@lovett/ui 0.0.4 → 0.0.6

package/src/__tests__/modal.test.tsx

@@ -0,0 +1,154 @@
+/**
+ * Modal — 51 consuming files plus 113 sub-component call sites.
+ *
+ * Note what these tests deliberately do NOT claim: Modal has no
+ * role="dialog", no aria-modal, no focus trap and no focus restore, so
+ * there is no dialog role to query by. That is a real accessibility gap
+ * (a keyboard user can Tab through the page behind the backdrop) and it
+ * is tracked separately — these tests pin the behaviour that exists so
+ * the a11y work can be verified as a change, not guessed at.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import Modal from '../modal'
+
+const noop = () => {}
+
+describe('Modal', () => {
+  it('renders nothing when closed', () => {
+    const { container } = render(
+      <Modal isOpen={false} onClose={noop} title="Confirm">
+        body
+      </Modal>,
+    )
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders the title and body when open', () => {
+    render(
+      <Modal isOpen onClose={noop} title="Confirm">
+        body content
+      </Modal>,
+    )
+    expect(screen.getByRole('heading', { name: 'Confirm' })).toBeInTheDocument()
+    expect(screen.getByText('body content')).toBeInTheDocument()
+  })
+
+  it('closes on the labelled close button', async () => {
+    const onClose = vi.fn()
+    render(
+      <Modal isOpen onClose={onClose} title="Confirm">
+        body
+      </Modal>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Close' }))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes on Escape', async () => {
+    const onClose = vi.fn()
+    render(
+      <Modal isOpen onClose={onClose} title="Confirm">
+        body
+      </Modal>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not listen for Escape while closed', async () => {
+    const onClose = vi.fn()
+    render(
+      <Modal isOpen={false} onClose={onClose} title="Confirm">
+        body
+      </Modal>,
+    )
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  it('detaches the Escape listener on unmount', async () => {
+    const onClose = vi.fn()
+    const { unmount } = render(
+      <Modal isOpen onClose={onClose} title="Confirm">
+        body
+      </Modal>,
+    )
+    unmount()
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).not.toHaveBeenCalled()
+  })
+
+  describe('Tray + Footer compose into one decision surface', () => {
+    // The actions belong ON the tray, not in the frame gap below it.
+    // Before this, Tray sat at --tray-inset (4px) and Footer on the outer
+    // card at px-6 (24px), so the buttons were 20px inboard of the tray
+    // edge they were meant to align with, and `.ds-card-tray:not(:last-child)`
+    // zeroed the tray's bottom margin so its lower corners were cut flush.
+    const renderBoth = () =>
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <Modal.Tray>tray body</Modal.Tray>
+          <Modal.Footer>
+            <button type="button">Confirm</button>
+          </Modal.Footer>
+        </Modal>,
+      )
+
+    it('puts the actions INSIDE the tray', () => {
+      renderBoth()
+      const tray = document.querySelector('.ds-card-tray')
+      expect(tray).toHaveTextContent('tray body')
+      expect(tray).toHaveTextContent('Confirm')
+      expect(tray!.contains(screen.getByRole('button', { name: 'Confirm' }))).toBe(
+        true,
+      )
+    })
+
+    it('renders exactly one tray — the footer does not get its own', () => {
+      renderBoth()
+      expect(document.querySelectorAll('.ds-card-tray')).toHaveLength(1)
+    })
+
+    it('separates body from actions with a divider', () => {
+      renderBoth()
+      const footer = screen
+        .getByRole('button', { name: 'Confirm' })
+        .closest('div')!
+      expect(footer.className).toContain('border-t')
+    })
+
+    it('keeps a Tray standalone when there is no Footer', () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <Modal.Tray>tray body</Modal.Tray>
+        </Modal>,
+      )
+      const tray = document.querySelector('.ds-card-tray')
+      expect(tray).toHaveTextContent('tray body')
+      // The standalone tray owns its own padding.
+      expect(tray!.className).toContain('p-5')
+    })
+
+    it('leaves flat children alone', () => {
+      render(
+        <Modal isOpen onClose={noop} title="Confirm">
+          <p>flat body</p>
+        </Modal>,
+      )
+      expect(screen.getByText('flat body')).toBeInTheDocument()
+      expect(document.querySelector('.ds-card-tray')).toBeNull()
+    })
+  })
+
+  it('merges a caller className onto the panel', () => {
+    render(
+      <Modal isOpen onClose={noop} title="Confirm" className="max-w-sm">
+        body
+      </Modal>,
+    )
+    const panel = document.querySelector('.ds-card-surface')
+    expect(panel).toHaveClass('ds-card-surface', 'max-w-sm')
+  })
+})

package/src/__tests__/page-shell.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * PageShell — 84 consuming files.
+ *
+ * Two behaviours matter to consumers and neither was verified before:
+ * the legacy `breadcrumb` + `title` props still resolve to the same
+ * crumb chain as `crumbs`, and the slot-host mode relocates the header
+ * instead of rendering a second sticky bar.
+ *
+ * PageShell imports <Link>, which is why every consumer inherits a hard
+ * dependency on react-router-dom — hence the MemoryRouter here.
+ */
+import { describe, expect, it } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { MemoryRouter } from 'react-router-dom'
+import {
+  PageShell,
+  PageHeaderSlotProvider,
+  PageHeaderHost,
+} from '../page-shell'
+
+const renderShell = (ui: React.ReactNode) =>
+  render(<MemoryRouter>{ui}</MemoryRouter>)
+
+describe('PageShell', () => {
+  it('renders its children', () => {
+    renderShell(
+      <PageShell title="Brand">
+        <p>lens content</p>
+      </PageShell>,
+    )
+    expect(screen.getByText('lens content')).toBeInTheDocument()
+  })
+
+  it('renders a crumb chain, linking only the crumbs that have a `to`', () => {
+    renderShell(
+      <PageShell
+        crumbs={[
+          { label: 'Clients', to: '/clients' },
+          { label: 'Acme' },
+          { label: 'Brand' },
+        ]}
+      >
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(screen.getByRole('link', { name: 'Clients' })).toHaveAttribute(
+      'href',
+      '/clients',
+    )
+    expect(screen.queryByRole('link', { name: 'Acme' })).toBeNull()
+    expect(screen.getByText('Acme')).toBeInTheDocument()
+    expect(screen.getByText('Brand')).toBeInTheDocument()
+  })
+
+  it('resolves the legacy breadcrumb + title pair into the same chain', () => {
+    renderShell(
+      <PageShell breadcrumb="Clients" title="Brand">
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(screen.getByText('Clients')).toBeInTheDocument()
+    expect(screen.getByText('Brand')).toBeInTheDocument()
+  })
+
+  it('prefers `crumbs` over the legacy props when both are supplied', () => {
+    renderShell(
+      <PageShell breadcrumb="Legacy" title="Old" crumbs={[{ label: 'New' }]}>
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(screen.getByText('New')).toBeInTheDocument()
+    expect(screen.queryByText('Legacy')).toBeNull()
+    expect(screen.queryByText('Old')).toBeNull()
+  })
+
+  it('renders actions', () => {
+    renderShell(
+      <PageShell title="Brand" actions={<button type="button">Export</button>}>
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument()
+  })
+
+  it('renders its own sticky header when no host is mounted', () => {
+    renderShell(
+      <PageShell title="Brand">
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(screen.getByRole('banner')).toBeInTheDocument()
+  })
+
+  it('portals the header into the host instead of rendering a second bar', () => {
+    renderShell(
+      <PageHeaderSlotProvider>
+        <PageHeaderHost />
+        <PageShell title="Brand" actions={<button type="button">Export</button>}>
+          <p>lens content</p>
+        </PageShell>
+      </PageHeaderSlotProvider>,
+    )
+    // The crumbs and actions still render exactly once...
+    expect(screen.getByText('Brand')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument()
+    // ...and PageShell does not add its own <header> on top of the host's.
+    expect(screen.getAllByRole('banner')).toHaveLength(1)
+  })
+
+  it('applies the default content padding, overridable by contentClassName', () => {
+    const { container, rerender } = renderShell(
+      <PageShell title="Brand">
+        <p>x</p>
+      </PageShell>,
+    )
+    expect(container.querySelector('.px-7')).not.toBeNull()
+
+    rerender(
+      <MemoryRouter>
+        <PageShell title="Brand" contentClassName="p-0">
+          <p>x</p>
+        </PageShell>
+      </MemoryRouter>,
+    )
+    expect(container.querySelector('.px-7')).toBeNull()
+    expect(container.querySelector('.p-0')).not.toBeNull()
+  })
+})

package/src/__tests__/setup.ts

@@ -0,0 +1,43 @@
+import '@testing-library/jest-dom/vitest'
+
+// Setup runs for BOTH environments. Pure source-scan files opt into the
+// node env with a `// @vitest-environment node` pragma (it skips the
+// ~500ms jsdom init), so every DOM stub below has to be guarded.
+const HAS_DOM = typeof window !== 'undefined'
+
+if (HAS_DOM) {
+  // jsdom ships neither observer. DropdownMenu measures its content before
+  // revealing it, ChipNav scroll-spies with an IntersectionObserver, and
+  // several primitives observe container resize. No-op stubs are enough
+  // for tests that don't exercise the observers themselves.
+  class StubIntersectionObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords(): IntersectionObserverEntry[] {
+      return []
+    }
+    root = null
+    rootMargin = ''
+    thresholds = []
+  }
+  ;(
+    globalThis as unknown as {
+      IntersectionObserver: typeof IntersectionObserver
+    }
+  ).IntersectionObserver =
+    StubIntersectionObserver as unknown as typeof IntersectionObserver
+
+  class StubResizeObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  ;(
+    globalThis as unknown as { ResizeObserver: typeof ResizeObserver }
+  ).ResizeObserver = StubResizeObserver as unknown as typeof ResizeObserver
+
+  if (!Element.prototype.scrollIntoView) {
+    Element.prototype.scrollIntoView = function () {}
+  }
+}

package/src/__tests__/token-shape.test.ts

@@ -0,0 +1,193 @@
+// @vitest-environment node
+//
+// Pure source scan — no DOM needed, and jsdom rewrites import.meta.url to
+// an http URL that fileURLToPath rejects.
+/**
+ * Static guard for the "type-checks, lints, builds, renders nothing"
+ * defect class — CSS that is syntactically fine and semantically void.
+ *
+ * WHY THIS IS A SOURCE SCAN AND NOT A RENDER TEST
+ * ------------------------------------------------
+ * The first attempt at this asserted rendered inline styles. It could not
+ * work: any value containing `var()` is "pending substitution", so jsdom
+ * (and browsers, at parse time) store it verbatim without validating it.
+ * `rgb(var(--surface-overlay-soft) / 0.5)` and `rgb(var(--muted))` are
+ * indistinguishable through the CSSOM — a render test happily passes on
+ * the broken form. The invalidity only appears at computed-value time in
+ * a real browser, which is precisely why typecheck, lint, build and the
+ * whole test suite were all green while three primitives shipped with no
+ * error border and every SortableTable shipped unbanded.
+ *
+ * So this reads the source instead, and derives its rules from
+ * tokens.css rather than hardcoding a token list — a new alpha-carrying
+ * or shadow-valued token is covered the day it is added.
+ *
+ * The two rules:
+ *
+ *   1. A token whose VALUE is a shadow list ("0 0 0 3px rgb(...)") can
+ *      never appear inside rgb(). `rgb(var(--ring-error))` expands to
+ *      `rgb(0 0 0 3px rgb(...))`, which is dropped.
+ *
+ *   2. A token whose VALUE already carries an alpha ("0 0 0 / 0.03")
+ *      can never take a second one. `rgb(var(--surface-overlay-soft) / 0.5)`
+ *      expands to `rgb(0 0 0 / 0.03 / 0.5)`, which is dropped.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const SRC = fileURLToPath(new URL('..', import.meta.url))
+
+function sourceFiles(dir: string, acc: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules' || entry === '__tests__') continue
+    const full = join(dir, entry)
+    if (statSync(full).isDirectory()) sourceFiles(full, acc)
+    else if (/\.(tsx?|css)$/.test(entry) && entry !== 'tokens.css') acc.push(full)
+  }
+  return acc
+}
+
+/** Parse tokens.css into { name -> [values across all theme blocks] }. */
+function readTokenValues(): Map<string, string[]> {
+  const css = readFileSync(join(SRC, 'tokens.css'), 'utf8')
+  const out = new Map<string, string[]>()
+  for (const [, name, value] of css.matchAll(/^\s*(--[a-z0-9-]+)\s*:\s*([^;]+);/gm)) {
+    const list = out.get(name!) ?? []
+    list.push(value!.trim())
+    out.set(name!, list)
+  }
+  return out
+}
+
+const TOKENS = readTokenValues()
+
+/** A shadow list — has a length unit, so it is not a colour. */
+const isShadowValued = (values: string[]) =>
+  values.some((v) => /\b\d+(px|rem|em)\b/.test(v) || v.startsWith('inset '))
+
+/** Already carries an alpha, so it cannot take a second one. */
+const isAlphaCarrying = (values: string[]) =>
+  values.some((v) => /^[\d\s.]+\/\s*[\d.]+$/.test(v))
+
+/**
+ * Blank out comments while preserving line numbers, so a violation still
+ * reports the line it is on. Without this the scan flags its own
+ * explanatory comments — every doc-block that spells out the broken form
+ * in order to warn against it.
+ *
+ * Line comments are only stripped when the line STARTS with `//`, so a
+ * `https://` inside a string is left intact.
+ */
+function stripComments(src: string): string {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .split('\n')
+    .map((line) => (/^\s*\/\//.test(line) ? '' : line))
+    .join('\n')
+}
+
+const FILES = sourceFiles(SRC)
+const rel = (f: string) => relative(SRC, f)
+const readCode = (f: string) => stripComments(readFileSync(f, 'utf8')).split('\n')
+
+describe('token shape', () => {
+  it('parsed a plausible token file', () => {
+    // Guard the guard: if the parse silently returned nothing, every
+    // assertion below would vacuously pass.
+    expect(TOKENS.size).toBeGreaterThan(100)
+    expect(isShadowValued(TOKENS.get('--ring-error') ?? [])).toBe(true)
+    expect(isAlphaCarrying(TOKENS.get('--surface-overlay-soft') ?? [])).toBe(true)
+    expect(isShadowValued(TOKENS.get('--accent') ?? [])).toBe(false)
+    expect(isAlphaCarrying(TOKENS.get('--accent') ?? [])).toBe(false)
+  })
+
+  it('finds source files to scan', () => {
+    expect(FILES.length).toBeGreaterThan(50)
+  })
+
+  it('never wraps a shadow-valued token in rgb()', () => {
+    const violations: string[] = []
+    for (const file of FILES) {
+      readCode(file).forEach((line, i) => {
+        for (const [, token] of line.matchAll(/rgb\(\s*var\((--[a-z0-9-]+)\)/g)) {
+          if (isShadowValued(TOKENS.get(token!) ?? [])) {
+            violations.push(`${rel(file)}:${i + 1} — rgb(var(${token})) is a box-shadow list, not a colour`)
+          }
+        }
+      })
+    }
+    expect(violations).toEqual([])
+  })
+
+  it('never nests a second alpha on an alpha-carrying token', () => {
+    const violations: string[] = []
+    for (const file of FILES) {
+      readCode(file).forEach((line, i) => {
+        for (const [, token] of line.matchAll(
+          /rgb\(\s*var\((--[a-z0-9-]+)\)\s*\/\s*[\d.]/g,
+        )) {
+          if (isAlphaCarrying(TOKENS.get(token!) ?? [])) {
+            violations.push(`${rel(file)}:${i + 1} — var(${token}) already carries an alpha`)
+          }
+        }
+      })
+    }
+    expect(violations).toEqual([])
+  })
+
+  it('never references a token that tokens.css does not define', () => {
+    const violations: string[] = []
+    for (const file of FILES) {
+      readCode(file).forEach((line, i) => {
+        for (const [, token] of line.matchAll(/var\((--[a-z0-9-]+)[,)]/g)) {
+          // Tailwind's own custom properties are not ours to define.
+          if (token!.startsWith('--tw-')) continue
+          if (!TOKENS.has(token!)) {
+            violations.push(`${rel(file)}:${i + 1} — var(${token}) is not defined in tokens.css`)
+          }
+        }
+      })
+    }
+    expect(violations).toEqual([])
+  })
+})
+
+describe('interpolated Tailwind classes', () => {
+  it('never builds an arbitrary-value utility from a template literal', () => {
+    // Tailwind scans source statically, so `h-[${SIZE}px]` is never
+    // generated. It type-checks, lints and builds, and does nothing.
+    const violations: string[] = []
+    for (const file of FILES) {
+      readCode(file).forEach((line, i) => {
+        if (/[a-z-]+-\[[^\]]*\$\{/.test(line)) {
+          violations.push(`${rel(file)}:${i + 1} — ${line.trim()}`)
+        }
+      })
+    }
+    expect(violations).toEqual([])
+  })
+})
+
+describe('undefined utility classes', () => {
+  // `animate-in`, `fade-in-0`, `zoom-in-95`, `slide-in-from-*` ship in
+  // tailwindcss-animate / tw-animate-css. Neither is a dependency of this
+  // repo, and Tailwind 4 core ships only spin/ping/pulse/bounce — so both
+  // of the kit's entrance animations referenced classes that had never
+  // been generated and had never run.
+  const ANIMATE_PLUGIN_CLASSES =
+    /\b(animate-in|animate-out|fade-in(-\d+)?|fade-out(-\d+)?|zoom-in(-\d+)?|zoom-out(-\d+)?|slide-in-from-\w+(-\d+)?|slide-out-to-\w+(-\d+)?)\b/
+
+  it('does not use tailwindcss-animate classes without the dependency', () => {
+    const violations: string[] = []
+    for (const file of FILES) {
+      readCode(file).forEach((line, i) => {
+        if (ANIMATE_PLUGIN_CLASSES.test(line)) {
+          violations.push(`${rel(file)}:${i + 1} — ${line.trim()}`)
+        }
+      })
+    }
+    expect(violations).toEqual([])
+  })
+})

package/src/allocation-sparkbar.tsx

@@ -0,0 +1,90 @@
+/**
+ * AllocationSparkbar — a compact per-period bar strip.
+ *
+ * New in ADR-123 (Budget Flighting redesign). Renders one bar per period
+ * (month), height proportional to the value; a zero/paused period renders
+ * short + dashed in a muted tone. Each bar can tint from its own token (e.g. a
+ * flight-group color), falling back to `baseColorVar`. Optional single-letter
+ * labels sit under each bar.
+ *
+ * Token discipline: colors come only from public token *names* via
+ * `rgb(var(--token) / a)`. No literals. Layout sizes use the spacing scale.
+ */
+
+export interface AllocationSparkbarProps {
+  /** Per-period amounts. A value of 0 is treated as paused (short + dashed). */
+  values: number[]
+  /** Base token name for normal bars, e.g. `--folder-teal`. Includes `--`. */
+  baseColorVar: string
+  /** Optional per-period token name (e.g. a flight-group color). `null`/
+   *  `undefined` falls back to `baseColorVar`. Length should match `values`. */
+  colorVars?: (string | null | undefined)[]
+  /** Optional short labels under each bar (e.g. `['J','F','M']`). */
+  labels?: string[]
+  /** Optional per-bar tooltip text (native `title`). */
+  titles?: string[]
+  /** Strip height in px. Default 36. */
+  height?: number
+  className?: string
+}
+
+export function AllocationSparkbar({
+  values,
+  baseColorVar,
+  colorVars,
+  labels,
+  titles,
+  height = 36,
+  className,
+}: AllocationSparkbarProps) {
+  const max = Math.max(...values, 1)
+  return (
+    <div
+      className={className}
+      style={{ display: 'flex', gap: 'var(--space-1)', alignItems: 'flex-end', height }}
+    >
+      {values.map((value, i) => {
+        const paused = value === 0
+        const barH = paused ? 4 : 8 + (value / max) * (height - 12)
+        const colorVar = colorVars?.[i] ?? baseColorVar
+        return (
+          <div
+            key={i}
+            title={titles?.[i]}
+            style={{
+              flex: 1,
+              display: 'flex',
+              flexDirection: 'column',
+              alignItems: 'center',
+              gap: 'var(--space-1)',
+              minWidth: 0,
+            }}
+          >
+            <div
+              style={{
+                width: '100%',
+                height: barH,
+                borderRadius: 'var(--radius-xs)',
+                background: paused
+                  ? 'rgb(var(--text-muted) / 0.18)'
+                  : `rgb(var(${colorVar}) / 0.67)`,
+                border: paused
+                  ? '1px dashed rgb(var(--text-muted) / 0.4)'
+                  : 'none',
+                transition: 'background var(--dur-fast, 120ms)',
+              }}
+            />
+            {labels?.[i] !== undefined && (
+              <span
+                className="text-[9.5px] font-semibold tracking-[0.02em]"
+                style={{ color: 'rgb(var(--text-muted))' }}
+              >
+                {labels[i]}
+              </span>
+            )}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/card.tsx

@@ -203,7 +203,7 @@ function MetaItem({
           {icon}
         </span>
       )}
-      <span className="truncate tnum">{children}</span>
+      <span className="truncate tabular-nums">{children}</span>
     </div>
   )
 }