@awarebydefault/display-case 1.0.0

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

@@ -0,0 +1,19 @@
+import { type A11yImpact, defineCases } from '@awarebydefault/display-case'
+import { ImpactTag } from './ImpactTag'
+
+const IMPACTS: A11yImpact[] = ['critical', 'serious', 'moderate', 'minor']
+
+export default defineCases(
+  'ImpactTag',
+  {
+    // The full severity scale, worst → least (the order a sorted list shows).
+    'All severities': () => (
+      <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+        {IMPACTS.map((impact) => (
+          <ImpactTag key={impact} impact={impact} />
+        ))}
+      </div>
+    ),
+  },
+  { level: 'atom' },
+)

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

@@ -0,0 +1,36 @@
+.dcui-impact-tag {
+  flex: 0 0 auto;
+  align-self: center;
+  min-width: 4.2rem;
+  text-align: center;
+  padding: 0 var(--dc-space-2);
+  border-radius: var(--dc-radius-sm);
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-2xs);
+  font-weight: var(--dc-weight-medium);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  /* Each severity carries its own text colour so the fill+text pair clears AA
+     theme-independently — a single --dc-brand-fg (white in light, ink in dark)
+     could not, since the fills span a light amber to a dark red. The fills are
+     the fixed ramp hues (not theme tokens), so the gradient — critical hottest
+     → minor coolest — and the contrast both hold in light and dark alike. */
+  color: #ffffff;
+  background: var(--dc-paper-700);
+}
+.dcui-impact-tag[data-impact="critical"] {
+  background: var(--dc-red-700);
+  color: #ffffff;
+}
+.dcui-impact-tag[data-impact="serious"] {
+  background: var(--dc-red-600);
+  color: #ffffff;
+}
+.dcui-impact-tag[data-impact="moderate"] {
+  background: var(--dc-amber-500);
+  color: var(--dc-paper-900);
+}
+.dcui-impact-tag[data-impact="minor"] {
+  background: var(--dc-paper-700);
+  color: #ffffff;
+}

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

@@ -0,0 +1,14 @@
+**ImpactTag** — a severity tag for an accessibility violation, colour-graded by axe `impact` so the worst findings read hottest. Used in the [A11yPanel](./A11yPanel.placard.md) violation list.
+
+```tsx
+<ImpactTag impact="critical" />
+<ImpactTag impact="serious" />
+```
+
+`impact` is one of `critical` · `serious` · `moderate` · `minor` (the `A11yImpact` type). critical is the deepest red, minor the calmest.
+
+The companion `impactRank(impact)` returns a sort key (worst = 0, unclassified last) — sort a violation list with it before mapping each to a tag:
+
+```tsx
+[...violations].sort((a, b) => impactRank(a.impact) - impactRank(b.impact))
+```

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

@@ -0,0 +1,40 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { ImpactTag, impactRank } from './ImpactTag'
+
+describe('impactRank', () => {
+  test('orders the impacts worst-first', () => {
+    expect(impactRank('critical')).toBeLessThan(impactRank('serious'))
+    expect(impactRank('serious')).toBeLessThan(impactRank('moderate'))
+    expect(impactRank('moderate')).toBeLessThan(impactRank('minor'))
+  })
+
+  test('sorts an unclassified (null) impact last', () => {
+    expect(impactRank(null)).toBeGreaterThan(impactRank('minor'))
+  })
+
+  test('is usable as an Array.sort comparator', () => {
+    const sorted = ['minor', 'critical', 'moderate', 'serious'].sort(
+      (a, b) => impactRank(a as never) - impactRank(b as never),
+    )
+    expect(sorted).toEqual(['critical', 'serious', 'moderate', 'minor'])
+  })
+})
+
+describe('ImpactTag', () => {
+  test('labels the tag with the impact and grades it via data-impact', () => {
+    const html = renderToStaticMarkup(<ImpactTag impact="critical" />)
+    expect(html).toContain('data-impact="critical"')
+    expect(html).toContain('title="Severity: critical"')
+    expect(html).toContain('>critical<')
+  })
+
+  test('reflects each severity level', () => {
+    expect(renderToStaticMarkup(<ImpactTag impact="minor" />)).toContain(
+      'data-impact="minor"',
+    )
+    expect(renderToStaticMarkup(<ImpactTag impact="moderate" />)).toContain(
+      'data-impact="moderate"',
+    )
+  })
+})

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

