@lovett/ui 0.0.11 → 0.2.0

package/src/__tests__/tabs.test.tsx

@@ -0,0 +1,303 @@
+/**
+ * Tabs — the WAI-ARIA APG keyboard contract.
+ *
+ * `role="tablist"` shipped with none of the behaviour the role promises: no
+ * roving tabindex (every tab was its own tab stop), no arrow keys, and no
+ * `id` / `aria-controls` linking a tab to anything. These pin the four halves
+ * of the fix — movement + wrap, Home/End, the roving tabindex values, and
+ * that an emitted `aria-controls` actually resolves to a rendered element.
+ */
+import { useState } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Tabs, type Tab } from '../tabs'
+import { SegmentedChoice } from '../detail/segmented-choice'
+
+const TABS: Tab[] = [
+  { id: 'overview', label: 'Overview' },
+  { id: 'activity', label: 'Activity' },
+  { id: 'settings', label: 'Settings' },
+]
+
+/** Controlled harness — the component is controlled, so the test owns state. */
+function Harness({
+  tabs = TABS,
+  initial = 'overview',
+  variant,
+  onTabChange,
+}: {
+  tabs?: Tab[]
+  initial?: string
+  variant?: 'underline' | 'pill' | 'segmented'
+  onTabChange?: (id: string) => void
+}) {
+  const [active, setActive] = useState(initial)
+  return (
+    <Tabs
+      idPrefix="demo"
+      {...(variant === undefined ? {} : { variant })}
+      tabs={tabs}
+      activeTabId={active}
+      onTabChange={(id) => {
+        setActive(id)
+        onTabChange?.(id)
+      }}
+    />
+  )
+}
+
+const tab = (name: string) => screen.getByRole('tab', { name })
+
+describe('Tabs', () => {
+  describe('roving tabindex', () => {
+    it('puts exactly one tab in the tab ring, and it is the selected one', () => {
+      render(<Harness initial="activity" />)
+      expect(tab('Overview')).toHaveAttribute('tabindex', '-1')
+      expect(tab('Activity')).toHaveAttribute('tabindex', '0')
+      expect(tab('Settings')).toHaveAttribute('tabindex', '-1')
+      expect(
+        screen.getAllByRole('tab').filter((node) => node.getAttribute('tabindex') === '0'),
+      ).toHaveLength(1)
+    })
+
+    it('never emits a positive tabindex', () => {
+      render(<Harness />)
+      for (const node of screen.getAllByRole('tab')) {
+        expect(Number(node.getAttribute('tabindex'))).toBeLessThanOrEqual(0)
+      }
+    })
+
+    it('falls back to the first enabled tab when the selected one is disabled', () => {
+      render(
+        <Harness
+          initial="overview"
+          tabs={[
+            { id: 'overview', label: 'Overview', disabled: true },
+            { id: 'activity', label: 'Activity' },
+          ]}
+        />,
+      )
+      expect(tab('Activity')).toHaveAttribute('tabindex', '0')
+      expect(tab('Overview')).toHaveAttribute('tabindex', '-1')
+    })
+
+    it('moves the tab stop with the selection', async () => {
+      render(<Harness />)
+      tab('Overview').focus()
+      await userEvent.keyboard('{ArrowRight}')
+      expect(tab('Activity')).toHaveAttribute('tabindex', '0')
+      expect(tab('Overview')).toHaveAttribute('tabindex', '-1')
+    })
+  })
+
+  describe('arrow keys', () => {
+    it('ArrowRight moves focus and selects the next tab (automatic activation)', async () => {
+      const onTabChange = vi.fn()
+      render(<Harness onTabChange={onTabChange} />)
+      tab('Overview').focus()
+      await userEvent.keyboard('{ArrowRight}')
+      expect(tab('Activity')).toHaveFocus()
+      expect(tab('Activity')).toHaveAttribute('aria-selected', 'true')
+      expect(onTabChange).toHaveBeenCalledWith('activity')
+    })
+
+    it('ArrowLeft moves the other way', async () => {
+      render(<Harness initial="settings" />)
+      tab('Settings').focus()
+      await userEvent.keyboard('{ArrowLeft}')
+      expect(tab('Activity')).toHaveFocus()
+      expect(tab('Activity')).toHaveAttribute('aria-selected', 'true')
+    })
+
+    it('wraps past the end', async () => {
+      render(<Harness initial="settings" />)
+      tab('Settings').focus()
+      await userEvent.keyboard('{ArrowRight}')
+      expect(tab('Overview')).toHaveFocus()
+      expect(tab('Overview')).toHaveAttribute('aria-selected', 'true')
+    })
+
+    it('wraps past the start', async () => {
+      render(<Harness />)
+      tab('Overview').focus()
+      await userEvent.keyboard('{ArrowLeft}')
+      expect(tab('Settings')).toHaveFocus()
+      expect(tab('Settings')).toHaveAttribute('aria-selected', 'true')
+    })
+
+    it('steps over a disabled tab rather than stranding focus on it', async () => {
+      render(
+        <Harness
+          tabs={[
+            { id: 'overview', label: 'Overview' },
+            { id: 'activity', label: 'Activity', disabled: true },
+            { id: 'settings', label: 'Settings' },
+          ]}
+        />,
+      )
+      tab('Overview').focus()
+      await userEvent.keyboard('{ArrowRight}')
+      expect(tab('Settings')).toHaveFocus()
+    })
+  })
+
+  describe('Home / End', () => {
+    it('Home jumps to the first tab', async () => {
+      render(<Harness initial="settings" />)
+      tab('Settings').focus()
+      await userEvent.keyboard('{Home}')
+      expect(tab('Overview')).toHaveFocus()
+      expect(tab('Overview')).toHaveAttribute('aria-selected', 'true')
+    })
+
+    it('End jumps to the last tab', async () => {
+      render(<Harness />)
+      tab('Overview').focus()
+      await userEvent.keyboard('{End}')
+      expect(tab('Settings')).toHaveFocus()
+      expect(tab('Settings')).toHaveAttribute('aria-selected', 'true')
+    })
+  })
+
+  describe('panel wiring', () => {
+    it('gives every tab a stable id built from idPrefix', () => {
+      render(<Harness />)
+      expect(tab('Overview')).toHaveAttribute('id', 'demo-tab-overview')
+      expect(tab('Settings')).toHaveAttribute('id', 'demo-tab-settings')
+    })
+
+    it('emits no aria-controls when the consumer renders no panel', () => {
+      render(<Harness />)
+      expect(tab('Overview')).not.toHaveAttribute('aria-controls')
+    })
+
+    it('resolves aria-controls to a rendered element when panelId is supplied', () => {
+      render(
+        <div>
+          <Tabs
+            idPrefix="demo"
+            tabs={[
+              { id: 'overview', label: 'Overview', panelId: 'demo-panel-overview' },
+              { id: 'activity', label: 'Activity', panelId: 'demo-panel-activity' },
+            ]}
+            activeTabId="overview"
+            onTabChange={() => {}}
+          />
+          <div
+            id="demo-panel-overview"
+            role="tabpanel"
+            aria-labelledby="demo-tab-overview"
+            tabIndex={0}
+          >
+            Overview panel
+          </div>
+        </div>,
+      )
+      const controls = tab('Overview').getAttribute('aria-controls')
+      expect(controls).toBe('demo-panel-overview')
+      const panel = document.getElementById(controls ?? '')
+      expect(panel).not.toBeNull()
+      expect(panel).toHaveAttribute('role', 'tabpanel')
+      // ...and the panel names its tab back, which resolves too.
+      expect(document.getElementById('demo-tab-overview')).toBe(tab('Overview'))
+    })
+  })
+
+  /**
+   * The `segmented` variant exists so the activity pane's strip can sit
+   * flush with the field-list header in the next pane. That is a HEIGHT
+   * claim, and the height is built the same way in both places — a 26px
+   * segment inside a 4px-padded, 1px-bordered track. jsdom lays nothing
+   * out, so what these pin is the construction the height comes from: if
+   * someone changes the track padding on one and not the other, the two
+   * headers stop lining up and this fails.
+   */
+  describe('the segmented variant', () => {
+    const boxOf = (el: Element) => ({
+      padding: /p-\[var\(--space-1\)\]/.test(el.className),
+      border: /(^|\s)border(\s|$)/.test(el.className),
+      radius: (el as HTMLElement).style.borderRadius,
+    })
+
+    it('builds the same box as SegmentedChoice, so the two headers align', () => {
+      const { unmount } = render(
+        <Tabs
+          variant="segmented"
+          stretch
+          tabs={TABS}
+          activeTabId="overview"
+          onTabChange={() => {}}
+        />,
+      )
+      const track = screen.getByRole('tablist')
+      const segment = screen.getByRole('tab', { name: 'Overview' })
+      expect(boxOf(track)).toEqual({ padding: true, border: true, radius: 'var(--radius-md)' })
+      expect(segment.className).toContain('h-[26px]')
+      unmount()
+
+      render(
+        <SegmentedChoice
+          ariaLabel="Filter fields"
+          value="all"
+          onChange={() => {}}
+          items={[
+            { id: 'all', label: 'All' },
+            { id: 'filled', label: 'Filled' },
+          ]}
+        />,
+      )
+      const choice = screen.getByRole('group', { name: 'Filter fields' })
+      expect(boxOf(choice)).toEqual({ padding: true, border: true, radius: 'var(--radius-md)' })
+      expect(screen.getByRole('button', { name: 'All' }).className).toContain('h-[26px]')
+    })
+
+    it('fills its container with equal-width segments', () => {
+      render(
+        <Tabs
+          variant="segmented"
+          stretch
+          tabs={TABS}
+          activeTabId="overview"
+          onTabChange={() => {}}
+        />,
+      )
+      expect(screen.getByRole('tablist').className).toContain('w-full')
+      for (const label of ['Overview', 'Activity', 'Settings']) {
+        expect(screen.getByRole('tab', { name: label }).className).toContain('flex-1')
+      }
+    })
+
+    it('keeps a focus ring — the one variant with no underline to lose', () => {
+      // The active segment carries `--shadow-sm`. As an INLINE style that
+      // would beat `focus-visible:`, silently; as a class it does not.
+      render(
+        <Tabs
+          variant="segmented"
+          stretch
+          tabs={TABS}
+          activeTabId="overview"
+          onTabChange={() => {}}
+        />,
+      )
+      const active = screen.getByRole('tab', { name: 'Overview' })
+      expect(active.getAttribute('style')).toBeNull()
+      expect(active.className).toContain('[box-shadow:var(--shadow-sm)]')
+      expect(active.className).toContain('focus-visible:[box-shadow:var(--ring-focus)]')
+    })
+
+    it('is still a tablist — the keyboard model comes with it', async () => {
+      const user = userEvent.setup()
+      render(
+        <Harness variant="segmented" tabs={TABS} />,
+      )
+      await user.tab()
+      await user.keyboard('{ArrowRight}')
+      expect(screen.getByRole('tab', { name: 'Activity' })).toHaveAttribute(
+        'aria-selected',
+        'true',
+      )
+    })
+  })
+})
+

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

