@awarebydefault/display-case 1.0.0

package/src/ui/design-system/components/shell/A11yPage.case.tsx

@@ -0,0 +1,237 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { useState } from 'react'
+import type { A11yViolation } from '../../../../index'
+import { Button, Input, RenderAddress } from '..'
+import { ShellView } from './ShellView'
+import {
+  makeModel,
+  mockA11y,
+  mockA11yClean,
+  mockA11yLeaf,
+  mockA11yPending,
+  mockA11yPerVariant,
+  mockA11yScrolling,
+  mockManifest,
+  PLACEHOLDER_DOC,
+  StageSlot,
+  selectIn,
+} from './shell-fixtures'
+
+// The resolved audit the "Re-scan" exhibit returns to after its simulated scan.
+const RESCAN_RESULT = mockA11y()
+
+/**
+ * Interactive "re-scan" exhibit: the panel's ⟳ control forces a fresh audit. We
+ * simulate the live cycle locally — clicking re-scan flips the verdict to the
+ * pulsing "Scanning…" state, then resolves back to the violations after a beat —
+ * exactly what `useShell.rescanA11y` does against the real scanner.
+ */
+function RescanDemo() {
+  const [current, setCurrent] = useState<
+    A11yViolation[] | 'pending' | 'unavailable'
+  >(RESCAN_RESULT.current)
+  // Initial render = already-scanned → fade in at once; a re-scan resolves from
+  // "Scanning…" → cascade (mirrors useShell driving `reveal` off the scan).
+  const [reveal, setReveal] = useState<'cascade' | 'all'>('all')
+  const rescan = () => {
+    setReveal('cascade')
+    setCurrent('pending')
+    setTimeout(() => setCurrent(RESCAN_RESULT.current), 1200)
+  }
+  return (
+    <ShellView
+      {...makeModel({
+        ...selectIn(mockManifest, 'input', 'default'),
+        a11y: { byVariant: RESCAN_RESULT.byVariant, current, reveal },
+        rescanA11y: rescan,
+        boxW: 260,
+        boxH: 96,
+      })}
+      renderFrame={
+        <StageSlot>
+          <Input placeholder="Email address" aria-label="Email address" />
+        </StageSlot>
+      }
+      primerFrame={null}
+    />
+  )
+}
+
+/**
+ * A real page proving where accessibility violations surface in the browse
+ * chrome — the proposal made concrete. Two complementary surfaces:
+ *
+ *  - **Discoverable** — danger markers on the nav rail. Violations belong to a
+ *    *variant*, so a collapsed component shows the sum across its variants;
+ *    expanded, the per-variant counts move onto the case rows and the parent
+ *    shows a plain dot (see the "Per-variant breakdown" case).
+ *  - **Visible** — the Accessibility panel under the stage, listing the selected
+ *    variant's violations (rule id, help text, node count) instead of leaving
+ *    them buried in the `display-case check` CLI log. Its header carries a
+ *    show/hide toggle and stays pinned while the list scrolls; it sits below the
+ *    Tweaks panel (the audit is the consequence of the tweaked state).
+ *
+ * Wiring `useShell` to feed live audit results into this same `a11y` field is the
+ * follow-up; the chrome that renders them is what this page proves.
+ */
+export default defineCases(
+  'A11y page',
+  {
+    Default: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'input', 'default'),
+          a11y: mockA11y(),
+          boxW: 260,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Input placeholder="Email address" aria-label="Email address" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // The panel's ⟳ re-scan control — click it to force a fresh audit (flips to
+    // "Scanning…", then resolves). Mirrors useShell.rescanA11y in the live app.
+    'Re-scan': () => <RescanDemo />,
+    // A11y configured, but the active variant's scan is still in flight: the
+    // panel shows its calm "Scanning…" state (neutral accent, no toggle) and no
+    // nav markers have landed yet.
+    Scanning: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'input', 'default'),
+          a11y: mockA11yPending(),
+          boxW: 260,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Input placeholder="Email address" aria-label="Email address" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // A11y configured and everything is clean: no nav markers, and the panel
+    // shows its reassuring all-green pass state.
+    'All clear': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'input', 'default'),
+          a11y: mockA11yClean(),
+          boxW: 260,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Input placeholder="Email address" aria-label="Email address" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // A11y NOT configured (no `a11y` on the model): no nav markers and no panel
+    // at all — the chrome is exactly as it was before the feature.
+    'Not configured': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'input', 'default'),
+          boxW: 260,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Input placeholder="Email address" aria-label="Email address" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // A selected single-case leaf: RenderAddress has one variant, so it renders
+    // as a leaf (no chevron, no case rows). With no children to defer to, its
+    // lone variant's count sits directly on the (selected, marigold) leaf row —
+    // never a dot. The Accessibility panel lists that variant's violations.
+    'Single-case leaf': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'render-address', 'default'),
+          a11y: mockA11yLeaf(),
+          boxW: 360,
+          boxH: 64,
+        })}
+        renderFrame={
+          <StageSlot>
+            <RenderAddress url="https://display-case.dev/render/render-address/default?theme=light" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // The per-variant nav breakdown: `button` is expanded, so its parent row
+    // shows a plain dot while its three variants carry their own counts
+    // (Playground 2, Variants 5, Sizes clean). The other components stay
+    // collapsed, showing their summed counts — the contrast the rail draws.
+    'Per-variant breakdown': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'variants'),
+          a11y: mockA11yPerVariant(),
+          boxW: 280,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Button variant="ghost">Low-contrast label</Button>
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // A case with more violations than the panel's height cap, so the list
+    // scrolls internally while the "ACCESSIBILITY" header stays pinned. Use the
+    // header's toggle to collapse the (long) list.
+    Scrolling: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'input', 'default'),
+          a11y: mockA11yScrolling(),
+          boxW: 260,
+          boxH: 96,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Input placeholder="Email address" aria-label="Email address" />
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+    // Everything open at once — stage + tweaks panel + a11y panel + docs panel —
+    // to see how the surfaces coexist on a crowded page. The Button atom (which
+    // has a placard-doc and a tweakable Playground) is selected, so the chosen nav
+    // row genuinely carries violations. The docked tweaks panel can be collapsed
+    // (its header chevron) to give the content column back to the stage.
+    'With tweaks and docs': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'playground'),
+          a11y: mockA11y(),
+          docOpen: true,
+          docText: PLACEHOLDER_DOC,
+          boxW: 240,
+          boxH: 120,
+        })}
+        renderFrame={
+          <StageSlot>
+            <Button>Save changes</Button>
+          </StageSlot>
+        }
+        primerFrame={null}
+      />
+    ),
+  },
+  { level: 'page' },
+)