@@ -0,0 +1,35 @@
+import type { A11yImpact } from '../../../../index'
+
+/**
+ * Display Case — ImpactTag
+ * A severity tag for an accessibility violation, colour-graded by axe impact
+ * (critical → minor) so the worst findings read hottest. Used in the
+ * {@link A11yPanel} violation list; `impactRank` orders a list worst-first.
+ */
+
+// Worst → least, so a list sorts top-down. Unclassified (null) sorts last.
+const RANK: Record<A11yImpact, number> = {
+  critical: 0,
+  serious: 1,
+  moderate: 2,
+  minor: 3,
+}
+
+/** Sort key for an impact (worst first); `null`/unclassified sorts last. */
+export const impactRank = (impact: A11yImpact | null): number =>
+  impact ? RANK[impact] : 4
+
+export interface ImpactTagProps {
+  impact: A11yImpact
+}
+
+export function ImpactTag({ impact }: ImpactTagProps) {
+  return (
+    <span
+      className="dcui-impact-tag"
+      data-impact={impact}
+      title={`Severity: ${impact}`}>
+      {impact}
+    </span>
+  )
+}

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

@@ -0,0 +1,86 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { NavItem } from './NavItem'
+import { Sidebar } from './Sidebar'
+
+export default defineCases(
+  'NavItem',
+  {
+    // Wrapped in Sidebar — NavItem rows are transparent and only read correctly
+    // against the sidebar's `--dc-bg-subtle` surface.
+    Playground: {
+      tweaks: {
+        kind: tweak.choice(['component', 'case'], 'component'),
+        label: tweak.text('Button'),
+        withCount: tweak.boolean(true),
+        count: tweak.number(4),
+        alert: tweak.number(0),
+        current: tweak.boolean(false),
+        expanded: tweak.boolean(false),
+      },
+      render: (t) => (
+        <Sidebar style={{ width: '15rem' }}>
+          <NavItem
+            kind={t.kind as 'component' | 'case'}
+            label={t.label}
+            count={t.withCount ? t.count : undefined}
+            alert={t.alert}
+            current={t.current}
+            expanded={t.expanded}
+            onToggle={() => {}}
+            onSelect={() => {}}
+          />
+        </Sidebar>
+      ),
+    },
+    // Accessibility-violation markers. Collapsed, a component shows the summed
+    // count (the danger pill). Expanded, the parent shows a plain dot while the
+    // per-variant counts move onto the case rows. See the "A11y page" exhibit
+    // for the markers in the full chrome.
+    Alert: () => (
+      <Sidebar style={{ width: '15rem' }}>
+        <NavItem
+          kind="component"
+          label="Input"
+          count={2}
+          alert={5}
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+        <NavItem
+          kind="component"
+          label="Button"
+          count={3}
+          alert="dot"
+          expanded
+          onToggle={() => {}}
+          onSelect={() => {}}
+        />
+        <NavItem kind="case" label="Playground" alert={2} onSelect={() => {}} />
+        <NavItem kind="case" label="Variants" alert={3} onSelect={() => {}} />
+        <NavItem kind="case" label="Sizes" onSelect={() => {}} />
+      </Sidebar>
+    ),
+    Tree: () => (
+      <Sidebar style={{ width: '15rem' }}>
+        <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: 'molecule' },
+)

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

@@ -0,0 +1,111 @@
+.dcui-navrow {
+  display: flex;
+  align-items: center;
+  gap: var(--dc-space-1);
+  width: 100%;
+  box-sizing: border-box;
+  position: relative;
+}
+.dcui-nav-disclosure {
+  flex: 0 0 auto;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 22px;
+  border: 0;
+  background: none;
+  color: var(--dc-fg-subtle);
+  cursor: pointer;
+  border-radius: var(--dc-radius-sm);
+  padding: 0;
+  transition:
+    color var(--dc-transition-fast),
+    background var(--dc-transition-fast);
+}
+.dcui-nav-disclosure:hover {
+  color: var(--dc-fg);
+  background: var(--dc-hover);
+}
+/* A non-expandable component row (single case) keeps the chevron's footprint so
+   its name still lines up under expandable siblings — just with no glyph. */
+.dcui-nav-disclosure-spacer {
+  flex: 0 0 auto;
+  width: 20px;
+  height: 22px;
+}
+.dcui-chevron {
+  font-family: var(--dc-font-mono);
+  font-size: 0.65rem;
+  line-height: 1;
+  transition: transform var(--dc-transition-fast);
+}
+.dcui-chevron[data-expanded="true"] {
+  transform: rotate(90deg);
+}
+.dcui-nav-name {
+  flex: 1;
+  min-width: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--dc-space-3);
+  text-align: left;
+  font-family: var(--dc-font-sans);
+  font-size: var(--dc-text-base);
+  font-weight: var(--dc-weight-medium);
+  color: var(--dc-fg);
+  border: 0;
+  background: none;
+  cursor: pointer;
+  padding: 0.25rem var(--dc-space-3);
+  border-radius: var(--dc-radius-sm);
+  overflow: hidden;
+  transition:
+    background var(--dc-transition-fast),
+    color var(--dc-transition-fast);
+}
+/* The name text itself truncates; the alert pill beside it never shrinks. */
+.dcui-nav-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dcui-nav-name:hover {
+  background: var(--dc-hover);
+}
+.dcui-nav-count {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  color: var(--dc-fg-subtle);
+  flex: 0 0 auto;
+  padding-right: var(--dc-space-3);
+}
+/* Case rows indent so their text lines up under the component name (chevron
+   width + row gap, then the name's own text padding). */
+.dcui-navrow[data-kind="case"] {
+  padding-left: calc(20px + var(--dc-space-1));
+}
+.dcui-navrow[data-kind="case"] .dcui-nav-name {
+  font-weight: var(--dc-weight-normal);
+  font-size: var(--dc-text-sm);
+  color: var(--dc-fg-muted);
+}
+.dcui-navrow[data-kind="case"] .dcui-nav-name:hover {
+  color: var(--dc-fg);
+}
+.dcui-navrow[data-current="true"] .dcui-nav-name {
+  color: var(--dc-brand);
+  font-weight: var(--dc-weight-medium);
+}
+.dcui-navrow[data-current="true"]::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 2px;
+  height: 1rem;
+  border-radius: 1px;
+  background: var(--dc-brand);
+}

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

