@awarebydefault/display-case 1.0.0

package/src/ui/design-system/components/showcase/SegmentedToggle.case.tsx

@@ -0,0 +1,84 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { useState } from 'react'
+import { type SegmentedOption, SegmentedToggle } from './SegmentedToggle'
+
+const two: SegmentedOption<string>[] = [
+  { id: 'primer', label: 'Primer' },
+  { id: 'library', label: 'Cases' },
+]
+
+const three: SegmentedOption<string>[] = [
+  { id: 'light', label: 'Light' },
+  { id: 'auto', label: 'Auto' },
+  { id: 'dark', label: 'Dark' },
+]
+
+const five: SegmentedOption<string>[] = [
+  { id: 'xs', label: 'XS' },
+  { id: 'sm', label: 'SM' },
+  { id: 'md', label: 'MD' },
+  { id: 'lg', label: 'LG' },
+  { id: 'xl', label: 'XL' },
+]
+
+// SegmentedToggle is controlled, so each specimen owns its selected value —
+// click a segment in the stage and the thumb lerps to it, no tweaks needed.
+function Demo({
+  label,
+  options,
+  initial,
+}: {
+  label: string
+  options: SegmentedOption<string>[]
+  initial: string
+}) {
+  const [value, setValue] = useState(initial)
+  return (
+    <SegmentedToggle
+      label={label}
+      options={options}
+      value={value}
+      onChange={setValue}
+    />
+  )
+}
+
+export default defineCases(
+  'SegmentedToggle',
+  {
+    // The browse chrome swaps cases *in place* (one persistent render root), so a
+    // bare <Demo> would be reconciled as the same instance across cases and keep
+    // its stale `value` — which, between cases with different option ids, leaves
+    // no segment active. A distinct `key` per case forces a remount so each
+    // re-seeds from its own `initial`. (Same reason the Playground keys by count.)
+    Playground: {
+      tweaks: {
+        count: tweak.choice(['2', '3', '5'], '5'),
+      },
+      render: (t) => {
+        const byCount: Record<string, SegmentedOption<string>[]> = {
+          '2': two,
+          '3': three,
+          '5': five,
+        }
+        const options = byCount[t.count] ?? five
+        return (
+          <Demo
+            key={`pg-${t.count}`}
+            label="Size"
+            options={options}
+            initial={options[0].id}
+          />
+        )
+      },
+    },
+    Two: () => (
+      <Demo key="two" label="View mode" options={two} initial="library" />
+    ),
+    Three: () => (
+      <Demo key="three" label="Theme" options={three} initial="auto" />
+    ),
+    Five: () => <Demo key="five" label="Size" options={five} initial="lg" />,
+  },
+  { level: 'molecule' },
+)

package/src/ui/design-system/components/showcase/SegmentedToggle.css

@@ -0,0 +1,61 @@
+.dcui-segmented {
+  position: relative;
+  display: grid;
+  grid-template-columns: repeat(var(--seg-count), 1fr);
+  gap: var(--dc-space-1);
+  padding: var(--dc-space-1);
+  border: var(--dc-border-line);
+  border-radius: var(--dc-radius-sm);
+  background: var(--dc-bg);
+}
+/* The highlight box: one cell-wide thumb pinned inside the padding box. The gap
+   between cells (and the padding around them) is one --dc-space-1; its width is a
+   single grid cell — (track − the N+1 gaps) divided by N — so translating by its
+   own width plus one gap, times the active index, lands it exactly over any
+   segment. The transform transition does the linear lerp across the list. */
+.dcui-segmented-thumb {
+  position: absolute;
+  top: var(--dc-space-1);
+  bottom: var(--dc-space-1);
+  left: var(--dc-space-1);
+  width: calc(
+    (100% - (var(--seg-count) + 1) * var(--dc-space-1)) /
+    var(--seg-count)
+  );
+  transform: translateX(calc((100% + var(--dc-space-1)) * var(--seg-index)));
+  border-radius: calc(var(--dc-radius-sm) - 1px);
+  background: var(--dc-brand);
+  transition: transform var(--dc-transition-base);
+  pointer-events: none;
+}
+.dcui-segmented-seg {
+  position: relative;
+  z-index: 1;
+  appearance: none;
+  border: 0;
+  border-radius: calc(var(--dc-radius-sm) - 1px);
+  padding: var(--dc-space-2) var(--dc-space-4);
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  font-weight: var(--dc-weight-medium);
+  letter-spacing: var(--dc-tracking-label);
+  text-transform: uppercase;
+  color: var(--dc-fg-muted);
+  background: transparent;
+  cursor: pointer;
+  transition: color var(--dc-transition-base);
+}
+/* Only the inactive segments take a hover fill — the active one sits over the
+   thumb, which already carries the brand background. */
+.dcui-segmented-seg:not([data-active="true"]):hover {
+  color: var(--dc-fg);
+  background: var(--dc-hover);
+}
+.dcui-segmented-seg[data-active="true"] {
+  color: var(--dc-brand-fg);
+}
+@media (prefers-reduced-motion: reduce) {
+  .dcui-segmented-thumb {
+    transition: none;
+  }
+}