package/src/ui/design-system/components/shell/A11yPage.placard.md

@@ -0,0 +1,15 @@
+**A11y page** — the Cases chrome with accessibility surfacing on: the page that proves where a11y results appear — per-variant markers in the nav rail and the Accessibility panel below the stage.
+
+Behaviour, by case — each is the live [A11yPanel](../showcase/A11yPanel.placard.md) and [A11yBadge](../showcase/A11yBadge.placard.md) fed a static model, so it shows one state of the surface:
+
+- **Default** — a violations verdict: the panel lists the findings impact-sorted (worst first), nav rows carry counts.
+- **Scanning** — a scan in flight: the pulsing "Scanning…" bar, no markers yet.
+- **All clear** — a clean pass: the green bar, no nav markers anywhere.
+- **Not configured** — a11y omitted from the model: no panel and no markers at all (the chrome exactly as before the feature).
+- **Single-case leaf** — a one-variant component shows its count directly on the leaf row (never a dot).
+- **Per-variant breakdown** — an expanded component shows a plain dot while its case rows carry the per-variant counts; collapsed siblings show their summed count.
+- **Scrolling** — a long violation list scrolls inside the height-capped panel, under the sticky header.
+- **Re-scan** — the panel's ⟳ control forces a fresh audit: flips to "Scanning…", then resolves (mirrors the live `rescanA11y`).
+- **With tweaks and docs** — the panel coexisting with the Tweaks and Docs panels on a crowded page.
+
+For how the live server feeds these states (on-demand scan, cache, SSE), see the package's Configuration guide (the `a11y` option) and the `display-case-live-a11y` change.

package/src/ui/design-system/components/shell/CaseTemplate.case.tsx