@@ -0,0 +1,13 @@
+**NavItem** — one row in the sidebar tree; reach for it to render a component or case entry in the navigation.
+
+```tsx
+<NavItem kind="component" label="Button" count={4} expanded
+  onToggle={toggle} onSelect={select} />
+<NavItem kind="case" label="Variants" current onSelect={select} />
+```
+
+`kind="component"` (the default) renders a disclosure chevron + name + optional case `count`; `kind="case"` renders an indented case link aligned under the component name. The chevron and `onToggle` exist only for `kind="component"`. The active row (`current`) is marigold with a left tick.
+
+Place inside `Sidebar`.
+
+`onSelect` (name click) and `onToggle` (chevron click) are argument-less. A11y: component rows expose `aria-expanded` with a dynamic Expand/Collapse label; the name button gets `aria-current` when `current`.

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

@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { NavItem } from './NavItem'
+
+describe('NavItem', () => {
+  test('a toggleable component row leads with a disclosure chevron', () => {
+    const html = renderToStaticMarkup(
+      <NavItem label="Button" expanded={false} onToggle={() => {}} count={3} />,
+    )
+    expect(html).toContain('class="dcui-nav-disclosure"')
+    expect(html).toContain('aria-expanded="false"')
+    expect(html).toContain('aria-label="Expand Button"')
+    expect(html).toContain('data-kind="component"')
+  })
+
+  test('the chevron aria-label flips with the expanded state', () => {
+    const html = renderToStaticMarkup(
+      <NavItem label="Button" expanded onToggle={() => {}} />,
+    )
+    expect(html).toContain('aria-label="Collapse Button"')
+    expect(html).toContain('data-expanded="true"')
+  })
+
+  test('a single-case component row swaps the chevron for an aligning spacer', () => {
+    const html = renderToStaticMarkup(<NavItem label="Solo" />)
+    expect(html).toContain('class="dcui-nav-disclosure-spacer"')
+    expect(html).not.toContain('class="dcui-nav-disclosure"')
+  })
+
+  test('a case row is indented and carries no disclosure', () => {
+    const html = renderToStaticMarkup(<NavItem kind="case" label="default" />)
+    expect(html).toContain('data-kind="case"')
+    expect(html).not.toContain('dcui-nav-disclosure')
+  })
+
+  test('the active row sets data-current and aria-current', () => {
+    const html = renderToStaticMarkup(<NavItem label="Button" current />)
+    expect(html).toContain('data-current="true"')
+    expect(html).toContain('aria-current="true"')
+  })
+
+  test('renders the a11y badge only for a positive count or "dot"', () => {
+    expect(renderToStaticMarkup(<NavItem label="x" alert={2} />)).toContain(
+      'dcui-a11y-badge',
+    )
+    expect(renderToStaticMarkup(<NavItem label="x" alert="dot" />)).toContain(
+      'data-dot="true"',
+    )
+    expect(renderToStaticMarkup(<NavItem label="x" alert={0} />)).not.toContain(
+      'dcui-a11y-badge',
+    )
+    expect(renderToStaticMarkup(<NavItem label="x" />)).not.toContain(
+      'dcui-a11y-badge',
+    )
+  })
+
+  test('renders the case count only when provided', () => {
+    expect(
+      renderToStaticMarkup(<NavItem label="x" onToggle={() => {}} count={5} />),
+    ).toContain('dcui-nav-count')
+    expect(
+      renderToStaticMarkup(<NavItem label="x" onToggle={() => {}} />),
+    ).not.toContain('dcui-nav-count')
+  })
+})

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