@@ -137,15 +137,46 @@ describe('token shape', () => {
     expect(violations).toEqual([])
   })
 
-  it('never references a token that tokens.css does not define', () => {
+  it('never references a custom property nothing in the package defines', () => {
+    // A COMPONENT-LOCAL custom property is not a token, and a reference to one
+    // is not the typo this rule hunts. `.ds-avatar` declares `--avatar-hue` /
+    // `--avatar-size` and reads them back, so a hue or size modifier is one
+    // declaration instead of a repeated block; `--avatar-ring` exists precisely
+    // so the HOST can hand the primitive a colour the primitive cannot know
+    // (ADR-147 D14). Requiring those in tokens.css would mean either banning
+    // component-local properties outright or padding the shared vocabulary with
+    // entries nothing outside one component may use.
+    //
+    // So the rule is: a var() must resolve to a tokens.css token OR to a custom
+    // property declared somewhere in this package. Package-wide rather than
+    // per-file because the declaring rule and the reading element routinely sit
+    // in different files — a class in `styles.css` setting a property that a
+    // `.tsx` reads is the normal shape. A misspelt name is still declared
+    // nowhere and still fails, which is the whole point.
+    const declared = new Set(
+      FILES.flatMap((file) =>
+        readCode(file).flatMap((line) =>
+          [...line.matchAll(/(--[a-z0-9-]+)\s*:/g)].map(([, name]) => name!),
+        ),
+      ),
+    )
     const violations: string[] = []
     for (const file of FILES) {
       readCode(file).forEach((line, i) => {
+        // BOTH forms are checked. An earlier pass excluded `var(--x, fallback)`
+        // on the theory that a fallback declares the property optional — but it
+        // also means a typo (`var(--surfce-card, white)`) renders the fallback
+        // forever with nothing to catch it. A genuine override knob declares
+        // itself and its default instead; see `--board-column-max-block-size`
+        // in styles.css.
         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 (declared.has(token!)) continue
           if (!TOKENS.has(token!)) {
-            violations.push(`${rel(file)}:${i + 1} — var(${token}) is not defined in tokens.css`)
+            violations.push(
+              `${rel(file)}:${i + 1} — var(${token}) is declared nowhere in packages/ui`,
+            )
           }
         }
       })
@@ -191,3 +222,102 @@ describe('undefined utility classes', () => {
     expect(violations).toEqual([])
   })
 })
+
+describe('a mark is never painted in a surface token', () => {
+  /**
+   * The defect this pins was MEASURED in a browser, not read out of the
+   * source: `GaugeRing` defaulted its track to `rgb(var(--muted))`, and
+   * `--muted` is declared as `var(--surface-inset)` — the recessed-well
+   * surface. A gauge dropped into a well therefore stroked its track in
+   * exactly the colour behind it: rgb(242,242,244) on rgb(242,242,244) in
+   * light and rgb(45,45,48) on rgb(45,45,48) in dark. **1.00:1 in both
+   * themes** — a 0% gauge rendered as bare text with no ring at all.
+   *
+   * Nothing about that is visible to typecheck, lint, build or a DOM-shape
+   * test: the attribute string `rgb(var(--muted))` is perfectly well-formed.
+   * What IS statically checkable is the relationship — that a token used as
+   * a MARK must not be an alias of a SURFACE. So this resolves the alias
+   * chain by name and asserts the mark never lands on one.
+   *
+   * Mutation check (ADR-146 D8's "a guard never observed failing is not a
+   * guard"): put `--muted` back as the default in `gauge-ring.tsx` and this
+   * test goes red, naming the alias chain it walked.
+   */
+
+  /**
+   * The surfaces a primitive may SIT ON. A mark may never be one of these.
+   *
+   * `--muted` is in the list because it aliases `--surface-inset`. That does
+   * NOT ban `--muted` as a small muted FILL — `RankedBars` fills its track
+   * with it and puts a `--border` stroke around it, which is the sanctioned
+   * shape (CLAUDE.md §2) and survives on any surface because the outline
+   * carries it. The scan below only reads named mark-COLOUR prop defaults,
+   * so that pattern is not matched.
+   */
+  const SURFACE_TOKENS = new Set([
+    '--surface-card',
+    '--surface-frame',
+    '--surface-inset',
+    '--bg-card',
+    '--muted',
+  ])
+
+  /** Follow `--a: var(--b)` until it stops being a pure alias. */
+  function resolveAlias(name: string): string[] {
+    const chain = [name]
+    let current = name
+    for (let hop = 0; hop < 8; hop += 1) {
+      const values = TOKENS.get(current)
+      if (values === undefined) break
+      // A pure alias is a value that is nothing but one var() reference.
+      const targets = values
+        .map((v) => /^var\((--[a-z0-9-]+)\)$/.exec(v.trim())?.[1])
+        .filter((v): v is string => v !== undefined)
+      const aliases = new Set(targets)
+      // Only follow when EVERY theme block declares the SAME alias. A token
+      // that aliases in one theme and is a literal in the other is a
+      // different problem, and stopping here reports it rather than
+      // silently walking one theme's chain.
+      if (aliases.size !== 1 || targets.length !== values.length) break
+      const next = [...aliases][0]!
+      if (chain.includes(next)) break
+      chain.push(next)
+      current = next
+    }
+    return chain
+  }
+
+  /**
+   * Every `<name> = 'rgb(var(--token))'` default in a primitive whose name
+   * says it paints a mark — a track, a stroke, a fill, a rule.
+   */
+  const MARK_DEFAULT =
+    /\b(trackColor|strokeColor|fillColor|ruleColor|barColor)\s*=\s*'rgb\(var\((--[a-z0-9-]+)\)\)'/g
+
+  it('resolves no mark default onto a surface token', () => {
+    const violations: string[] = []
+    for (const file of FILES) {
+      const source = readCode(file).join('\n')
+      for (const [, prop, token] of source.matchAll(MARK_DEFAULT)) {
+        const chain = resolveAlias(token!)
+        const hit = chain.find((step) => SURFACE_TOKENS.has(step))
+        if (hit !== undefined) {
+          violations.push(
+            `${rel(file)} — ${prop} defaults to ${token}, which resolves ` +
+              `${chain.join(' -> ')}; ${hit} is a SURFACE. A mark painted in ` +
+              `the surface it may sit on is invisible (measured 1.00:1).`,
+          )
+        }
+      }
+    }
+    expect(violations).toEqual([])
+  })
+
+  it('still recognises --muted as a surface alias (the guard, inverted)', () => {
+    // Proves the resolver actually walks the chain rather than passing
+    // because it found nothing. If `--muted` ever stops aliasing
+    // `--surface-inset`, THIS is what tells us the guard above went blind.
+    expect(resolveAlias('--muted')).toContain('--surface-inset')
+    expect(resolveAlias('--border-strong')).toEqual(['--border-strong'])
+  })
+})