@@ -0,0 +1,32 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { ShellView } from './ShellView'
+import {
+  caseTemplateSelection,
+  makeModel,
+  PlaceholderExhibit,
+} from './shell-fixtures'
+
+/**
+ * The Cases layout as a *template*: the chrome's header, nav rail, stage, tweaks
+ * panel, and docs panel arranged around placeholder content. It shows the shape
+ * a case page takes before any real component, tweak, or doc fills it — the
+ * empty template a {@link defineCases} page is poured into.
+ */
+export default defineCases(
+  'Case template',
+  {
+    Default: () => (
+      <ShellView
+        {...makeModel({
+          ...caseTemplateSelection(),
+          docText: '_Placeholder documentation lives here._',
+          boxW: 260,
+          boxH: 150,
+        })}
+        renderFrame={<PlaceholderExhibit />}
+        primerFrame={null}
+      />
+    ),
+  },
+  { level: 'template' },
+)

package/src/ui/design-system/components/shell/CaseTemplate.placard.md

@@ -0,0 +1,5 @@
+**Case template** — the Cases (library) layout with no real data: the empty shape every `defineCases` page is poured into. Reach for it to see the chrome's regions before any component fills them.
+
+Regions: **header** (wordmark · device/zoom/grid controls · theme toggle) · **nav rail** (the component tree, grouped by hierarchy level) · **stage** (the centred exhibit, with its shareable `/render` address above) · **Tweaks panel** (the case's live controls, docked under the stage) · **Docs panel** (the selected component's `.placard.md`, on the right when open).
+
+Use this to read the library layout itself. For the reading-mode layout instead, reach for [Primer template](./PrimerTemplate.placard.md). Filled with a live component, a tweak, and prose, it's exhibited in the [Cases page](./CasesPage.placard.md) (its "With tweaks and docs" variant).

package/src/ui/design-system/components/shell/CasesPage.case.tsx

@@ -0,0 +1,141 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { Button } from '..'
+import { ShellView } from './ShellView'
+import {
+  FlowStep,
+  makeModel,
+  mockManifest,
+  PageScreen,
+  PLACEHOLDER_DOC,
+  StageSlot,
+  selectIn,
+} from './shell-fixtures'
+
+/**
+ * A real page: the Cases chrome (the library view) browsing the mock manifest,
+ * with a live exhibit on the stage. The variants pour the same page full to
+ * different depths and show how the stage adapts to what it's browsing:
+ *
+ * - **Default / With tweaks / With docs / With tweaks and docs** — browsing the
+ *   Button atom; the tweaks panel rides alongside when the case carries a
+ *   schema, the docs panel opens when the component has a placard-doc.
+ * - **Page** — browsing a page-level component, where the stage drops its grid
+ *   and padding to let the screen fill edge to edge.
+ * - **Flow** — browsing a flow, where the FlowNav stepper appears above the
+ *   stage and it fills edge to edge.
+ *
+ * The Primer reading view is its own page — see Primer page.
+ */
+
+// The Variants case content — the stage for the bare/docs exhibits, which select
+// the schema-less "Variants" case.
+const variantsExhibit = (
+  <StageSlot>
+    <div style={{ display: 'flex', gap: '0.5rem' }}>
+      <Button>Save changes</Button>
+      <Button variant="accent">Publish</Button>
+      <Button variant="ghost">Cancel</Button>
+    </div>
+  </StageSlot>
+)
+
+// The Playground case's stage at its default tweak values (variant 'ghost', size
+// 'md', label 'Button') — the single button the tweaks panel's controls drive.
+// The exhibits that select "Playground" put this on the stage, so the controls
+// and the staged button agree.
+const playgroundExhibit = (
+  <StageSlot>
+    <Button>Button</Button>
+  </StageSlot>
+)
+
+export default defineCases(
+  'Cases page',
+  {
+    // The bare stage: the Variants case has no tweak schema and docs stay closed.
+    Default: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'variants'),
+          boxW: 280,
+          boxH: 120,
+        })}
+        renderFrame={variantsExhibit}
+        primerFrame={null}
+      />
+    ),
+    // Tweaks revealed: the Playground case carries a tweak schema, so the docked
+    // TweaksPanel rides alongside the stage — its controls at their defaults,
+    // driving the Playground button on the stage.
+    'With tweaks': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'playground'),
+          boxW: 280,
+          boxH: 120,
+        })}
+        renderFrame={playgroundExhibit}
+        primerFrame={null}
+      />
+    ),
+    // Documentation revealed: the Button component has a placard-doc, so opening
+    // the docs panel pours real prose into the aside.
+    'With docs': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'variants'),
+          docOpen: true,
+          docText: PLACEHOLDER_DOC,
+          boxW: 280,
+          boxH: 120,
+        })}
+        renderFrame={variantsExhibit}
+        primerFrame={null}
+      />
+    ),
+    // The page at its fullest: the Playground case's tweaks panel and the open
+    // docs panel flank the Playground button on the stage.
+    'With tweaks and docs': () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'button', 'playground'),
+          docOpen: true,
+          docText: PLACEHOLDER_DOC,
+          boxW: 280,
+          boxH: 120,
+        })}
+        renderFrame={playgroundExhibit}
+        primerFrame={null}
+      />
+    ),
+    // Browsing a page: a page-level component flips `stageDecor` off, so the
+    // stage drops its grid, corner ticks, and padding (and the header's Grid
+    // button), and `fillFrame` lets the screen fill the whole stage edge to edge
+    // rather than sitting in a centred box.
+    Page: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'cases-page', 'default'),
+          stageDecor: false,
+        })}
+        fillFrame
+        renderFrame={<PageScreen />}
+        primerFrame={null}
+      />
+    ),
+    // Browsing a flow: a flow component shows the FlowNav stepper above the stage
+    // (one tab per step) and, like a page, fills the whole stage edge to edge.
+    Flow: () => (
+      <ShellView
+        {...makeModel({
+          ...selectIn(mockManifest, 'sign-in', 'request-link'),
+          stageDecor: false,
+        })}
+        fillFrame
+        renderFrame={<FlowStep />}
+        primerFrame={null}
+      />
+    ),
+  },
+  { level: 'page' },
+)