@@ -0,0 +1,95 @@
+import type { ReactNode } from 'react'
+import { A11yBadge } from './A11yBadge'
+
+/**
+ * Display Case — NavItem
+ * One row in the sidebar tree. `kind="component"` renders a disclosure chevron +
+ * name (+ optional case count); when no `onToggle` is given (a component with a
+ * single case) the chevron is replaced by a same-width spacer and the count is
+ * omitted, so the row reads as a plain leaf that still aligns with its siblings.
+ * `kind="case"` renders an indented case link that lines up under the component
+ * name. The active row is marigold with a left tick.
+ */
+
+export type NavItemKind = 'component' | 'case'
+
+export interface NavItemProps {
+  kind?: NavItemKind
+  label: ReactNode
+  count?: ReactNode
+  current?: boolean
+  expanded?: boolean
+  /** Accessibility marker. A positive number renders a counted danger pill; the
+   *  string `'dot'` renders an unnumbered danger dot — used on an *expanded*
+   *  component whose per-variant counts have moved onto its case rows, so the
+   *  parent flags "issues here" without competing with the child numbers. Omit
+   *  or `0` for none. */
+  alert?: number | 'dot'
+  onSelect?: () => void
+  onToggle?: () => void
+  /** `data-testid` for the select (name) button. */
+  testId?: string
+  /** `data-testid` for the disclosure chevron (component rows only). */
+  toggleTestId?: string
+  /** `data-testid` for the a11y-violation marker. */
+  alertTestId?: string
+}
+
+export function NavItem({
+  kind = 'component',
+  label,
+  count,
+  current = false,
+  expanded = false,
+  alert,
+  onSelect,
+  onToggle,
+  testId,
+  toggleTestId,
+  alertTestId,
+}: NavItemProps) {
+  // The a11y marker (a counted pill, or a bare 'dot' on an expanded parent) is
+  // the standalone A11yBadge; render it only for a positive count / 'dot'.
+  const showAlert = alert === 'dot' || (typeof alert === 'number' && alert > 0)
+  // Component rows lead with a disclosure chevron; a component with no `onToggle`
+  // (a single case) gets a same-width spacer instead so its name still aligns
+  // under expandable siblings. Case rows lead with nothing.
+  let disclosure: ReactNode = null
+  if (kind === 'component') {
+    disclosure = onToggle ? (
+      <button
+        type="button"
+        className="dcui-nav-disclosure"
+        aria-label={expanded ? `Collapse ${label}` : `Expand ${label}`}
+        aria-expanded={expanded}
+        data-testid={toggleTestId}
+        onClick={onToggle}>
+        <span className="dcui-chevron" data-expanded={expanded}>
+          ▸
+        </span>
+      </button>
+    ) : (
+      <span className="dcui-nav-disclosure-spacer" aria-hidden="true" />
+    )
+  }
+  return (
+    <div
+      className="dcui-navrow"
+      data-kind={kind}
+      data-current={current ? 'true' : undefined}>
+      {disclosure}
+      <button
+        type="button"
+        className="dcui-nav-name"
+        aria-current={current ? 'true' : undefined}
+        data-testid={testId}
+        onClick={onSelect}>
+        <span className="dcui-nav-label">{label}</span>
+        {showAlert && alert !== undefined && (
+          <A11yBadge value={alert} testId={alertTestId} />
+        )}
+      </button>
+      {count != null ? <span className="dcui-nav-count">{count}</span> : null}
+    </div>
+  )
+}

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