package/src/ui/design-system/components/showcase/SegmentedToggle.placard.md

@@ -0,0 +1,21 @@
+**SegmentedToggle** — an isolated, multi-option segmented control; reach for it whenever you're switching between a small fixed set of mutually-exclusive views or modes (2, 3, 5 — any count) and want the selection to slide rather than blink.
+
+```tsx
+<SegmentedToggle
+  label="View mode"
+  options={[
+    { id: 'primer', label: 'Primer' },
+    { id: 'library', label: 'Cases' },
+  ]}
+  value={mode}
+  onChange={setMode}
+/>
+```
+
+It's controlled: pass `value` (one option's `id`) and `onChange`. A single brand-filled thumb is sized to one cell and translated by the active index, so the highlight animates **linearly across the list** for any number of options — there is no per-count CSS. The geometry is driven by `--seg-count` / `--seg-index` set inline on the root; the transition respects `prefers-reduced-motion`.
+
+`label` is the tablist's accessible name (the control is `role="tablist"`, each segment `role="tab"`). Options render in array order. An unknown `value` parks the thumb on the first cell.
+
+Pass `testId(id)` for per-segment `data-testid`s (the sidebar mode switch uses `DcTestIds.modeSwitch`). Pass `className` for layout-context placement (e.g. the sidebar adds `dc-modeswitch` for pinning); the control's own appearance stays self-contained.
+
+For a single pill, reach for `Chip`; for a stepper with Prev/Next, `FlowNav`.

package/src/ui/design-system/components/showcase/SegmentedToggle.test.tsx

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { SegmentedToggle } from './SegmentedToggle'
+
+const options = [
+  { id: 'light', label: 'Light' },
+  { id: 'dark', label: 'Dark' },
+  { id: 'system', label: 'System' },
+] as const
+
+const noop = () => {}
+
+describe('SegmentedToggle', () => {
+  test('renders a labelled tablist of tabs', () => {
+    const html = renderToStaticMarkup(
+      <SegmentedToggle
+        options={[...options]}
+        value="light"
+        onChange={noop}
+        label="Theme"
+      />,
+    )
+    expect(html).toContain('role="tablist"')
+    expect(html).toContain('aria-label="Theme"')
+    expect((html.match(/role="tab"/g) ?? []).length).toBe(3)
+  })
+
+  test('marks the selected option as the active, selected tab', () => {
+    const html = renderToStaticMarkup(
+      <SegmentedToggle
+        options={[...options]}
+        value="dark"
+        onChange={noop}
+        label="Theme"
+      />,
+    )
+    // Exactly one tab is selected/active.
+    expect((html.match(/aria-selected="true"/g) ?? []).length).toBe(1)
+    expect((html.match(/data-active="true"/g) ?? []).length).toBe(1)
+  })
+
+  test('drives the thumb geometry from --seg-count and --seg-index', () => {
+    const html = renderToStaticMarkup(
+      <SegmentedToggle
+        options={[...options]}
+        value="system"
+        onChange={noop}
+        label="Theme"
+      />,
+    )
+    expect(html).toContain('--seg-count:3')
+    expect(html).toContain('--seg-index:2')
+  })
+
+  test('clamps an unknown value to the first cell rather than a negative index', () => {
+    const html = renderToStaticMarkup(
+      <SegmentedToggle
+        options={[...options]}
+        value={'gone' as never}
+        onChange={noop}
+        label="Theme"
+      />,
+    )
+    expect(html).toContain('--seg-index:0')
+    expect(html).not.toContain('aria-selected="true"')
+  })
+
+  test('applies a per-segment test id factory when given', () => {
+    const html = renderToStaticMarkup(
+      <SegmentedToggle
+        options={[...options]}
+        value="light"
+        onChange={noop}
+        label="Theme"
+        testId={(id) => `seg-${id}`}
+      />,
+    )
+    expect(html).toContain('data-testid="seg-light"')
+    expect(html).toContain('data-testid="seg-system"')
+  })
+})