package/src/ui/design-system/components/shell/CasesPage.placard.md

@@ -0,0 +1,12 @@
+**Cases page** — the Cases (library) chrome browsing the mock manifest: the [Case template](./CaseTemplate.placard.md) poured full, with a live exhibit on the stage. The consolidated dogfood of everything the library view does.
+
+Behaviour, by case — each shows how the stage adapts to *what it's browsing*:
+
+- **Default** — browsing a schema-less case (Button → Variants): bare stage, no tweaks or docs panel.
+- **With tweaks** — browsing a case that carries a tweak schema (Button → Playground): the docked Tweaks panel rides alongside, its controls at their defaults driving the staged button.
+- **With docs** — the component has a placard-doc, so the Docs panel opens with real prose.
+- **With tweaks and docs** — the fullest case: Tweaks panel and open Docs panel flanking the stage.
+- **Page** — browsing a page-level component: the stage drops its grid, corner ticks, and padding (and the header's Grid button), and fills edge-to-edge.
+- **Flow** — browsing a flow: the FlowNav stepper appears above the stage (one tab per step) and, like a page, fills edge-to-edge.
+
+A static snapshot per variant (the nav/controls don't route here). The reading view is its own page — see [Primer page](./PrimerPage.placard.md).

package/src/ui/design-system/components/shell/PrimerPage.case.tsx

@@ -0,0 +1,22 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { ShellView } from './ShellView'
+import { makeModel, RealPrimer } from './shell-fixtures'
+
+/**
+ * The Primer *page*: the Primer template filled with the real reading page —
+ * actual prose and live {@link Display} specimens rendered into the host. This
+ * is what the Primer template becomes once a consumer authors its `.mdx`.
+ */
+export default defineCases(
+  'Primer page',
+  {
+    Default: () => (
+      <ShellView
+        {...makeModel({ mode: 'primer', shownMode: 'primer' })}
+        renderFrame={null}
+        primerFrame={<RealPrimer />}
+      />
+    ),
+  },
+  { level: 'page' },
+)

package/src/ui/design-system/components/shell/PrimerPage.placard.md

@@ -0,0 +1,3 @@
+**Primer page** — the [Primer template](./PrimerTemplate.placard.md) filled with the real reading page: actual prose and live `Display` specimens in the reading host. What the template becomes once a consumer authors its `.mdx`.
+
+Behaviour: the chrome is in Primer (reading) mode — the table-of-contents nav lists the page's sections and the host renders the wall text with specimens embedded inline. The mode switch flips to the library; walking that change is the [Primer to Cases](./ShellView.placard.md) flow.

package/src/ui/design-system/components/shell/PrimerTemplate.case.tsx

@@ -0,0 +1,22 @@
+import { defineCases } from '@awarebydefault/display-case'
+import { ShellView } from './ShellView'
+import { makeModel, PlaceholderPrimer } from './shell-fixtures'
+
+/**
+ * The Primer layout as a *template*: the chrome in reading mode — the mode
+ * switch, the table-of-contents nav, and the reading host — wrapped around a
+ * skeleton standing in for the long-form wall text and its specimens.
+ */
+export default defineCases(
+  'Primer template',
+  {
+    Default: () => (
+      <ShellView
+        {...makeModel({ mode: 'primer', shownMode: 'primer' })}
+        renderFrame={null}
+        primerFrame={<PlaceholderPrimer />}
+      />
+    ),
+  },
+  { level: 'template' },
+)

package/src/ui/design-system/components/shell/PrimerTemplate.placard.md

@@ -0,0 +1,5 @@
+**Primer template** — the chrome in reading mode with no real data: the layout a Primer `.mdx` pours into. Reach for it to see the reading-mode regions before the wall text fills them.
+
+Regions: the **Primer / Cases mode switch** (top of the sidebar) · the **table-of-contents nav** (the page's sections, one accordion group open at a time) · the **reading host** (long-form prose with inline live specimens). No stage, Tweaks, or Docs panel — those are Cases-mode only.
+
+Use this to read the reading-mode layout. For the library layout instead, reach for [Case template](./CaseTemplate.placard.md). Filled with real prose and specimens it becomes the [Primer page](./PrimerPage.placard.md).

package/src/ui/design-system/components/shell/ShellView.case.tsx

@@ -0,0 +1,57 @@
+import { defineFlow } from '@awarebydefault/display-case'
+import { Button } from '..'
+import { ShellView } from './ShellView'
+import { makeModel, RealPrimer, StageSlot } from './shell-fixtures'
+
+/**
+ * The headline dogfood: Display Case's own Primer ↔ Cases view change, exhibited
+ * as a flow. Each step is the pure {@link ShellView} fed a static model — the
+ * Primer step shows the reading page, the Cases step shows the library — and the
+ * sidebar's mode switch is wired to the flow's `goto`, so clicking it walks the
+ * flow exactly as it walks the live chrome.
+ */
+export default defineFlow('Primer to Cases', {
+  steps: {
+    'Primer view': {
+      transitions: ['Cases view'],
+      render: ({ goto }) => (
+        <ShellView
+          {...makeModel({
+            mode: 'primer',
+            shownMode: 'primer',
+            setMode: (m) => {
+              if (m === 'library') goto('Cases view')
+            },
+          })}
+          renderFrame={null}
+          primerFrame={<RealPrimer />}
+        />
+      ),
+    },
+    'Cases view': {
+      transitions: ['Primer view'],
+      render: ({ goto }) => (
+        <ShellView
+          {...makeModel({
+            mode: 'library',
+            shownMode: 'library',
+            boxW: 240,
+            boxH: 120,
+            setMode: (m) => {
+              if (m === 'primer') goto('Primer view')
+            },
+          })}
+          renderFrame={
+            <StageSlot>
+              <div style={{ display: 'flex', gap: '0.5rem' }}>
+                <Button>Save changes</Button>
+                <Button variant="accent">Publish</Button>
+              </div>
+            </StageSlot>
+          }
+          primerFrame={null}
+        />
+      ),
+    },
+  },
+})

package/src/ui/design-system/components/shell/ShellView.placard.md

@@ -0,0 +1,5 @@
+**Primer to Cases** — Display Case's own Primer ↔ Cases view change, walked as a flow. The headline dogfood: the same pure `ShellView` the live chrome renders, fed a static model per step.
+
+Steps, in order: `primer-view` (reading mode — the Primer wall text with live specimens) ↔ `cases-view` (the library — a component on the stage).
+
+Advances when: the sidebar's **Primer / Cases mode switch** is clicked — each step wires it to the flow's `goto`, so clicking it transitions to the other step exactly as the live chrome crossfades between the two views. A two-step loop with no terminal state: walk it in either direction, or deep-link to a single step to snapshot just that view.