@@ -0,0 +1,21 @@
+import { defineCases, tweak } from '@awarebydefault/display-case'
+import { RenderAddress } from './RenderAddress'
+
+export default defineCases(
+  'RenderAddress',
+  {
+    Playground: {
+      tweaks: {
+        method: tweak.text('GET'),
+        url: tweak.text(
+          '/render/button/playground?theme=light&t.variant=accent',
+        ),
+      },
+      render: (t) => <RenderAddress method={t.method} url={t.url} />,
+    },
+    Default: () => (
+      <RenderAddress url="/render/button/playground?theme=light&t.variant=accent" />
+    ),
+  },
+  { level: 'molecule' },
+)

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

@@ -0,0 +1,35 @@
+.dcui-address {
+  display: flex;
+  align-items: center;
+  gap: var(--dc-space-4);
+  width: 100%;
+  /* border-box so the 100% width + padding + border stays inside the container
+     (matches the docked tweaks panel's right edge instead of overflowing it). */
+  box-sizing: border-box;
+  border: var(--dc-border-line);
+  border-radius: var(--dc-radius-sm);
+  background: var(--dc-surface);
+  padding: var(--dc-space-3) var(--dc-space-4);
+}
+/* A solid accent tag (the accent Button's fill), but inert — it's just a label. */
+.dcui-address-method {
+  flex: 0 0 auto;
+  line-height: 1;
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-xs);
+  font-weight: var(--dc-weight-medium);
+  color: var(--dc-brand-fg);
+  background: var(--dc-brand);
+  padding: 0.3125rem var(--dc-space-3);
+  border-radius: var(--dc-radius-sm);
+}
+.dcui-address-url {
+  font-family: var(--dc-font-mono);
+  font-size: var(--dc-text-sm);
+  color: var(--dc-fg);
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

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

@@ -0,0 +1,7 @@
+**RenderAddress** — a monospace address bar with an HTTP method tag, a URL that scrolls if it overflows, and a copy button; reach for it to show a deterministic render URL (or any endpoint) the reader can copy.
+
+```tsx
+<RenderAddress method="GET" url="/render/button/playground?theme=light" />
+```
+
+Clicking the button copies `url` to the clipboard, flips the glyph to ✓ for ~1.2s, then reverts. It degrades silently when the clipboard is unavailable (e.g. an isolated frame) — the address still reads.

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

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { RenderAddress } from './RenderAddress'
+
+describe('RenderAddress', () => {
+  test('renders the URL with a default GET method tag and a copy control', () => {
+    const html = renderToStaticMarkup(
+      <RenderAddress url="/render/button/default" />,
+    )
+    expect(html).toContain('class="dcui-address-method"')
+    expect(html).toContain('>GET<')
+    expect(html).toContain('/render/button/default')
+    expect(html).toContain('aria-label="Copy address"')
+  })
+
+  test('renders the copy glyph in its un-copied resting state', () => {
+    const html = renderToStaticMarkup(<RenderAddress url="/x" />)
+    expect(html).toContain('⧉')
+    expect(html).not.toContain('✓')
+  })
+
+  test('reflects a custom method tag', () => {
+    const html = renderToStaticMarkup(<RenderAddress url="/x" method="POST" />)
+    expect(html).toContain('>POST<')
+  })
+})

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

@@ -0,0 +1,43 @@
+import { useState } from 'react'
+import { IconButton } from '../controls/IconButton'
+
+/**
+ * Display Case — RenderAddress
+ * A monospace address bar: an HTTP method tag, a URL that truncates with an
+ * ellipsis if it overflows, and a copy button. Shows a deterministic render URL (or any
+ * endpoint) the reader can copy — the browse chrome uses it for the live
+ * exhibit's address.
+ */
+
+export interface RenderAddressProps {
+  /** The address shown and copied. */
+  url: string
+  /** HTTP method tag on the left. */
+  method?: string
+}
+
+export function RenderAddress({ url, method = 'GET' }: RenderAddressProps) {
+  const [copied, setCopied] = useState(false)
+  const copy = () => {
+    try {
+      navigator.clipboard?.writeText(url)
+    } catch {
+      // Clipboard may be unavailable in an isolated frame — the address still reads.
+    }
+    setCopied(true)
+    setTimeout(() => setCopied(false), 1200)
+  }
+  return (
+    <div className="dcui-address">
+      <span className="dcui-address-method">{method}</span>
+      <span className="dcui-address-url">{url}</span>
+      <IconButton
+        glyph={copied ? '✓' : '⧉'}
+        label="Copy address"
+        variant="bare"
+        size="sm"
+        onClick={copy}
+      />
+    </div>
+  )
+}