@mattstack/glance-react

@forge-glance/react

React component library for Forge Glance — pre-themed MR dashboards, CI badges, and base primitives powered by the GDS design system.

Install

npm install @forge-glance/react @forge-glance/sdk
# or
bun add @forge-glance/react @forge-glance/sdk

Quick Start

import '@forge-glance/react/styles.css';
import { MRCard, Button, Badge } from '@forge-glance/react';

The CSS import brings in all tokens, utilities, and component styles — no Tailwind required on your end.

Dashboard Integration

The dashboard API provides real-time MR data and pre-bound mutation actions. There are three integration patterns depending on your architecture:

1. React Hook — useDashboard

The simplest approach for standard React apps. Handles the subscription lifecycle and state internally.

import '@forge-glance/react/styles.css';
import { useDashboard, MRCard, MRRow } from '@forge-glance/react';

function MergeRequestDashboard({ provider, projectPath, mrIid, userId }) {
  const { mr, actions, status } = useDashboard({
    provider, projectPath, mrIid, userId
  });

  if (status === 'connecting' || !mr) return <p>Loading…</p>;

  // Full card view — status, pipeline, reviewers, merge/rebase actions
  return <MRCard mr={mr} actions={actions} />;

  // Or use the compact row view — same props, different layout
  // return <MRRow mr={mr} actions={actions} />;
}

useDashboard returns:

Field	Type	Description
mr	MRDashboardProps | null	Render-ready props. null until first update.
actions	MRDashboardActions	Pre-bound mutations (merge, rebase, approve, etc.)
status	'connecting' | 'watching'	Subscription state

2. SDK + State Manager (Zustand, Redux, etc.)

Use createDashboard from the SDK directly when you manage state outside React (e.g., Zustand stores).

import { createDashboard } from '@forge-glance/sdk';
import { create } from 'zustand';
import type { MRDashboardProps, MRDashboardActions } from '@forge-glance/sdk';

// Create the store
const useMRStore = create<{
  mr: MRDashboardProps | null;
  actions: MRDashboardActions | null;
}>(() => ({
  mr: null,
  actions: null,
}));

// Wire up the dashboard — call once on mount
const { actions, subscribe, dispose } = createDashboard({
  provider, projectPath: 'group/project', mrIid: 42, userId
});

// actions is available immediately — stable reference
useMRStore.setState({ actions });

// subscribe feeds real-time MR updates into the store
subscribe((mr) => useMRStore.setState({ mr }));

// Later, when tearing down:
dispose();

Then in your React component:

import '@forge-glance/react/styles.css';
import { MRCard } from '@forge-glance/react';

function Dashboard() {
  const mr = useMRStore((s) => s.mr);
  const actions = useMRStore((s) => s.actions);

  if (!mr) return <p>Loading…</p>;

  return <MRCard mr={mr} actions={actions} />;
}

3. Read-Only (no actions)

For displaying MR data without mutation buttons, simply omit the actions prop:

import { useDashboard, MRCard } from '@forge-glance/react';

function ReadOnlyCard({ provider, projectPath, mrIid, userId }) {
  const { mr } = useDashboard({ provider, projectPath, mrIid, userId });

  if (!mr) return <p>Loading…</p>;

  // No actions prop → buttons are hidden / disabled
  return <MRCard mr={mr} />;
}

4. Multi-MR Dashboard (shared WebSocket)

Watch multiple MRs over a single connection:

import { createDashboard } from '@forge-glance/sdk';
import { MRRow } from '@forge-glance/react';

const { actionsFor, subscribe, dispose } = createDashboard({
  provider, projectPath: 'group/project',
  mrIid: [42, 43, 44, 45],
  userId
});

subscribe((mrs) => {
  for (const [iid, mr] of mrs) {
    renderRow(mr, actionsFor(iid));
  }
});

createDashboard Return Shape

const { actions, subscribe, dispose } = createDashboard(provider, path, iid, userId);

Property	Type	Description
actions	MRDashboardActions	Pre-bound mutations — available immediately
subscribe(cb)	(listener: (mr: MRDashboardProps) => void) => void	Register a listener for real-time MR updates
dispose()	() => void	Stop the subscription and clean up

MRDashboardActions

Actions are pre-bound to the specific MR — no need to pass project path or IID:

Action	Description
merge(input?)	Merge the MR (optional merge options)
rebase()	Rebase onto target branch
approve()	Approve the MR
unapprove()	Remove your approval
setAutoMerge()	Enable auto-merge when pipeline passes
cancelAutoMerge()	Cancel auto-merge
retryPipeline(id)	Retry a specific pipeline
requestReReview(usernames?)	Request re-review
can	Provider capability flags

Components

Forge Components

Built for GitLab/GitHub merge request dashboards. Feed them MRDashboardProps from @forge-glance/sdk.

Component	Description
MRCard	Full MR card — status, pipeline, reviewers, merge/rebase actions, forge icon link
MRRow	Compact MR row for list views
MRRowList	Renders a list of MRRow items
MRStatusBadge	Status badge — mergeable, blocked, draft, merged, closed
PipelineBadge	CI pipeline badge — passing, failing, running, warnings
ReviewerList	Reviewer avatars with approval state badges
ReviewerRow	Single reviewer row (used by ReviewerList)

Both MRCard and MRRow accept an optional actions prop. When provided, the SDK actions take precedence over individual onMerge/onRebase callbacks (which still work for backward compatibility).

Brand Icons

import { GitLabIcon, GitHubIcon, IconButton } from '@forge-glance/react';

<IconButton variant="ghost" aria-label="Open in GitLab">
  <GitLabIcon className="size-4" />
</IconButton>

Component	Description
GitLabIcon	GitLab tanuki logo (official brand colors)
GitHubIcon	GitHub octocat logo (uses currentColor)
IconButton	Square icon-only button wrapper — supports all Button variants and colors

Base Primitives

Themed variants of common UI elements. Built on Radix UI + CVA.

Component	Variants	Colors
Button	filled outline subtle ghost link	emphasis action positive negative caution merge neutral
IconButton	filled outline subtle ghost	emphasis action positive negative caution merge neutral
Badge	filled outline subtle	emphasis action positive negative caution merge neutral
Switch	—	—
Tooltip	—	—

Theming

Light / Dark Mode

Toggle by adding .dark to your <html> element:

document.documentElement.classList.toggle('dark');

Using Tokens in Your Own Tailwind Setup

If you want to use the GDS tokens as Tailwind utilities in your own code, import tokens.css instead of styles.css:

@import 'tailwindcss';
@import '@forge-glance/react/tokens.css';

@theme inline {
  --color-positive: var(--positive);
  --color-negative: var(--negative);
  --color-caution: var(--caution);
  /* register whichever tokens you need */
}

Overriding Tokens

All component colors are CSS custom properties — override any token to retheme:

:root {
  --positive: oklch(0.72 0.22 145);
  --btn-merge: oklch(0.55 0.20 280);
}

SDK Types

Common types are re-exported so you don't need to install @forge-glance/sdk separately for types:

import type {
  MRDashboardProps,
  MRDashboardActions,
  Dashboard,
  MRStatus,
  Reviewer,
} from '@forge-glance/react';

Development

bun install
bun run dev:app        # demo app (imports from source)
bun storybook          # component playground on :6006
bun run build          # production build → dist/

Releasing

This package uses @changesets/cli for independent versioning:

bun changeset          # create a changeset after making changes
bun run version        # apply changesets → bump versions + changelogs
bun run release        # build + npm publish + git tags

License

MIT