package/src/ui/design-system/components/showcase/SegmentedToggle.tsx

@@ -0,0 +1,75 @@
+import type { CSSProperties, ReactNode } from 'react'
+
+/**
+ * Display Case — SegmentedToggle
+ * An isolated, multi-option segmented control. Takes any number of options and
+ * animates a single brand-filled thumb linearly from one to the next: the thumb
+ * is sized to one cell and translated by `index` cells, so the highlight lerps
+ * across the list however many options there are — no per-count CSS.
+ *
+ * The geometry is driven entirely by two custom properties set inline on the
+ * root (`--seg-count`, `--seg-index`); the CSS below is option-count agnostic.
+ */
+
+export interface SegmentedOption<T extends string> {
+  id: T
+  label: ReactNode
+}
+
+export interface SegmentedToggleProps<T extends string> {
+  /** The options, in display order. The thumb slides across them by index. */
+  options: SegmentedOption<T>[]
+  /** The currently selected option id. */
+  value: T
+  /** Called with the chosen option id when a segment is activated. */
+  onChange: (id: T) => void
+  /** Accessible name for the tablist (e.g. "View mode"). */
+  label: string
+  /** Optional className applied to the root, for layout-context placement. */
+  className?: string
+  /** Optional per-segment `data-testid` factory. */
+  testId?: (id: T) => string
+}
+
+export function SegmentedToggle<T extends string>({
+  options,
+  value,
+  onChange,
+  label,
+  className,
+  testId,
+}: SegmentedToggleProps<T>) {
+  // Clamp to 0 so an unknown `value` parks the thumb on the first cell rather
+  // than translating it off the track by a negative index.
+  const activeIndex = Math.max(
+    0,
+    options.findIndex((o) => o.id === value),
+  )
+  return (
+    <div
+      className={className ? `dcui-segmented ${className}` : 'dcui-segmented'}
+      role="tablist"
+      aria-label={label}
+      style={
+        {
+          '--seg-count': options.length,
+          '--seg-index': activeIndex,
+        } as CSSProperties
+      }>
+      <span className="dcui-segmented-thumb" aria-hidden="true" />
+      {options.map((opt) => (
+        <button
+          key={opt.id}
+          type="button"
+          role="tab"
+          aria-selected={value === opt.id}
+          className="dcui-segmented-seg"
+          data-testid={testId?.(opt.id)}
+          data-active={value === opt.id ? 'true' : undefined}
+          onClick={() => onChange(opt.id)}>
+          {opt.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/ui/design-system/components/showcase/Sidebar.case.tsx

@@ -0,0 +1,67 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { Eyebrow } from './Eyebrow'
+import { NavItem } from './NavItem'
+import { Sidebar } from './Sidebar'
+
+export default defineCases(
+  'Sidebar',
+  {
+    Playground: {
+      tweaks: {
+        label: tweak.text('Components'),
+        width: tweak.number(15),
+        maxHeight: tweak.number(24),
+        showEyebrow: tweak.boolean(true),
+      },
+      render: (t) => (
+        <Sidebar
+          label={t.label}
+          style={{ width: `${t.width}rem`, maxHeight: `${t.maxHeight}rem` }}>
+          {t.showEyebrow && (
+            <Eyebrow style={{ margin: '0 0 0.5rem 0.5rem' }}>Atoms</Eyebrow>
+          )}
+          <NavItem
+            kind="component"
+            label="Button"
+            count={4}
+            expanded
+            onToggle={() => {}}
+            onSelect={() => {}}
+          />
+          <NavItem kind="case" label="Playground" onSelect={() => {}} />
+          <NavItem kind="case" label="Variants" current onSelect={() => {}} />
+          <NavItem kind="case" label="Sizes" onSelect={() => {}} />
+          <NavItem
+            kind="component"
+            label="Checkbox"
+            onToggle={() => {}}
+            onSelect={() => {}}
+          />
+        </Sidebar>
+      ),
+    },
+    Tree: () => (
+      <Sidebar style={{ width: '15rem', maxHeight: '24rem' }}>
+        <Eyebrow style={{ margin: '0 0 0.5rem 0.5rem' }}>Atoms</Eyebrow>
+        <NavItem
+          kind="component"
+          label="Button"
+          count={4}
+          expanded
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+        <NavItem kind="case" label="Playground" onSelect={() => {}} />
+        <NavItem kind="case" label="Variants" current onSelect={() => {}} />
+        <NavItem kind="case" label="Sizes" onSelect={() => {}} />
+        <NavItem
+          kind="component"
+          label="Checkbox"
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+      </Sidebar>
+    ),
+  },
+  { level: 'organism' },
+)

package/src/ui/design-system/components/showcase/Sidebar.css

@@ -0,0 +1,6 @@
+.dcui-sidebar {
+  overflow-y: auto;
+  padding: var(--dc-space-6);
+  border-right: var(--dc-border-line);
+  background: var(--dc-bg-subtle);
+}

package/src/ui/design-system/components/showcase/Sidebar.placard.md

@@ -0,0 +1,14 @@
+**Sidebar** — the nav rail: a scrolling, hairline-bordered column on the subtle backdrop that holds the component tree; reach for it as the ground `NavItem` rows sit on (rows are transparent and only read correctly against this surface).
+
+```tsx
+<Sidebar label="Components">
+  <NavItem kind="component" label="Button" count={4} expanded onToggle={toggle} />
+  <NavItem kind="case" label="Variants" current onSelect={select} />
+</Sidebar>
+```
+
+Layout (grid placement, collapse) stays the chrome's; the surface is the component's.
+
+- **label**: accessible name for the `<nav>` landmark; pass the contextual name (default `"Navigation"` is a generic fallback)
+- **children**: `NavItem` rows (typically grouped by hierarchy level)
+- spreads remaining props onto the `<nav>`

package/src/ui/design-system/components/showcase/Sidebar.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { Sidebar } from './Sidebar'
+
+describe('Sidebar', () => {
+  test('renders a nav landmark with a generic default label', () => {
+    const html = renderToStaticMarkup(
+      <Sidebar>
+        <span>rows</span>
+      </Sidebar>,
+    )
+    expect(html).toContain('<nav')
+    expect(html).toContain('class="dcui-sidebar"')
+    expect(html).toContain('aria-label="Navigation"')
+    expect(html).toContain('rows')
+  })
+
+  test('uses a contextual landmark label when given', () => {
+    const html = renderToStaticMarkup(<Sidebar label="Components">x</Sidebar>)
+    expect(html).toContain('aria-label="Components"')
+  })
+
+  test('forwards arbitrary attributes to the nav element', () => {
+    const html = renderToStaticMarkup(
+      <Sidebar id="rail" data-testid="sidebar">
+        x
+      </Sidebar>,
+    )
+    expect(html).toContain('id="rail"')
+    expect(html).toContain('data-testid="sidebar"')
+  })
+})

package/src/ui/design-system/components/showcase/Sidebar.tsx

@@ -0,0 +1,30 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+
+/**
+ * Display Case — Sidebar
+ * The nav rail: a scrolling, hairline-bordered column on the subtle backdrop
+ * that holds the component tree. It's the ground NavItem rows are designed to
+ * sit on — the rows are transparent and only read correctly against this
+ * `--dc-bg-subtle` surface. Layout (grid placement, collapse) is the chrome's;
+ * the surface is the component's.
+ */
+
+export interface SidebarProps extends HTMLAttributes<HTMLElement> {
+  /** Accessible name for the nav landmark; consumers should pass the contextual
+   *  name (the chrome uses "Components"). Defaults to a generic fallback so the
+   *  landmark always has an accessible name. */
+  label?: string
+  children?: ReactNode
+}
+
+export function Sidebar({
+  label = 'Navigation',
+  children,
+  ...rest
+}: SidebarProps) {
+  return (
+    <nav className="dcui-sidebar" aria-label={label} {...rest}>
+      {children}
+    </nav>
+  )
+}

package/src/ui/design-system/components/showcase/Stage.case.tsx

@@ -0,0 +1,51 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { Button } from '../controls/Button'
+import { Stage } from './Stage'
+
+const box = { width: '24rem', height: '12rem' }
+
+export default defineCases(
+  'Stage',
+  {
+    Playground: {
+      tweaks: {
+        caption: tweak.text('button / playground'),
+        meta: tweak.text('390 × 844'),
+        grid: tweak.boolean(true),
+        corners: tweak.boolean(false),
+      },
+      render: (t) => (
+        <Stage
+          caption={t.caption || undefined}
+          meta={t.meta || undefined}
+          frame="fill"
+          grid={t.grid}
+          corners={t.corners}
+          style={box}>
+          <Button>On the stage</Button>
+        </Stage>
+      ),
+    },
+    Default: () => (
+      <Stage frame="fill" style={box}>
+        <Button>On the stage</Button>
+      </Stage>
+    ),
+    Grid: () => (
+      <Stage frame="fill" grid style={box}>
+        <Button variant="accent">On the grid</Button>
+      </Stage>
+    ),
+    Captioned: () => (
+      <Stage
+        caption="button / playground"
+        meta="390 × 844"
+        frame="fill"
+        grid
+        style={box}>
+        <Button>Captioned</Button>
+      </Stage>
+    ),
+  },
+  { level: 'molecule' },
+)

package/src/ui/design-system/components/showcase/Stage.css

@@ -0,0 +1,91 @@
+.dcui-stage {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  border: 1px solid var(--dc-border);
+  border-radius: var(--dc-radius-md);
+  background: var(--dc-surface);
+  overflow: hidden;
+}
+/* Live-frame sizing (the browse chrome's preview). */
+.dcui-stage[data-frame="hug"] {
+  flex: 0 0 auto;
+  min-width: min(22rem, 100%);
+  min-height: min(11rem, 100%);
+  max-width: 100%;
+  max-height: 100%;
+}
+.dcui-stage[data-frame="fill"] {
+  align-self: stretch;
+  width: 100%;
+}
+.dcui-stage-caption {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--dc-space-4);
+  padding: var(--dc-space-4) var(--dc-space-6);
+  border-bottom: 1px solid var(--dc-border);
+  background: var(--dc-bg-subtle);
+}
+.dcui-stage-caption-label {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  font-weight: var(--dc-weight-medium);
+  letter-spacing: var(--dc-tracking-label);
+  text-transform: uppercase;
+  color: var(--dc-fg-muted);
+}
+.dcui-stage-caption-meta {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  color: var(--dc-fg-subtle);
+}
+.dcui-stage-body {
+  position: relative;
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 0;
+  padding: 0;
+}
+/* hug-frame sets the body padding inline (the dynamic grid margin); a filled
+   frame stays edge-to-edge. */
+.dcui-stage[data-grid="true"] .dcui-stage-body {
+  background-image: radial-gradient(var(--dc-border) 1px, transparent 1px);
+  background-size: 16px 16px;
+  background-position: -1px -1px;
+}
+.dcui-stage-corner {
+  position: absolute;
+  width: 9px;
+  height: 9px;
+  border: 1.5px solid var(--dc-border-strong);
+  pointer-events: none;
+  z-index: 1;
+}
+.dcui-stage-corner[data-c="tl"] {
+  top: 8px;
+  left: 8px;
+  border-right: 0;
+  border-bottom: 0;
+}
+.dcui-stage-corner[data-c="tr"] {
+  top: 8px;
+  right: 8px;
+  border-left: 0;
+  border-bottom: 0;
+}
+.dcui-stage-corner[data-c="bl"] {
+  bottom: 8px;
+  left: 8px;
+  border-right: 0;
+  border-top: 0;
+}
+.dcui-stage-corner[data-c="br"] {
+  bottom: 8px;
+  right: 8px;
+  border-left: 0;
+  border-top: 0;
+}

package/src/ui/design-system/components/showcase/Stage.placard.md

@@ -0,0 +1,15 @@
+**Stage** — the vitrine: the framed surface a component is exhibited on (hairline border, soft corner ticks, optional dotted grid, optional mono caption); reach for it to present one component. Keep it quiet — the exhibit leads.
+
+The browse chrome's preview stage, sized by `frame` rather than centering a card. `frame="hug"` shrinks to the exhibit with a minimum size and a dynamic grid margin (`padX`/`padY`, in px); `frame="fill"` stretches edge-to-edge for full pages.
+
+```tsx
+<Stage frame="hug" padX={48} padY={32} surface="var(--color-bg)">
+  <App />
+</Stage>
+```
+
+- **frame** (required): `hug` (shrink to the exhibit) · `fill` (stretch edge-to-edge)
+- **caption** / **meta**: mono caption strip (label left, meta right)
+- **grid**: dotted graph-paper backdrop · **corners**: corner ticks (default on)
+- **padX** / **padY**: dynamic grid-margin padding (px) for `frame="hug"`
+- **surface**: override the body backdrop colour