nuvox 0.1.5 → 0.1.6

package/BUILDING-COMPONENTS.md

@@ -1,554 +1,556 @@
-# Building Components on the Nuvox Foundation
-
-This is the how-to that sits next to `CONTRACT.md`. CONTRACT.md is the
-rulebook (why each rule exists). This document is the *procedure* —
-what order to build things in, what file goes where, and what each
-category of component specifically needs, so you're not re-deriving
-the process for every one of the ~44 components you'll eventually
-build.
-
-Every component in the old Nuvox fell into one of six shapes. Each
-shape has different requirements beyond the universal ones. Find your
-component's category below, but read the **Universal build order**
-first — it applies regardless of category.
-
----
-
-## Universal build order (every component, no exceptions)
-
-Build in this order. Don't skip ahead to the React file before the
-core file exists — that ordering is itself part of the contract
-(Rule: architecture before features, applied at the single-component
-scale).
-
-```
-1. src/core/<name>.ts         — pure logic, no JSX, no DOM
-2. src/react/<Name>.tsx       — thin wrapper consuming the core logic
-3. src/react/<Name>.css       — CSS variables only, no hardcoded values
-4. tests/<name>.test.tsx      — written and RUN before you call it done
-```
-
-### 1. Core file (`src/core/<name>.ts`)
-Pure functions only. No `import React`, no JSX, ever — this is what
-makes the component portable to a future Vue/Angular adapter for free.
-
-```ts
-import type { Size, Variant } from "./types";
-
-export interface <Name>Props {
-  size?: Size;
-  variant?: Variant;
-  disabled?: boolean;
-  // ...component-specific props
-}
-
-export interface <Name>State {
-  size: Size;
-  variant: Variant;
-  isDisabled: boolean;
-  // ...resolved values
-}
-
-export function resolve<Name>State(props: <Name>Props): <Name>State {
-  return {
-    size: props.size ?? "md",       // always ??, never ||  (Rule 3)
-    variant: props.variant ?? "solid",
-    isDisabled: props.disabled ?? false,
-  };
-}
-
-export function get<Name>Classes(state: <Name>State): string {
-  return ["nx-<name>", `nx-<name>--${state.size}`, `nx-<name>--${state.variant}`]
-    .filter(Boolean)
-    .join(" ");
-}
-```
-
-### 2. React file (`src/react/<Name>.tsx`)
-```tsx
-import { forwardRef } from "react";                       // Rule 4
-import { resolve<Name>State, get<Name>Classes } from "../core/<name>";
-import type { BaseComponentProps } from "../core/types";    // Rule 2
-import { withThemeOverride, withAccentOverride } from "../theme-engine/NuvoxProvider"; // Rule 5 / 5b
-
-interface <Name>Props extends BaseComponentProps, /* core props */ {}
-
-export const <Name> = forwardRef<HTMLElement, <Name>Props>(function <Name>(
-  { className, style, theme, color, ...rest }, ref
-) {
-  const state = resolve<Name>State(rest);
-  const classes = [get<Name>Classes(state), className].filter(Boolean).join(" ");
-  const el = <div ref={ref} className={classes} style={style}>{/* ... */}</div>;
-  // theme = shape, color = accent — independent, apply both (Rule 5b).
-  return withThemeOverride(theme, withAccentOverride(color, el));
-});
-```
-
-### 3. CSS file (`src/react/<Name>.css`)
-Every value is a `var(--x, fallback)`. Never a literal color, radius,
-shadow, or duration.
-```css
-.nx-<name> {
-  border-radius: var(--radius-md);
-  padding: var(--spacing-sm) var(--spacing-md);
-  background: var(--color-surface);
-  transition: all var(--motion-durationFast) var(--motion-easeStandard);
-}
-```
-
-**Import it in the `.tsx` file** — `import "./<Name>.css";` near the
-top of `<Name>.tsx`. This step is easy to silently skip: the class
-names in `get<Name>Classes()` will apply to the DOM either way with
-no error from TypeScript, ESLint, or the test suite, so a component
-can look completely correct in code review while rendering as an
-unstyled, un-themed native element. This exact bug happened to
-Button in this project's own foundation — caught only by looking at
-the docs site's live `<Preview>` and noticing every variant/theme
-rendered identically. Add a `<Preview>` example to the component's
-`.mdx` page and actually look at it (`npm run docs:dev`) before
-considering a component done — the automated tests don't currently
-catch a missing CSS import, since none of them assert on computed
-styles.
-
-### 4. Tests (`tests/<name>.test.tsx`)
-Minimum four, per CONTRACT.md Rule 8 — more if the component is
-complex:
-```tsx
-it("renders with default props", () => { /* ... */ });
-it("scopes a theme/color override to just this component", () => { /* ... */ });
-it("forwards its ref", () => { /* ... */ });          // if applicable
-it("propagates theme correctly through its portal", () => { /* ... */ }); // if applicable
-```
-
-Run `npm test` and `npm run typecheck` before moving to the next
-component. Not after five components — after each one.
-
----
-
-## Category A — Static / display primitives
-**Examples:** Badge, Avatar, Divider, Skeleton, Spinner, Progress,
-Card, Alert, Tag
-
-**What makes this category different:** no interactivity, often no
-portal, sometimes no ref target at all (Divider).
-
-**What to keep:**
-- Core file still exists even for something this simple — resist the
-  urge to inline the logic directly in the `.tsx` file. It costs
-  nothing today and is what makes a future Vue port of Card free.
-- `color` is no longer category-specific — it's on `BaseComponentProps`
-  for every component now (the accent override, see CONTRACT.md Rule
-  5b), so every component gets it whether it's in this category or
-  not. What IS still a legitimate category-A-specific choice is
-  `radius` as an extra override prop (this was the old codebase's
-  pattern, on 2/41 components, both in this category) — display
-  primitives are the case where overriding a single shape property
-  without a full theme override makes sense. Keep it consistent: if
-  `Card` gets a `radius` prop, `Skeleton` should offer it the same
-  way, not a differently-shaped prop.
-- **Ref exemption check (Rule 4):** Divider is a legitimate exemption
-  (no focusable/interactive element). Badge, Avatar, Card are NOT —
-  they render a real DOM node and should forward.
-- No portal, no overlay tests needed.
-
-**Test minimum:** default render + theme/color override + ref forwarding
-(skip ref only for genuine layout-only elements like Divider).
-
----
-
-## Category B — Form / input primitives
-**Examples:** Input, Textarea, Checkbox, Radio, Toggle, NumberInput,
-Slider, OTPInput, PhoneInput, FileUpload
-
-**What makes this category different:** controlled/uncontrolled state,
-a value the consumer cares about, validation/error states, and — this
-is the category form libraries actually need refs for.
-
-**What to keep:**
-- **Ref forwarding is non-negotiable here** — this is exactly the
-  category (Input, Checkbox, etc.) where the old codebase's 1-of-41
-  problem actually costs real integration pain (react-hook-form,
-  Formik, imperative `.focus()` on validation error).
-- Support both controlled (`value` + `onChange`) and uncontrolled
-  (`defaultValue`) the same way React's native `<input>` does — don't
-  invent a third pattern.
-- Standard props every component in this category should share:
-  `value`/`defaultValue`, `onChange`, `disabled`, `error` (or
-  `invalid`), `placeholder` where applicable. Decide this shape once,
-  here, rather than letting Input and NumberInput drift (the old
-  color/radius drift, one category up).
-- `aria-invalid` and `aria-describedby` (for an error message) are
-  part of this category's baseline, the same way Rule 11 sets a
-  baseline for overlays — worth stating explicitly even though
-  CONTRACT.md's Rule 11 is scoped to overlays specifically.
-
-**Test minimum:** default render + ref forwarding (mandatory) +
-theme/color override + a controlled-value test (typing/changing updates
-what the consumer expects) + an error/invalid-state test.
-
----
-
-## Category C — Overlay / portal components (non-composite)
-**Examples:** Modal, Drawer, Tooltip, Toast, ContextMenu, Tour
-
-**What makes this category different:** this is exactly the category
-that broke in the old codebase (3 of 15 portal components missing the
-theme fix). Treat every rule here as load-bearing, not optional.
-
-**What to keep:**
-- **Always render through `ThemedPortal`, never `createPortal`
-  directly (Rule 6).** No exceptions, no "this one's simple enough to
-  skip it" — that reasoning is exactly how Toast and Tooltip broke
-  last time.
-- **Always implement the Rule 11 accessibility baseline**: Escape to
-  close, focus trap, return focus to trigger, correct ARIA role
-  (`dialog` for Modal, `alert`/`status` for Toast, etc.). Build this
-  once as a shared `useOverlayBehavior()` hook and have every
-  component in this category use it — don't hand-roll focus trapping
-  five separate times the way the portal-theme fix got hand-rolled
-  twelve times.
-- Toast is a special case within this category: it's a *queue*, not a
-  single open/closed instance. Its state (the list of active toasts)
-  lives outside any individual themed subtree by nature — make sure
-  its `ThemedPortal` anchor is something stable (e.g. the toast
-  trigger call site, or fall back to whatever element is currently
-  focused) rather than assuming one obvious anchor the way Popover
-  can.
-- `Tooltip` needs hover AND focus triggers (not just `onMouseEnter`) —
-  a keyboard user tabbing to a button needs to see its tooltip too.
-
-**Test minimum:** default render + `ThemedPortal` theme propagation
-(mandatory) + Escape-closes + focus-returns-to-trigger + ARIA role
-present. This category needs the full Rule 8 floor plus the
-accessibility-specific tests — don't stop at four.
-
----
-
-## Category D — Composite overlay + input components
-**Examples:** Select, Combobox, DatePicker, ColorPicker, Command
-
-**What makes this category different:** this is exactly what Rule 12
-(composition) is for. This category is where the old codebase's
-"components know too much" problem would show up hardest if repeated.
-
-**What to keep:**
-- **Compose, don't reimplement (Rule 12).** A `Select` is: an `Input`
-  or trigger button (Category B/A) + a `ThemedPortal`-based panel
-  (Category C's pattern) + a shared keyboard-navigable list primitive.
-  Build that list primitive (`ListBox` — arrow-key navigation, typeahead,
-  active-descendant ARIA wiring) **once**, and have Select, Combobox,
-  and Command all use it instead of each implementing arrow-key
-  handling separately.
-- `DatePicker` composes: an `Input` (for the text value) + `Popover`
-  (for the calendar panel) + a calendar-grid primitive. The calendar
-  grid itself is a good candidate for a shared internal primitive if
-  you ever add a date-range picker later — don't decide that now, just
-  don't make the calendar grid *only* reachable from inside DatePicker
-  in a way that'd make reuse painful.
-- These inherit Category C's overlay requirements in full (ThemedPortal,
-  `useOverlayBehavior`) *and* Category B's input requirements in full
-  (ref forwarding on the visible input/trigger, controlled/uncontrolled
-  value). Don't drop either set of requirements because the component
-  is "mostly a Select, not really an Input."
-
-**Test minimum:** everything from both Category B and Category C's
-minimums, plus one test proving keyboard navigation through the list
-(arrow down moves the active option, Enter selects it).
-
----
-
-## Category E — Navigation / structural components
-**Examples:** Tabs, Accordion, Breadcrumb, Pagination
-
-**What makes this category different:** state is about *which item is
-active*, not a portal, not a value being typed. Usually no portal at
-all.
-
-**What to keep:**
-- **Same `value` + `onChange` (controlled) / `defaultValue`
-  (uncontrolled) convention as Category B, applied to "which item is
-  active" instead of "what's typed."** Not `onValueChange` — there is
-  exactly one controlled-state prop name across this entire library,
-  regardless of category, and it's `onChange`. (This had to be fixed
-  once already — Tabs and Accordion shipped with `onValueChange` in
-  0.1.0/0.1.1 because this line didn't exist yet. See `tests/no-on-value-change.test.ts`,
-  which now fails the build if this drifts again.)
-- Roving `tabIndex` pattern for keyboard nav within the group (Tabs,
-  Accordion) — only the active tab is in the natural tab order; arrow
-  keys move between siblings. This is the same class of "accessibility
-  baseline" as Rule 11, just for a different interaction shape — worth
-  treating with the same seriousness even though it's not a portal
-  component.
-- `aria-selected`/`aria-expanded` and matching `role="tablist"` /
-  `role="tab"` / `role="tabpanel"` etc. — get the ARIA pattern right
-  once (Tabs) and Accordion's is nearly identical, so build the second
-  one by extending the first's approach, not from scratch.
-- Ref forwarding still applies to the interactive elements (each tab
-  button, each pagination button) even though the outer container
-  might not need one.
-
-**Test minimum:** default render + ref forwarding on interactive
-children + keyboard navigation between items + ARIA state updates on
-selection change.
-
----
-
-## Category F — Complex / stateful components
-**Examples:** Table, Treeview, Kanban, Carousel, Timeline, ChatBubble
-
-**What makes this category different:** these are the components most
-likely to become monoliths again if you're not deliberate, because
-each one genuinely has a lot of internal state (Kanban was 1,372 lines
-in the old codebase — by far the largest).
-
-**What to keep:**
-- **Decompose on paper before writing code (this is Phase 1/Phase 2
-  from your own original retro, applied per-component now instead of
-  project-wide).** Before writing `Kanban.tsx`, write down its
-  sub-pieces: `KanbanBoard`, `KanbanColumn`, `KanbanCard`,
-  a drag-context hook. Build and test the sub-pieces individually
-  where possible, the same way `Select` composes `Input` + `Popover` +
-  `ListBox` in Category D.
-- If a sub-piece needs its own portal (a Kanban card being dragged
-  needs to render above everything, which is effectively an overlay),
-  it follows Category C's rules too — this is likely where "Kanban
-  missing the theme fix" happened last time, because the drag layer
-  wasn't recognized as "a portal component" the way Modal obviously is.
-- These components justify the most tests, per Rule 8's "floor, not
-  ceiling" — expect 15–30 meaningful tests for something like Kanban,
-  covering drag-and-drop state transitions, keyboard-accessible
-  reordering (don't ship drag-and-drop as the *only* way to reorder —
-  that's an accessibility gap, not just a nice-to-have), and the
-  virtualized-rendering edge cases if the list can get long.
-- Table specifically: sorting/filtering state should be lifted to
-  props the consumer can control (controlled sort state), not trapped
-  entirely inside the component, the same way Input supports
-  controlled `value`.
-
-**Test minimum:** default render + ref forwarding on the outer
-container + theme/color override + portal theming for any internal overlay
-(drag layer, cell editor, etc.) + a dedicated test per major state
-transition specific to the component (drag-drop for Kanban, sort-order
-for Table, expand/collapse for Treeview).
-
----
-
-## Quick-reference: which categories need what
-
-| Requirement | A: Static | B: Form | C: Overlay | D: Composite | E: Nav | F: Complex |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| Core/React split | Yes | Yes | Yes | Yes | Yes | Yes |
-| Ref forwarding | Usually | **Always** | Yes | Yes | Yes (children) | Yes |
-| `ThemedPortal` | No | No | **Always** | **Always** | No | Sometimes (drag layer, cell editor) |
-| `useOverlayBehavior` (Rule 11) | No | No | **Always** | **Always** | No | If it has an overlay |
-| Composition over reimplementation (Rule 12) | N/A | N/A | N/A | **Core requirement** | Some | **Core requirement** |
-| Controlled/uncontrolled value | No | **Always** | Yes (selection) | Yes | Sometimes (active tab) | Yes |
-| Test minimum (beyond Rule 8's 4) | none extra | +controlled-value, +error-state | +Escape, +focus-return, +ARIA role | Category B + C combined | +keyboard-nav, +ARIA state | +per-state-transition |
-
----
-
-## Component build checklist (copy this per component)
-
-```
-[ ] src/core/<name>.ts written — pure logic, ?? not ||, canonical Size/Variant types
-[ ] src/react/<Name>.tsx written — forwardRef (unless genuinely exempt),
-    BaseComponentProps extended, BOTH withThemeOverride AND withAccentOverride
-    wired (accepting theme/color without applying them is worse than not
-    accepting them at all)
-[ ] src/react/<Name>.css written — every value is var(--x, fallback)
-[ ] If it portals: uses ThemedPortal, not createPortal
-[ ] If it's an overlay: Escape/focus-trap/ARIA via useOverlayBehavior
-[ ] If it composes other components: uses the real component, not a reimplementation
-[ ] tests/<name>.test.tsx — Rule 8 floor + category-specific tests, written and RUN
-[ ] npm run typecheck — clean
-[ ] npm test — full suite still green, not just the new file
-[ ] docs-site/content/docs/components/<name>.mdx — import interactive
-    components from @/components/nuvox-client (not nuvox directly),
-    use <Preview> for a real live-rendered example, added to that
-    folder's meta.json, verified via npm run docs:build + grepping the
-    prerendered HTML for the component's actual class names (a
-    successful build alone doesn't prove the live preview rendered —
-    see NUVOX-COMPLETE-REFERENCE.md Part 12)
-```
-
----
-
-## Full component list — what each one needs
-
-All 42 components from the original Nuvox, categorized, with the
-requirements from the quick-reference table above applied per
-component instead of per category. Use this as the actual build
-checklist source — pick a row, build it, check the boxes.
-
-**Legend:** ✅ required &nbsp;·&nbsp; ❌ not required &nbsp;·&nbsp;
-➖ not applicable &nbsp;·&nbsp; 🟡 conditional / partial &nbsp;·&nbsp;
-🛠️ already built &nbsp;·&nbsp; ⬜ not built yet
-
-**`theme` and `color` overrides aren't columns here** — unlike the
-other requirements, they're universal via `BaseComponentProps` (Rule
-2/5/5b), so every single component below needs both wired, not just
-some categories. Missing columns for them isn't an oversight; a
-column that's ✅ on all 42 rows wouldn't tell you anything a table is
-good at telling you.
-
-| # | Component | Category | Ref forward | ThemedPortal | Overlay a11y (Rule 11) | Composes (Rule 12) | Controlled value | Status |
-|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
-| 1 | Button | B | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 2 | Popover | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 3 | Avatar | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 4 | Badge | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 5 | Card | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 6 | Divider | A | ✅ *(exempt per Rule 4, forwarded anyway)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 7 | Progress | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 8 | Skeleton | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 9 | Spinner | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 10 | Alert | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 11 | ChatBubble | A | ✅ | ❌ | ❌ | ➖ | ❌ | ⬜ |
-| 12 | Timeline | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 13 | Input | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 14 | Textarea | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 15 | Checkbox | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 16 | Radio | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 17 | Toggle | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 18 | NumberInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 19 | Slider | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 20 | OTPInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 21 | PhoneInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
-| 22 | FileUpload | B | ✅ | ❌ | ❌ | 🟡 *(internal trigger button)* | ✅ | 🛠️ Built |
-| 23 | Modal | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 24 | Drawer | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 25 | Tooltip | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 26 | Toast | C | 🟡 *(queue, not a single instance)* | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 27 | ContextMenu | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
-| 28 | Tour | C | ✅ | ✅ | ✅ | ➖ | ❌ | ⬜ |
-| 29 | Dropdown | C | ✅ | ✅ | ✅ | 🟡 *(reuses `core/collection` from Category D)* | ❌ | 🛠️ Built *(as `DropdownMenu`)* |
-| 30 | Select | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
-| 31 | Combobox | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
-| 32 | DatePicker | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built *(+ standalone `Calendar`, `core/calendar.ts`)* |
-| 33 | ColorPicker | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
-| 34 | Command | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built *(as `CommandPalette`)* |
-| 35 | Accordion | E | ✅ *(items)* | ❌ | ❌ *(own roving-tabindex baseline instead)* | ➖ | ✅ *(expanded index)* | 🛠️ Built |
-| 36 | Tabs | E | ✅ *(tabs)* | ❌ | ❌ *(own roving-tabindex baseline instead)* | ➖ | ✅ *(active tab)* | 🛠️ Built |
-| 37 | Breadcrumb | E | ✅ *(links)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
-| 38 | Pagination | E | ✅ *(buttons)* | ❌ | ❌ | ➖ | ✅ *(current page)* | 🛠️ Built |
-| 39 | Table | F | ✅ | 🟡 *(only if cell editor overlays)* | 🟡 *(only if it has an overlay)* | ✅ | ✅ *(sort/filter state)* | 🛠️ Built |
-| 40 | Treeview | F | ✅ | ❌ | ❌ | ✅ | ✅ *(expanded/selected)* | ⬜ |
-| 41 | Kanban | F | ✅ | 🟡 *(drag layer)* | 🟡 *(drag layer)* | ✅ | ✅ *(board state)* | ⬜ |
-| 42 | Carousel | F | ✅ | ❌ | ❌ *(own baseline: arrow keys, pause-on-hover, not Rule 11)* | ✅ | ✅ *(active slide)* | 🛠️ Built |
-| 43 | Rating | B | ✅ | ❌ | ❌ | ➖ | ✅ *(selected value)* | 🛠️ Built *(added outside the original plan — a single-value control, same shape as Slider)* |
-| 44 | StatCard | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built *(added outside the original plan — composes `Card` for chrome)* |
-| 45 | CodeBlock | A | ✅ *(forwards to the scrollable `<pre>`)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built *(added outside the original plan — tokenizer lives in the shared `core/code-highlight.ts` primitive, not owned solely by this component; `highlighter` prop is a pluggable escape hatch, see that file's header)* |
-| 46 | RichTextEditor | F | ✅ *(`RichTextContent` forwards to the contentEditable element)* | ➖ *(the link editor's popover panel portals via the real `Popover`, not directly)* | ➖ *(inherited transitively through `Popover`)* | ✅ *(link editor composes `Popover`, Rule 12)* | ✅ *(`value`/`onChange`, HTML string)* | 🛠️ Built *(added outside the original plan — by far the largest component; deliberately NOT a ProseMirror-style document model, see `core/rich-text.ts`'s header for the v1 scope boundary and the `engine` escape hatch for consumers who need one)* |
-
-A few things worth noting from the table itself, not just the rows:
-
-- **Category C has 8 components and all 8 need `ThemedPortal` +
-  the Rule 11 baseline with no exceptions** — this is the exact
-  category that produced the 3-missing-out-of-15 bug last time.
-  If you ever mark a ❌ in either of those columns for a Category C
-  component, stop and double check it actually belongs in Category A
-  or E instead.
-- **Toast and Dropdown are the two 🟡 rows in Category C** — both
-  for real structural reasons (Toast is a queue; Dropdown reuses
-  `core/collection.ts`, Category D's list primitive), not because the
-  rule is optional for them. Don't let "it's a bit different" quietly
-  become "it's exempt."
-- **Table, Kanban's conditional portal/a11y columns are the most likely
-  place to repeat the old bug** — a drag layer or cell editor is an
-  overlay in every way that matters, even though the component's name
-  doesn't obviously say "overlay" the way Modal's does. Flag it
-  explicitly in that component's own file comments once you decide
-  whether it applies.
-
-
-Build roughly in this category order, not alphabetically and not by
-whichever component sounds fun that day:
-
-1. **Button is settled; Categories A, B, C, D, and E are all proven
-   out now.** Input, Textarea, Checkbox, Radio, Toggle, and Slider
-   (Category B) share `core/field.ts`'s disabled/required/invalid/
-   size shape. Badge, Avatar, Spinner, Divider, Card, Alert, and
-   Progress (Category A) consistently derive booleans like
-   "dismissible" or "clickable" from whether a handler was actually
-   passed (`onDismiss`, `onClick`) rather than adding a redundant flag
-   prop. Modal, Tooltip, Toast, Dropdown, Popover, and CommandPalette
-   (Category C) share `useOverlayBehavior`
-   (Escape/focus-trap/return-focus) and `core/floating.ts` (anchor
-   positioning). Select, Combobox, and DatePicker (Category D) all
-   compose across categories rather than picking one — Select and
-   Combobox both reuse Input's field shape AND Category C's overlay
-   stack; DatePicker goes one step further and composes Popover
-   itself (not just Popover's underlying hooks) plus a standalone
-   Calendar component. Tabs and Accordion (Category E) share
-   `useRovingFocus`. `core/collection.ts` (arrow-key nav + typeahead)
-   is the one primitive proven across three different categories at
-   once — Dropdown (C), Select and Combobox (D), and CommandPalette
-   (D) all call the exact same functions.
-2. **Category A is down to one: ChatBubble.** Timeline is done — same
-   proven conventions, no portal/overlay complexity. Skeleton is done;
-   it also settled a real-world edge case worth carrying forward: a
-   full-width block built from divs (not a native form element) needs
-   its own `inline-size: 100%` — nothing in the platform gives it one
-   for free the way `<input>` gets a UA-stylesheet default width. Any
-   future component in this shape should declare it explicitly rather
-   than rely on an ancestor happening to be definite-width.
-3. **Category B is fully built.** OTPInput and PhoneInput both landed
-   — the ref-forwarding and controlled-value conventions were already
-   established by Input/Checkbox/Slider/NumberInput/etc. FileUpload is
-   the reference for Rule 12 inside Category B specifically: its
-   "Browse" trigger composes the real `Button` rather than hand-styling
-   a second one, exactly what the `🟡 (internal trigger button)` note
-   in the table called for.
-4. **Category D is fully built.** ColorPicker landed following the
-   same "compose Input's field shape + Popover + a new pure-logic
-   grid/wheel module" shape DatePicker established — Select, Combobox,
-   and DatePicker had already proven Rule 12 held here.
-5. **The rest of Category C** (Tour) — Drawer and ContextMenu are
-   done and confirm the prediction: both really were mostly a new
-   visual shape on `useOverlayBehavior`/`core/floating.ts`'s existing,
-   tested infrastructure. Drawer is a close copy of Modal.tsx with one
-   axis added (which edge, and "size" meaning width vs. height
-   depending on it). ContextMenu is DropdownMenu's sibling — same
-   portal/keyboard-nav machinery, reusing DropdownMenu's own item
-   classes and pure logic (Rule 12) rather than duplicating them — with
-   the one real new piece being a "virtual anchor" (a zero-size element
-   moved to the click point) that lets `useFloatingPosition` position
-   relative to a cursor location it was never written to expect,
-   completely unmodified. Tour is the one left, and will need actual
-   new choreography (sequencing highlighted-element steps) that neither
-   Drawer nor ContextMenu needed.
-6. **The rest of Category E** — Breadcrumb and Pagination are done,
-   and turned out *not* to need `useRovingFocus`: that hook is for a
-   single widget where only one item belongs in the tab order at a
-   time (Tabs, Accordion). A breadcrumb trail and a pager are both
-   just several independently-useful links/buttons in normal tab
-   order, closer to a browser's own navigation than to a listbox —
-   worth checking which model actually fits before reaching for
-   `useRovingFocus` on a future Category E component.
-7. **Category F** — Table and Carousel are both done. Table is the
-   reference for "compose more than any other category": seven small
-   pieces on paper first (Table, TableHeader, TableBody, TableRow,
-   TableHead, TableCell, TableCaption) rather than one component
-   holding sorting, selection, and layout all at once. Sort state is
-   controlled by the consumer, the same shape as every value-holding
-   component in this library; row selection isn't modeled by Table at
-   all — a "select all"/row checkbox is just a real `Checkbox` (Rule
-   12) placed in a cell. Carousel followed the same decompose-first
-   approach (root, viewport, track, slide, prev/next, indicators) and
-   owns its own keyboard/pause-on-hover baseline rather than reusing
-   `useOverlayBehavior`, since it isn't an overlay. Treeview, Kanban,
-   and ChatBubble remain — each will need its own genuinely new
-   interaction model the way Table's sort/selection split did, rather
-   than being a rearrangement of an existing component's pieces.
-8. **Two components shipped outside this table's original plan:**
-   Rating (Category B — a single-value control, same conventions as
-   Slider) and StatCard (Category A — composes `Card` for its chrome).
-   Both follow every rule in `CONTRACT.md` the same as anything on
-   the original list; they're just proof this table is a starting
-   roadmap, not a hard ceiling on what Nuvox can become.
-
-If building a Category D or F component forces a change to the
-foundation (`ThemedPortal`, `useOverlayBehavior`, `core/types.ts`),
-that's a signal the foundation still has a gap — fix it there, not
-with a one-off workaround in the component. That's the whole point of
+# Building Components on the Nuvox Foundation
+
+This is the how-to that sits next to `CONTRACT.md`. CONTRACT.md is the
+rulebook (why each rule exists). This document is the *procedure* —
+what order to build things in, what file goes where, and what each
+category of component specifically needs, so you're not re-deriving
+the process for every one of the ~44 components you'll eventually
+build.
+
+Every component in the old Nuvox fell into one of six shapes. Each
+shape has different requirements beyond the universal ones. Find your
+component's category below, but read the **Universal build order**
+first — it applies regardless of category.
+
+---
+
+## Universal build order (every component, no exceptions)
+
+Build in this order. Don't skip ahead to the React file before the
+core file exists — that ordering is itself part of the contract
+(Rule: architecture before features, applied at the single-component
+scale).
+
+```
+1. src/core/<name>.ts         — pure logic, no JSX, no DOM
+2. src/react/<Name>.tsx       — thin wrapper consuming the core logic
+3. src/react/<Name>.css       — CSS variables only, no hardcoded values
+4. tests/<name>.test.tsx      — written and RUN before you call it done
+```
+
+### 1. Core file (`src/core/<name>.ts`)
+Pure functions only. No `import React`, no JSX, ever — this is what
+makes the component portable to a future Vue/Angular adapter for free.
+
+```ts
+import type { Size, Variant } from "./types";
+
+export interface <Name>Props {
+  size?: Size;
+  variant?: Variant;
+  disabled?: boolean;
+  // ...component-specific props
+}
+
+export interface <Name>State {
+  size: Size;
+  variant: Variant;
+  isDisabled: boolean;
+  // ...resolved values
+}
+
+export function resolve<Name>State(props: <Name>Props): <Name>State {
+  return {
+    size: props.size ?? "md",       // always ??, never ||  (Rule 3)
+    variant: props.variant ?? "solid",
+    isDisabled: props.disabled ?? false,
+  };
+}
+
+export function get<Name>Classes(state: <Name>State): string {
+  return ["nx-<name>", `nx-<name>--${state.size}`, `nx-<name>--${state.variant}`]
+    .filter(Boolean)
+    .join(" ");
+}
+```
+
+### 2. React file (`src/react/<Name>.tsx`)
+```tsx
+import { forwardRef } from "react";                       // Rule 4
+import { resolve<Name>State, get<Name>Classes } from "../core/<name>";
+import type { BaseComponentProps } from "../core/types";    // Rule 2
+import { withThemeOverride, withAccentOverride } from "../theme-engine/NuvoxProvider"; // Rule 5 / 5b
+
+interface <Name>Props extends BaseComponentProps, /* core props */ {}
+
+export const <Name> = forwardRef<HTMLElement, <Name>Props>(function <Name>(
+  { className, style, theme, color, ...rest }, ref
+) {
+  const state = resolve<Name>State(rest);
+  const classes = [get<Name>Classes(state), className].filter(Boolean).join(" ");
+  const el = <div ref={ref} className={classes} style={style}>{/* ... */}</div>;
+  // theme = shape, color = accent — independent, apply both (Rule 5b).
+  return withThemeOverride(theme, withAccentOverride(color, el));
+});
+```
+
+### 3. CSS file (`src/react/<Name>.css`)
+Every value is a `var(--x, fallback)`. Never a literal color, radius,
+shadow, or duration.
+```css
+.nx-<name> {
+  border-radius: var(--radius-md);
+  padding: var(--spacing-sm) var(--spacing-md);
+  background: var(--color-surface);
+  transition: all var(--motion-durationFast) var(--motion-easeStandard);
+}
+```
+
+**Import it in the `.tsx` file** — `import "./<Name>.css";` near the
+top of `<Name>.tsx`. This step is easy to silently skip: the class
+names in `get<Name>Classes()` will apply to the DOM either way with
+no error from TypeScript, ESLint, or the test suite, so a component
+can look completely correct in code review while rendering as an
+unstyled, un-themed native element. This exact bug happened to
+Button in this project's own foundation — caught only by looking at
+the docs site's live `<Preview>` and noticing every variant/theme
+rendered identically. Add a `<Preview>` example to the component's
+`.mdx` page and actually look at it (`npm run docs:dev`) before
+considering a component done — the automated tests don't currently
+catch a missing CSS import, since none of them assert on computed
+styles.
+
+### 4. Tests (`tests/<name>.test.tsx`)
+Minimum four, per CONTRACT.md Rule 8 — more if the component is
+complex:
+```tsx
+it("renders with default props", () => { /* ... */ });
+it("scopes a theme/color override to just this component", () => { /* ... */ });
+it("forwards its ref", () => { /* ... */ });          // if applicable
+it("propagates theme correctly through its portal", () => { /* ... */ }); // if applicable
+```
+
+Run `npm test` and `npm run typecheck` before moving to the next
+component. Not after five components — after each one.
+
+---
+
+## Category A — Static / display primitives
+**Examples:** Badge, Avatar, Divider, Skeleton, Spinner, Progress,
+Card, Alert, Tag
+
+**What makes this category different:** no interactivity, often no
+portal, sometimes no ref target at all (Divider).
+
+**What to keep:**
+- Core file still exists even for something this simple — resist the
+  urge to inline the logic directly in the `.tsx` file. It costs
+  nothing today and is what makes a future Vue port of Card free.
+- `color` is no longer category-specific — it's on `BaseComponentProps`
+  for every component now (the accent override, see CONTRACT.md Rule
+  5b), so every component gets it whether it's in this category or
+  not. What IS still a legitimate category-A-specific choice is
+  `radius` as an extra override prop (this was the old codebase's
+  pattern, on 2/41 components, both in this category) — display
+  primitives are the case where overriding a single shape property
+  without a full theme override makes sense. Keep it consistent: if
+  `Card` gets a `radius` prop, `Skeleton` should offer it the same
+  way, not a differently-shaped prop.
+- **Ref exemption check (Rule 4):** Divider is a legitimate exemption
+  (no focusable/interactive element). Badge, Avatar, Card are NOT —
+  they render a real DOM node and should forward.
+- No portal, no overlay tests needed.
+
+**Test minimum:** default render + theme/color override + ref forwarding
+(skip ref only for genuine layout-only elements like Divider).
+
+---
+
+## Category B — Form / input primitives
+**Examples:** Input, Textarea, Checkbox, Radio, Toggle, NumberInput,
+Slider, OTPInput, PhoneInput, FileUpload
+
+**What makes this category different:** controlled/uncontrolled state,
+a value the consumer cares about, validation/error states, and — this
+is the category form libraries actually need refs for.
+
+**What to keep:**
+- **Ref forwarding is non-negotiable here** — this is exactly the
+  category (Input, Checkbox, etc.) where the old codebase's 1-of-41
+  problem actually costs real integration pain (react-hook-form,
+  Formik, imperative `.focus()` on validation error).
+- Support both controlled (`value` + `onChange`) and uncontrolled
+  (`defaultValue`) the same way React's native `<input>` does — don't
+  invent a third pattern.
+- Standard props every component in this category should share:
+  `value`/`defaultValue`, `onChange`, `disabled`, `error` (or
+  `invalid`), `placeholder` where applicable. Decide this shape once,
+  here, rather than letting Input and NumberInput drift (the old
+  color/radius drift, one category up).
+- `aria-invalid` and `aria-describedby` (for an error message) are
+  part of this category's baseline, the same way Rule 11 sets a
+  baseline for overlays — worth stating explicitly even though
+  CONTRACT.md's Rule 11 is scoped to overlays specifically.
+
+**Test minimum:** default render + ref forwarding (mandatory) +
+theme/color override + a controlled-value test (typing/changing updates
+what the consumer expects) + an error/invalid-state test.
+
+---
+
+## Category C — Overlay / portal components (non-composite)
+**Examples:** Modal, Drawer, Tooltip, Toast, ContextMenu, Tour
+
+**What makes this category different:** this is exactly the category
+that broke in the old codebase (3 of 15 portal components missing the
+theme fix). Treat every rule here as load-bearing, not optional.
+
+**What to keep:**
+- **Always render through `ThemedPortal`, never `createPortal`
+  directly (Rule 6).** No exceptions, no "this one's simple enough to
+  skip it" — that reasoning is exactly how Toast and Tooltip broke
+  last time.
+- **Always implement the Rule 11 accessibility baseline**: Escape to
+  close, focus trap, return focus to trigger, correct ARIA role
+  (`dialog` for Modal, `alert`/`status` for Toast, etc.). Build this
+  once as a shared `useOverlayBehavior()` hook and have every
+  component in this category use it — don't hand-roll focus trapping
+  five separate times the way the portal-theme fix got hand-rolled
+  twelve times.
+- Toast is a special case within this category: it's a *queue*, not a
+  single open/closed instance. Its state (the list of active toasts)
+  lives outside any individual themed subtree by nature — make sure
+  its `ThemedPortal` anchor is something stable (e.g. the toast
+  trigger call site, or fall back to whatever element is currently
+  focused) rather than assuming one obvious anchor the way Popover
+  can.
+- `Tooltip` needs hover AND focus triggers (not just `onMouseEnter`) —
+  a keyboard user tabbing to a button needs to see its tooltip too.
+
+**Test minimum:** default render + `ThemedPortal` theme propagation
+(mandatory) + Escape-closes + focus-returns-to-trigger + ARIA role
+present. This category needs the full Rule 8 floor plus the
+accessibility-specific tests — don't stop at four.
+
+---
+
+## Category D — Composite overlay + input components
+**Examples:** Select, Combobox, DatePicker, ColorPicker, Command
+
+**What makes this category different:** this is exactly what Rule 12
+(composition) is for. This category is where the old codebase's
+"components know too much" problem would show up hardest if repeated.
+
+**What to keep:**
+- **Compose, don't reimplement (Rule 12).** A `Select` is: an `Input`
+  or trigger button (Category B/A) + a `ThemedPortal`-based panel
+  (Category C's pattern) + a shared keyboard-navigable list primitive.
+  Build that list primitive (`ListBox` — arrow-key navigation, typeahead,
+  active-descendant ARIA wiring) **once**, and have Select, Combobox,
+  and Command all use it instead of each implementing arrow-key
+  handling separately.
+- `DatePicker` composes: an `Input` (for the text value) + `Popover`
+  (for the calendar panel) + a calendar-grid primitive. The calendar
+  grid itself is a good candidate for a shared internal primitive if
+  you ever add a date-range picker later — don't decide that now, just
+  don't make the calendar grid *only* reachable from inside DatePicker
+  in a way that'd make reuse painful.
+- These inherit Category C's overlay requirements in full (ThemedPortal,
+  `useOverlayBehavior`) *and* Category B's input requirements in full
+  (ref forwarding on the visible input/trigger, controlled/uncontrolled
+  value). Don't drop either set of requirements because the component
+  is "mostly a Select, not really an Input."
+
+**Test minimum:** everything from both Category B and Category C's
+minimums, plus one test proving keyboard navigation through the list
+(arrow down moves the active option, Enter selects it).
+
+---
+
+## Category E — Navigation / structural components
+**Examples:** Tabs, Accordion, Breadcrumb, Pagination
+
+**What makes this category different:** state is about *which item is
+active*, not a portal, not a value being typed. Usually no portal at
+all.
+
+**What to keep:**
+- **Same `value` + `onChange` (controlled) / `defaultValue`
+  (uncontrolled) convention as Category B, applied to "which item is
+  active" instead of "what's typed."** Not `onValueChange` — there is
+  exactly one controlled-state prop name across this entire library,
+  regardless of category, and it's `onChange`. (This had to be fixed
+  once already — Tabs and Accordion shipped with `onValueChange` in
+  0.1.0/0.1.1 because this line didn't exist yet. See `tests/no-on-value-change.test.ts`,
+  which now fails the build if this drifts again.)
+- Roving `tabIndex` pattern for keyboard nav within the group (Tabs,
+  Accordion) — only the active tab is in the natural tab order; arrow
+  keys move between siblings. This is the same class of "accessibility
+  baseline" as Rule 11, just for a different interaction shape — worth
+  treating with the same seriousness even though it's not a portal
+  component.
+- `aria-selected`/`aria-expanded` and matching `role="tablist"` /
+  `role="tab"` / `role="tabpanel"` etc. — get the ARIA pattern right
+  once (Tabs) and Accordion's is nearly identical, so build the second
+  one by extending the first's approach, not from scratch.
+- Ref forwarding still applies to the interactive elements (each tab
+  button, each pagination button) even though the outer container
+  might not need one.
+
+**Test minimum:** default render + ref forwarding on interactive
+children + keyboard navigation between items + ARIA state updates on
+selection change.
+
+---
+
+## Category F — Complex / stateful components
+**Examples:** Table, Treeview, Kanban, Carousel, Timeline, ChatBubble
+
+**What makes this category different:** these are the components most
+likely to become monoliths again if you're not deliberate, because
+each one genuinely has a lot of internal state (Kanban was 1,372 lines
+in the old codebase — by far the largest).
+
+**What to keep:**
+- **Decompose on paper before writing code (this is Phase 1/Phase 2
+  from your own original retro, applied per-component now instead of
+  project-wide).** Before writing `Kanban.tsx`, write down its
+  sub-pieces: `KanbanBoard`, `KanbanColumn`, `KanbanCard`,
+  a drag-context hook. Build and test the sub-pieces individually
+  where possible, the same way `Select` composes `Input` + `Popover` +
+  `ListBox` in Category D.
+- If a sub-piece needs its own portal (a Kanban card being dragged
+  needs to render above everything, which is effectively an overlay),
+  it follows Category C's rules too — this is likely where "Kanban
+  missing the theme fix" happened last time, because the drag layer
+  wasn't recognized as "a portal component" the way Modal obviously is.
+- These components justify the most tests, per Rule 8's "floor, not
+  ceiling" — expect 15–30 meaningful tests for something like Kanban,
+  covering drag-and-drop state transitions, keyboard-accessible
+  reordering (don't ship drag-and-drop as the *only* way to reorder —
+  that's an accessibility gap, not just a nice-to-have), and the
+  virtualized-rendering edge cases if the list can get long.
+- Table specifically: sorting/filtering state should be lifted to
+  props the consumer can control (controlled sort state), not trapped
+  entirely inside the component, the same way Input supports
+  controlled `value`.
+
+**Test minimum:** default render + ref forwarding on the outer
+container + theme/color override + portal theming for any internal overlay
+(drag layer, cell editor, etc.) + a dedicated test per major state
+transition specific to the component (drag-drop for Kanban, sort-order
+for Table, expand/collapse for Treeview).
+
+---
+
+## Quick-reference: which categories need what
+
+| Requirement | A: Static | B: Form | C: Overlay | D: Composite | E: Nav | F: Complex |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Core/React split | Yes | Yes | Yes | Yes | Yes | Yes |
+| Ref forwarding | Usually | **Always** | Yes | Yes | Yes (children) | Yes |
+| `ThemedPortal` | No | No | **Always** | **Always** | No | Sometimes (drag layer, cell editor) |
+| `useOverlayBehavior` (Rule 11) | No | No | **Always** | **Always** | No | If it has an overlay |
+| Composition over reimplementation (Rule 12) | N/A | N/A | N/A | **Core requirement** | Some | **Core requirement** |
+| Controlled/uncontrolled value | No | **Always** | Yes (selection) | Yes | Sometimes (active tab) | Yes |
+| Test minimum (beyond Rule 8's 4) | none extra | +controlled-value, +error-state | +Escape, +focus-return, +ARIA role | Category B + C combined | +keyboard-nav, +ARIA state | +per-state-transition |
+
+---
+
+## Component build checklist (copy this per component)
+
+```
+[ ] src/core/<name>.ts written — pure logic, ?? not ||, canonical Size/Variant types
+[ ] src/react/<Name>.tsx written — forwardRef (unless genuinely exempt),
+    BaseComponentProps extended, BOTH withThemeOverride AND withAccentOverride
+    wired (accepting theme/color without applying them is worse than not
+    accepting them at all)
+[ ] src/react/<Name>.css written — every value is var(--x, fallback)
+[ ] If it portals: uses ThemedPortal, not createPortal
+[ ] If it's an overlay: Escape/focus-trap/ARIA via useOverlayBehavior
+[ ] If it composes other components: uses the real component, not a reimplementation
+[ ] tests/<name>.test.tsx — Rule 8 floor + category-specific tests, written and RUN
+[ ] npm run typecheck — clean
+[ ] npm test — full suite still green, not just the new file
+[ ] docs-site/content/docs/components/<name>.mdx — import interactive
+    components from @/components/nuvox-client (not nuvox directly),
+    use <Preview> for a real live-rendered example, added to that
+    folder's meta.json, verified via npm run docs:build + grepping the
+    prerendered HTML for the component's actual class names (a
+    successful build alone doesn't prove the live preview rendered —
+    see NUVOX-COMPLETE-REFERENCE.md Part 12)
+```
+
+---
+
+## Full component list — what each one needs
+
+All 42 components from the original Nuvox, categorized, with the
+requirements from the quick-reference table above applied per
+component instead of per category. Use this as the actual build
+checklist source — pick a row, build it, check the boxes.
+
+**Legend:** ✅ required &nbsp;·&nbsp; ❌ not required &nbsp;·&nbsp;
+➖ not applicable &nbsp;·&nbsp; 🟡 conditional / partial &nbsp;·&nbsp;
+🛠️ already built &nbsp;·&nbsp; ⬜ not built yet
+
+**`theme` and `color` overrides aren't columns here** — unlike the
+other requirements, they're universal via `BaseComponentProps` (Rule
+2/5/5b), so every single component below needs both wired, not just
+some categories. Missing columns for them isn't an oversight; a
+column that's ✅ on all 42 rows wouldn't tell you anything a table is
+good at telling you.
+
+| # | Component | Category | Ref forward | ThemedPortal | Overlay a11y (Rule 11) | Composes (Rule 12) | Controlled value | Status |
+|---|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| 1 | Button | B | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 2 | Popover | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 3 | Avatar | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 4 | Badge | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 5 | Card | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 6 | Divider | A | ✅ *(exempt per Rule 4, forwarded anyway)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 7 | Progress | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 8 | Skeleton | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 9 | Spinner | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 10 | Alert | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 11 | ChatBubble | A | ✅ | ❌ | ❌ | ➖ | ❌ | ⬜ |
+| 12 | Timeline | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 13 | Input | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 14 | Textarea | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 15 | Checkbox | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 16 | Radio | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 17 | Toggle | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 18 | NumberInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 19 | Slider | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 20 | OTPInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 21 | PhoneInput | B | ✅ | ❌ | ❌ | ➖ | ✅ | 🛠️ Built |
+| 22 | FileUpload | B | ✅ | ❌ | ❌ | 🟡 *(internal trigger button)* | ✅ | 🛠️ Built |
+| 23 | Modal | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 24 | Drawer | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 25 | Tooltip | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 26 | Toast | C | 🟡 *(queue, not a single instance)* | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 27 | ContextMenu | C | ✅ | ✅ | ✅ | ➖ | ❌ | 🛠️ Built |
+| 28 | Tour | C | ✅ | ✅ | ✅ | ➖ | ❌ | ⬜ |
+| 29 | Dropdown | C | ✅ | ✅ | ✅ | 🟡 *(reuses `core/collection` from Category D)* | ❌ | 🛠️ Built *(as `DropdownMenu`)* |
+| 30 | Select | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
+| 31 | Combobox | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
+| 32 | DatePicker | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built *(+ standalone `Calendar`, `core/calendar.ts`)* |
+| 33 | ColorPicker | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built |
+| 34 | Command | D | ✅ | ✅ | ✅ | ✅ | ✅ | 🛠️ Built *(as `CommandPalette`)* |
+| 35 | Accordion | E | ✅ *(items)* | ❌ | ❌ *(own roving-tabindex baseline instead)* | ➖ | ✅ *(expanded index)* | 🛠️ Built |
+| 36 | Tabs | E | ✅ *(tabs)* | ❌ | ❌ *(own roving-tabindex baseline instead)* | ➖ | ✅ *(active tab)* | 🛠️ Built |
+| 37 | Breadcrumb | E | ✅ *(links)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built |
+| 38 | Pagination | E | ✅ *(buttons)* | ❌ | ❌ | ➖ | ✅ *(current page)* | 🛠️ Built |
+| 39 | Table | F | ✅ | 🟡 *(only if cell editor overlays)* | 🟡 *(only if it has an overlay)* | ✅ | ✅ *(sort/filter state)* | 🛠️ Built |
+| 40 | Treeview | F | ✅ | ❌ | ❌ | ✅ | ✅ *(expanded/selected)* | ⬜ |
+| 41 | Kanban | F | ✅ | 🟡 *(drag layer, cards and columns)* | 🟡 *(drag layer — Escape-to-cancel handled directly, not via `useOverlayBehavior`; see Kanban.tsx's header)* | ✅ | ✅ *(board state)* | 🛠️ Built *(cards are data-driven via `renderCard`, not nested `<KanbanCard>` children; columns stay ordinary JSX children since they never cross a parent boundary, and are drag/keyboard-reorderable via the same value/onChange path — see the docs page)* |
+| 42 | Carousel | F | ✅ | ❌ | ❌ *(own baseline: arrow keys, pause-on-hover, not Rule 11)* | ✅ | ✅ *(active slide)* | 🛠️ Built |
+| 43 | Rating | B | ✅ | ❌ | ❌ | ➖ | ✅ *(selected value)* | 🛠️ Built *(added outside the original plan — a single-value control, same shape as Slider)* |
+| 44 | StatCard | A | ✅ | ❌ | ❌ | ➖ | ❌ | 🛠️ Built *(added outside the original plan — composes `Card` for chrome)* |
+| 45 | CodeBlock | A | ✅ *(forwards to the scrollable `<pre>`)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built *(added outside the original plan — tokenizer lives in the shared `core/code-highlight.ts` primitive, not owned solely by this component; `highlighter` prop is a pluggable escape hatch, see that file's header)* |
+| 46 | RichTextEditor | F | ✅ *(`RichTextContent` forwards to the contentEditable element)* | ➖ *(the link editor's popover panel portals via the real `Popover`, not directly)* | ➖ *(inherited transitively through `Popover`)* | ✅ *(link editor composes `Popover`, Rule 12)* | ✅ *(`value`/`onChange`, HTML string)* | 🛠️ Built *(added outside the original plan — by far the largest component; deliberately NOT a ProseMirror-style document model, see `core/rich-text.ts`'s header for the v1 scope boundary and the `engine` escape hatch for consumers who need one)* |
+| 47 | SearchBar | D | ✅ | ✅ | ✅ *(closeOnEscape: false — same reasoning as Combobox, see its own header)* | ✅ *(reuses `core/combobox.ts`'s ARIA/id helpers directly, Rule 12)* | ✅ *(`value`/`onChange`, plain text — no committed/query split)* | 🛠️ Built *(added outside the original plan — Combobox's shape, but free-text: nothing reverts on blur/Escape, Enter always fires `onSearch` unless a suggestion is highlighted, and `suggestions` is shown as-is rather than filtered internally — see `core/search-bar.ts`'s header for the full contrast with Combobox)* |
+| 48 | ScrollArea | A | ✅ *(forwards to the scrollable viewport, not the outer wrapper)* | ❌ | ❌ | ➖ | ❌ | 🛠️ Built *(added outside the original plan — wraps arbitrary `children` in a custom-scrollbar viewport; `orientation` (`vertical`/`horizontal`/`both`) and `scrollbarVisibility` (`always`/`hover`/`auto`/`never`) are independent props, see `core/scroll-area.ts`'s header)* |
+
+A few things worth noting from the table itself, not just the rows:
+
+- **Category C has 8 components and all 8 need `ThemedPortal` +
+  the Rule 11 baseline with no exceptions** — this is the exact
+  category that produced the 3-missing-out-of-15 bug last time.
+  If you ever mark a ❌ in either of those columns for a Category C
+  component, stop and double check it actually belongs in Category A
+  or E instead.
+- **Toast and Dropdown are the two 🟡 rows in Category C** — both
+  for real structural reasons (Toast is a queue; Dropdown reuses
+  `core/collection.ts`, Category D's list primitive), not because the
+  rule is optional for them. Don't let "it's a bit different" quietly
+  become "it's exempt."
+- **Table, Kanban's conditional portal/a11y columns are the most likely
+  place to repeat the old bug** — a drag layer or cell editor is an
+  overlay in every way that matters, even though the component's name
+  doesn't obviously say "overlay" the way Modal's does. Flag it
+  explicitly in that component's own file comments once you decide
+  whether it applies.
+
+
+Build roughly in this category order, not alphabetically and not by
+whichever component sounds fun that day:
+
+1. **Button is settled; Categories A, B, C, D, and E are all proven
+   out now.** Input, Textarea, Checkbox, Radio, Toggle, and Slider
+   (Category B) share `core/field.ts`'s disabled/required/invalid/
+   size shape. Badge, Avatar, Spinner, Divider, Card, Alert, and
+   Progress (Category A) consistently derive booleans like
+   "dismissible" or "clickable" from whether a handler was actually
+   passed (`onDismiss`, `onClick`) rather than adding a redundant flag
+   prop. Modal, Tooltip, Toast, Dropdown, Popover, and CommandPalette
+   (Category C) share `useOverlayBehavior`
+   (Escape/focus-trap/return-focus) and `core/floating.ts` (anchor
+   positioning). Select, Combobox, and DatePicker (Category D) all
+   compose across categories rather than picking one — Select and
+   Combobox both reuse Input's field shape AND Category C's overlay
+   stack; DatePicker goes one step further and composes Popover
+   itself (not just Popover's underlying hooks) plus a standalone
+   Calendar component. Tabs and Accordion (Category E) share
+   `useRovingFocus`. `core/collection.ts` (arrow-key nav + typeahead)
+   is the one primitive proven across three different categories at
+   once — Dropdown (C), Select and Combobox (D), and CommandPalette
+   (D) all call the exact same functions.
+2. **Category A is down to one: ChatBubble.** Timeline is done — same
+   proven conventions, no portal/overlay complexity. Skeleton is done;
+   it also settled a real-world edge case worth carrying forward: a
+   full-width block built from divs (not a native form element) needs
+   its own `inline-size: 100%` — nothing in the platform gives it one
+   for free the way `<input>` gets a UA-stylesheet default width. Any
+   future component in this shape should declare it explicitly rather
+   than rely on an ancestor happening to be definite-width.
+3. **Category B is fully built.** OTPInput and PhoneInput both landed
+   — the ref-forwarding and controlled-value conventions were already
+   established by Input/Checkbox/Slider/NumberInput/etc. FileUpload is
+   the reference for Rule 12 inside Category B specifically: its
+   "Browse" trigger composes the real `Button` rather than hand-styling
+   a second one, exactly what the `🟡 (internal trigger button)` note
+   in the table called for.
+4. **Category D is fully built.** ColorPicker landed following the
+   same "compose Input's field shape + Popover + a new pure-logic
+   grid/wheel module" shape DatePicker established — Select, Combobox,
+   and DatePicker had already proven Rule 12 held here.
+5. **The rest of Category C** (Tour) — Drawer and ContextMenu are
+   done and confirm the prediction: both really were mostly a new
+   visual shape on `useOverlayBehavior`/`core/floating.ts`'s existing,
+   tested infrastructure. Drawer is a close copy of Modal.tsx with one
+   axis added (which edge, and "size" meaning width vs. height
+   depending on it). ContextMenu is DropdownMenu's sibling — same
+   portal/keyboard-nav machinery, reusing DropdownMenu's own item
+   classes and pure logic (Rule 12) rather than duplicating them — with
+   the one real new piece being a "virtual anchor" (a zero-size element
+   moved to the click point) that lets `useFloatingPosition` position
+   relative to a cursor location it was never written to expect,
+   completely unmodified. Tour is the one left, and will need actual
+   new choreography (sequencing highlighted-element steps) that neither
+   Drawer nor ContextMenu needed.
+6. **The rest of Category E** — Breadcrumb and Pagination are done,
+   and turned out *not* to need `useRovingFocus`: that hook is for a
+   single widget where only one item belongs in the tab order at a
+   time (Tabs, Accordion). A breadcrumb trail and a pager are both
+   just several independently-useful links/buttons in normal tab
+   order, closer to a browser's own navigation than to a listbox —
+   worth checking which model actually fits before reaching for
+   `useRovingFocus` on a future Category E component.
+7. **Category F** — Table and Carousel are both done. Table is the
+   reference for "compose more than any other category": seven small
+   pieces on paper first (Table, TableHeader, TableBody, TableRow,
+   TableHead, TableCell, TableCaption) rather than one component
+   holding sorting, selection, and layout all at once. Sort state is
+   controlled by the consumer, the same shape as every value-holding
+   component in this library; row selection isn't modeled by Table at
+   all — a "select all"/row checkbox is just a real `Checkbox` (Rule
+   12) placed in a cell. Carousel followed the same decompose-first
+   approach (root, viewport, track, slide, prev/next, indicators) and
+   owns its own keyboard/pause-on-hover baseline rather than reusing
+   `useOverlayBehavior`, since it isn't an overlay. Treeview, Kanban,
+   and ChatBubble remain — each will need its own genuinely new
+   interaction model the way Table's sort/selection split did, rather
+   than being a rearrangement of an existing component's pieces.
+8. **Two components shipped outside this table's original plan:**
+   Rating (Category B — a single-value control, same conventions as
+   Slider) and StatCard (Category A — composes `Card` for its chrome).
+   Both follow every rule in `CONTRACT.md` the same as anything on
+   the original list; they're just proof this table is a starting
+   roadmap, not a hard ceiling on what Nuvox can become.
+
+If building a Category D or F component forces a change to the
+foundation (`ThemedPortal`, `useOverlayBehavior`, `core/types.ts`),
+that's a signal the foundation still has a gap — fix it there, not
+with a one-off workaround in the component. That's the whole point of
 having gone through this exercise once already.