@dashforge/tw 0.2.1-beta → 0.4.0-beta

package/PARITY.md

@@ -0,0 +1,483 @@
+# `@dashforge/tw` ↔ `@dashforge/ui` parity audit
+
+> Sprint 3 P1 deliverable (2026-05-19). Per-component diff between the
+> two Dashforge UI lines for the **10 bridge-integrated components**.
+>
+> **Motivation (revised post-Sprint 2).** This audit does NOT exist to
+> support customer migration MUI→TW (no consumer switches across UI
+> ecosystems in real life). It exists because:
+>
+> 1. **Internal consistency** — a refactor on `@dashforge/ui` that
+>    doesn't land on `@dashforge/tw` would otherwise be invisible.
+> 2. **Bridge contract validation** — proves that the same
+>    `@dashforge/forms` schema works identically on both lines.
+> 3. **Foundation for Sprint 5 starter kits** — two parallel kits
+>    (one MUI, one TW) require call-site-level parity to stay
+>    parallel-maintainable.
+
+## Versions audited
+
+| Lib | Version | Date |
+|---|---|---|
+| `@dashforge/tw` | `0.3.0-beta` | 2026-05-18 |
+| `@dashforge/ui` | `0.2.3-beta` | 2026-05-15 |
+
+## Scoring legend
+
+| Symbol | Meaning |
+|---|---|
+| ✓ | Parity verified — the two lines accept the same prop / behave the same way at the call-site level. |
+| ⚠ | Intentional delta — different prop or slightly different behavior, motivated and documented in the per-component section below. |
+| ✗ | Unintended drift — bug or oversight, files a follow-up issue. |
+
+## Bridge contract — universal across all 10 components
+
+Both libs share an identical bridge contract. The following props
+behave **byte-identical** in both lines (verified by reading the
+types files of all 10 components):
+
+| Prop | Type | Semantics |
+|---|---|---|
+| `name` | `string` (required) | Field name registered with the `DashFormProvider` bridge. |
+| `rules` | `unknown` | Validation rules forwarded to the bridge engine — opaque to the component. |
+| `visibleWhen` | `(engine: Engine) => boolean` | Engine predicate. Component returns `null` when false. |
+| `access` | `AccessRequirement` | RBAC requirement. Behaviors (`hide` / `disable` / `readonly`) identical in both libs. |
+| `helperText` | `ReactNode` | Helper text slot below the control. Auto-replaced with bridge error message when (a) error is true and (b) the Form Closure v1 gate passes (`touched \|\| submitCount > 0`). |
+| `error` | `boolean` | Explicit error semaphore override. Cuts ahead of the bridge's auto-error. |
+| `label` | `ReactNode` | Visible label. |
+
+The bridge integration semantics (Form Closure v1 error gating, prop
+precedence, granular per-field subscriptions, StrictMode-safe
+unregister on unmount) are implemented identically across both lines
+via the shared `@dashforge/ui-core` + `@dashforge/forms` packages.
+
+This is the **portability layer**: any consumer who swaps
+`@dashforge/ui` for `@dashforge/tw` (or vice versa) keeps their
+form schemas, validation rules, and RBAC declarations unchanged.
+
+## Per-component parity table
+
+| # | Component | Signature | Behavior | Variant axis | Bridge | Overall |
+|---|---|---|---|---|---|---|
+| 1 | Button | ✓ | ✓ | ⚠ | ✓ | ⚠ |
+| 2 | TextField | ✓ | ✓ | ⚠ | ✓ | ⚠ |
+| 3 | Checkbox | ⚠ | ✓ | ✓ | ✓ | ⚠ |
+| 4 | Switch | ⚠ | ✓ | ✓ | ✓ | ⚠ |
+| 5 | RadioGroup | ⚠ | ✓ | ⚠ | ✓ | ⚠ |
+| 6 | Textarea | ⚠ | ✓ | ⚠ | ✓ | ⚠ |
+| 7 | NumberField | ✓ | ✓ | ⚠ | ✓ | ⚠ |
+| 8 | OTPField | ✓ | ✓ | ⚠ | ✓ | ⚠ |
+| 9 | Autocomplete | ⚠ | ⚠ | ⚠ | ✓ | ⚠ |
+| 10 | DateTimePicker | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**No `✗` rows** — no unintended drift was discovered. All deltas
+are intentional and motivated below. The single `✓` overall
+(DateTimePicker) is the only component where the two lines are
+truly byte-identical at the prop level.
+
+---
+
+## 1. Button
+
+### Signature
+
+| Prop | `@dashforge/ui` (MUI) | `@dashforge/tw` |
+|---|---|---|
+| Inherits | `Omit<MuiButtonProps, 'disabled'>` | `Omit<ButtonHTMLAttributes, 'className' \| 'color'>` + `Pick<TVariants, 'variant' \| 'color' \| 'size' \| 'fullWidth' \| 'loading'>` |
+| `access` | ✓ | ✓ |
+| `disabled` | ✓ | ✓ |
+| `asChild` | ✗ | ✓ (Radix Slot polymorphism) |
+| `sx` | ✗ (MUI sx-object inherited via MuiButtonProps) | ✓ (utility-string) |
+| `loading` | ✗ (consumer adds it manually) | ✓ (built-in variant axis) |
+
+### Variant axis ⚠
+
+| Axis | MUI | TW |
+|---|---|---|
+| `variant` | `contained` \| `outlined` \| `text` | `solid` \| `outline` \| `soft` \| `ghost` |
+| `size` | `small` \| `medium` \| `large` | `sm` \| `md` \| `lg` |
+| `color` | `primary` \| `secondary` \| `error` \| `info` \| `success` \| `warning` | same 6 intents |
+| `fullWidth` | ✓ | ✓ |
+
+**Intentional delta.** TW renames `contained → solid`, adds `soft`
++ `ghost` variants, renames sizes to short forms. The MUI naming is
+a vestige of Material Design vocabulary; TW adopts the
+shadcn/Radix/Mantine common-denominator naming because that's what
+TW-native developers expect.
+
+### Notes
+
+- `loading` is a built-in TW variant (renders spinner + sets
+  `aria-busy`). On MUI side it's a consumer-level pattern.
+- TW's `asChild` (Radix Slot) is more powerful than MUI's
+  `component`/`href` polymorphism — single API, no DOM doubling.
+
+---
+
+## 2. TextField
+
+### Signature
+
+| Prop | MUI | TW |
+|---|---|---|
+| Inherits | `Omit<MuiTextFieldProps, 'name' \| 'SelectProps' \| 'InputProps' \| 'InputLabelProps' \| 'FormHelperTextProps' \| 'inputProps'>` | `Omit<InputHTMLAttributes, 'size' \| 'className'>` + `Pick<TVariants, 'size' \| 'layout' \| 'fullWidth'>` |
+| `layout` | ✓ (`floating` \| `stacked` \| `inline`) | ✓ (same enum) |
+| `required` | ✓ (renders asterisk) | ✓ (same) |
+| `slotProps.prefix/suffix` | ✗ (use `slotProps.input.startAdornment` / `endAdornment` — MUI v9 API) | ✓ (new in `0.3.0-beta` — inline adornments) |
+| `sx` | MUI sx-object | TW utility-string |
+
+### Variant axis ⚠
+
+| Axis | MUI | TW |
+|---|---|---|
+| `variant` | `outlined` \| `filled` \| `standard` | not exposed (defaults to `outlined`-equivalent) |
+| `size` | `small` \| `medium` | `sm` \| `md` \| `lg` |
+| `layout` | `floating` \| `stacked` \| `inline` | same |
+
+**Intentional delta.** TW intentionally drops MUI's
+`variant="standard"` (underline-only field) — it's a Material Design
+artifact that doesn't fit a typical Tailwind design system. TW also
+drops MUI's `variant="filled"` for now (no design system demand).
+
+### Notes
+
+- TW exposes `slotProps.prefix` / `slotProps.suffix` (added in
+  `0.3.0-beta`) for inline adornments. MUI achieves the same via
+  `slotProps.input.startAdornment` / `endAdornment` — different shape,
+  same outcome.
+- MUI's deprecated `inputProps` / `InputProps` / `InputLabelProps` /
+  `FormHelperTextProps` are explicitly Omit-ed from TW (cleanly,
+  since TW never inherited them in the first place).
+
+---
+
+## 3. Checkbox
+
+### Signature ⚠
+
+| Prop | MUI | TW |
+|---|---|---|
+| Inherits | `Omit<MuiCheckboxProps, 'name'>` (inherits MUI's `onChange: (event, checked) => void`) | `Pick<TVariants, 'size'>` (no HTML attrs inherited) |
+| `onChange` | ✓ MUI HTML signature: `(event, checked) => void` | ✗ (not exposed) |
+| `onCheckedChange` | ✗ | ✓ Radix signature: `(checked: boolean) => void` |
+| `checked` / `defaultChecked` | ✓ | ✓ |
+| `slotProps.indicator` | ✗ | ✓ |
+
+**Intentional delta.** Callback signature differs: MUI uses the HTML
+`onChange(event, checked)`, TW uses Radix's `onCheckedChange(checked)`.
+A consumer rewriting `<Checkbox onChange={…}>` → `<Checkbox onCheckedChange={…}>`
+is the only call-site change. Documented in `customization.mdx`
+(Sprint 3 P2).
+
+### Variant axis ✓
+
+Both libs expose `size` only (`small`/`medium`/`large` MUI ↔
+`sm`/`md`/`lg` TW — same naming convention as Button).
+
+### Notes
+
+- TW's Indicator renders BOTH `<CheckIcon />` and `<DashIcon />` and
+  toggles via Radix `data-state` (added in `0.3.0-beta`).
+  Indeterminate state is handled CSS-only.
+- Bridge contract identical: `useDashFieldMeta(name)` granular
+  subscription, Form Closure v1 gating.
+
+---
+
+## 4. Switch
+
+### Signature ⚠
+
+Same delta as Checkbox: TW exposes `onCheckedChange(checked)` (Radix),
+MUI exposes `onChange(event, checked)` (HTML). All other props
+identical (name, label, rules, visibleWhen, helperText, error, access,
+checked, defaultChecked, disabled).
+
+### Variant axis ✓
+
+Both libs: `size` only.
+
+### Notes
+
+- TW gates the thumb-slide animation on `prefers-reduced-motion`
+  (added Sprint 2 0.3.0-beta).
+
+---
+
+## 5. RadioGroup
+
+### Signature ⚠
+
+| Prop | MUI | TW |
+|---|---|---|
+| Inherits | `Omit<MuiRadioGroupProps, 'name'>` | `RadioGroupVariants` (Pick-style) |
+| `onChange` | ✓ MUI signature | ✗ |
+| `onValueChange` | ✗ | ✓ Radix signature: `(value: string) => void` |
+| `options` | ✓ (`RadioGroupOption[]` — identical shape) | ✓ |
+| `RadioGroupOption.access` | ✓ option-level RBAC | ✓ option-level RBAC |
+
+### Variant axis ⚠
+
+| Axis | MUI | TW |
+|---|---|---|
+| `orientation` | inherited from MUI's `row` boolean | dedicated `orientation: 'horizontal' \| 'vertical'` |
+| `size` | inherited (`small`/`medium`) | `sm` \| `md` \| `lg` |
+
+**Intentional delta.** TW exposes `orientation` as a typed variant
+axis (vs MUI's legacy `row={true}` boolean). MUI's `row` prop is a
+Material legacy; TW's `orientation` is the Radix/Aria standard.
+
+### Notes
+
+- Option-level RBAC is implemented identically in both libs
+  (`hide` keeps selected option visible-but-disabled to expose the
+  user's previous choice).
+- Group-level access has precedence over option-level access in
+  both libs.
+
+---
+
+## 6. Textarea
+
+### Signature ⚠
+
+| Prop | MUI | TW |
+|---|---|---|
+| Inherits | `Omit<MuiTextFieldProps, 'name'>` (with internal `multiline={true}` hard-coded) | `Omit<TextareaHTMLAttributes, 'name' \| 'size' \| 'onChange' \| 'onBlur' \| 'value' \| 'defaultValue'>` + `TextareaVariants` |
+| `rows` / `minRows` | ✓ (defaults `minRows={3}`) | ✓ (`rows` defaults to 3) |
+| `resize` | ✗ (CSS native, no prop) | ✓ variant axis (`none` \| `vertical` \| `horizontal` \| `both`) |
+
+### Variant axis ⚠
+
+TW adds the `resize` variant axis as a typed prop. MUI relies on the
+consumer adding inline `style={{ resize: 'vertical' }}` or CSS.
+
+### Notes
+
+- Form bridge contract identical.
+- TW exposes own `onChange` / `onBlur` typed for `HTMLTextAreaElement`;
+  MUI inherits from MUI's `TextFieldProps` typing for the
+  multiline-disguised-as-input case.
+
+---
+
+## 7. NumberField
+
+### Signature
+
+| Prop | MUI | TW |
+|---|---|---|
+| Inherits | `Omit<MuiTextFieldProps, 'name' \| 'type' \| 'value' \| 'onChange'>` | `Omit<InputHTMLAttributes, 'name' \| 'type' \| 'size' \| ...>` + `NumberFieldVariants` |
+| `value` | `number \| string \| null` | `number \| string \| null` (identical) |
+| `min` / `max` / `step` | inherited HTML attrs | typed at top level |
+| `showStepper` | ✗ | ✓ (TW-only: inline +/− buttons) |
+| `slotProps.stepper` / `slotProps.stepperButton` | ✗ | ✓ |
+
+### Variant axis ⚠
+
+TW exposes the stepper as a typed feature (`showStepper={true}`).
+MUI's NumberField is a plain `type="number"` input with no stepper UI.
+
+### Behavior ✓
+
+**Value contract is byte-identical** between the two lines:
+
+- Bridge storage type: `number \| null` (NEVER `NaN`)
+- UI display: `number → String(number)`, `null/undefined → ""`
+- Empty string → `setValue(name, null)`
+- Parseable number → `setValue(name, parsed)`
+- Non-numeric input → no bridge write (UI keeps string for UX,
+  bridge stays at last valid value)
+- Parsing uses `Number(...)` + `Number.isFinite(...)`. No locale parsing.
+
+This contract is explicitly documented in both lines' types files —
+the audit confirms they match word-for-word.
+
+---
+
+## 8. OTPField
+
+### Signature
+
+| Prop | MUI | TW |
+|---|---|---|
+| `length` | ✓ (default 6) | ✓ (default 6) |
+| `mode` | `numeric` \| `alphanumeric` \| `alpha` | `numeric` \| `alphanumeric` |
+| `onComplete` | ✓ | ✓ |
+| `onChange` | `(value: string) => void` | `(value: string) => void` (identical) |
+| `autoFocus` | ✓ (default `true`) | not in types (defaults via native `<input autoFocus>`) |
+
+### Variant axis ⚠
+
+| Axis | MUI | TW |
+|---|---|---|
+| Slot rendering | custom React per-slot | custom React per-slot + Tailwind variant (`size`, `tone`) |
+
+**Intentional delta.** TW drops MUI's `alpha`-only mode (no design
+system demand; consumers needing pure-alpha can use `alphanumeric`
++ client-side filter). TW also exposes per-slot styling via typed
+`slotProps.slot` / `slotProps.slotChar`.
+
+### Behavior ✓
+
+Both libs:
+- Sanitize input per `mode` on every keystroke
+- Sanitize paste content and fill slots sequentially
+- Emit `onChange` with the joined sanitized value (≤ `length`)
+- Fire `onComplete` when all slots filled
+
+---
+
+## 9. Autocomplete
+
+### Signature ⚠
+
+| Prop | MUI | TW |
+|---|---|---|
+| `multiple` (multi-select) | ✗ (MUI v9 inherits but Dashforge wrapper doesn't expose) | ✓ |
+| `freeSolo` | ✗ (MUI inherits but wrapper hides it) | ✓ |
+| `loadOptions` (async loader) | ✗ | ✓ |
+| `loadDebounceMs` | ✗ | ✓ (default 250ms) |
+| `optionsFromFieldData` | ✓ (MUI-only feature for runtime options from form runtime) | ✗ (TW doesn't have a runtime-data integration yet — F6+ work) |
+| `getOptionValue` / `getOptionLabel` / `getOptionDisabled` | ✓ | ✓ |
+| `getOptionKey` | ✗ | ✓ |
+| `onChange` | `(value: TValue \| null) => void` | `onValueChange: (AutocompleteValue) => void` (AutocompleteValue = `string \| string[] \| null`) |
+
+### Variant axis ⚠
+
+| Axis | MUI | TW |
+|---|---|---|
+| Mode | single-select only | single + multi + free-solo |
+| Async | not in wrapper (use MUI's directly if needed) | first-class `loadOptions` prop |
+
+**Intentional delta — TW is feature-ahead.** TW's Autocomplete is
+the most-extended bridge component:
+
+- **Multi-select** (chips inside input, backspace to remove last)
+- **Free-solo** (Enter commits typed text as value)
+- **Async loadOptions** (debounced, replaces static `options` while
+  the user types)
+
+MUI's Dashforge wrapper trails behind because: (a) MUI's underlying
+Autocomplete already supports these via inherited props, so wrapping
+them feels redundant; (b) the MUI consumer can drop down to
+`MuiAutocomplete` directly when they need these features. TW had to
+implement them from scratch (built on React Aria's `useComboBox`),
+so it was natural to expose them as first-class props.
+
+**Reverse delta — MUI is ahead on**: `optionsFromFieldData` (runtime
+field data integration for dynamic option lists fed by the form
+engine). This is a F6+ feature on the TW roadmap.
+
+### Behavior ⚠
+
+The core bridge contract is parity:
+
+- Storage policy: option pick → mapped `option.value`; clear → `null`
+- Form Closure v1 error gating
+- StrictMode-safe unregister on unmount
+
+But the **storage type** differs:
+- MUI: `TValue \| null` where TValue is `string | number`
+- TW: `string \| string[] \| null` (`string[]` for multi-select)
+
+This is a real call-site delta. A consumer migrating MUI → TW with
+a NumberField-style numeric `TValue` would need to switch to string
+storage + cast on submission.
+
+---
+
+## 10. DateTimePicker
+
+### Signature ✓
+
+All props parity:
+
+- `mode: 'date' \| 'time' \| 'datetime'` — identical
+- `value: string \| null` — identical (ISO 8601-ish naive string)
+- `min` / `max` / `step` — identical
+- `name` / `rules` / `visibleWhen` / `access` — identical (bridge)
+- `label` / `helperText` / `error` / `required` / `disabled` — identical
+
+### Variant axis ✓
+
+Layout: both libs allow `stacked` / `inline` and downgrade `floating`
+to `stacked` with a dev warning (rationale: native input always
+shows a placeholder mask that overlaps the floating label).
+
+### Behavior ✓
+
+Both libs:
+- Use native `<input type="date|time|datetime-local">`
+- Bridge contract identical
+- ISO string contract identical (`datetime-local` is naive — no TZ;
+  if you need TZ-aware persistence, both libs say to convert
+  upstream)
+
+**This is the cleanest parity case in the audit** — the only ✓✓✓
+across all four columns. Likely because both lines deliberately
+chose native HTML5 inputs over a custom calendar widget, leaving
+very little surface to diverge on.
+
+### Notes
+
+- MUI exposes `@deprecated inputProps` / `InputLabelProps` shims for
+  MUI v7 backward compatibility. TW never had these (no MUI lineage).
+
+---
+
+## Summary of intentional deltas
+
+1. **Callback signatures**: TW prefers Radix-style `onCheckedChange` /
+   `onValueChange` (single-arg). MUI inherits HTML `onChange(event, value)`.
+   → **Documented in `customization.mdx` decision tree.**
+2. **Variant taxonomy**: TW uses shadcn/Radix common-denominator
+   vocabulary (`solid`/`outline`/`soft`/`ghost`, `sm`/`md`/`lg`).
+   MUI uses Material Design vocabulary (`contained`/`outlined`/`text`,
+   `small`/`medium`/`large`). 1:1 mappable.
+3. **`sx` shape**: TW = utility string, MUI = sx-object. Same name,
+   different semantics — by design (see `customization.mdx` §1).
+4. **TW-only props**: `slotProps`, `asChild` (Button), `loading`
+   (Button), `slotProps.prefix/suffix` (TextField), `showStepper`
+   (NumberField), `multiple` / `freeSolo` / `loadOptions`
+   (Autocomplete), `resize` variant (Textarea).
+5. **MUI-only props**: `optionsFromFieldData` (Autocomplete runtime
+   data integration).
+
+## Components NOT covered by this audit
+
+The MUI line has these additional components that have no TW
+counterpart yet (NOT in scope for this audit — they're not part of
+the bridge-integrated tier):
+
+- `Select` (MUI-only) — TW uses Autocomplete for select-like UX
+- `Animate` (MUI-only utility)
+
+The TW line has these additional components with no MUI counterpart
+(Sprint 1-2 Foundation work, not in scope here):
+
+- `Typography`, `Box`, `Stack`, `Grid`, `Container`, `Divider`,
+  `AspectRatio`, `VisuallyHidden` (8 Foundation primitives)
+
+Tier-4 components (Dialog, Tabs, Tooltip, Popover, Accordion) ship in
+Sprint 3 P3 — they will be MUI-side counterparts of MUI's own
+`Dialog`, `Tabs`, `Tooltip`, `Popover`, `Accordion`. Future PARITY.md
+revisions will include them.
+
+## Follow-up items
+
+No `✗` rows surfaced, so no critical follow-ups. The intentional
+deltas are documented above. The following nice-to-haves were
+identified but are explicitly deferred:
+
+| Item | Notes | Sprint |
+|---|---|---|
+| Optional `onChange` (HTML-style) on Checkbox / Switch / RadioGroup | For MUI-migrating consumers who want byte-identical call-sites. Could be added as an additional optional callback alongside `onCheckedChange`. | Not planned. Intentional choice; documented in customization.mdx instead. |
+| `optionsFromFieldData` on TW Autocomplete | Runtime field data integration. Requires F6 infrastructure (form runtime data hooks not yet ported to TW). | Sprint 6 (post-1.0 candidate). |
+| MUI-side `loadOptions` / `freeSolo` / `multiple` exposure | MUI consumer can use `MuiAutocomplete` directly for these. Not adding to the wrapper unless concrete demand. | Not planned. |
+| `variant="standard"` / `"filled"` on TW TextField | No design system demand. | Not planned. |
+
+Maintenance pact: every release that touches a bridge-integrated
+component on either line MUST re-run this audit. The cost is low
+(~30 min for a single-component diff) and the consistency value is
+high.

package/PERFORMANCE.md

@@ -0,0 +1,169 @@
+# `@dashforge/tw` performance baseline
+
+> Sprint 3 P4 deliverable (2026-05-19). Establishes the pre-`1.0.0`
+> performance commitment for `@dashforge/tw@0.4.0-beta` (29
+> components). Every subsequent release MUST hold this line or
+> justify the regression in `CHANGELOG.md`.
+
+## Bundle size
+
+### Full library (`dist/index.esm.js`)
+
+Measured immediately after `nx build @dashforge/tw` on the
+`0.4.0-beta` source tree.
+
+| Metric | Value |
+|---|---|
+| Raw size | **312 KB** (319,924 bytes) |
+| Gzipped | **68.85 KB** (70,499 bytes) |
+| Brotli (estimate) | ~58 KB |
+
+### Historical bundle trajectory
+
+| Version | Raw | Gzipped | Components | Delta vs prev |
+|---|---|---|---|---|
+| `0.1.0-beta` | 255 KB | ~57 KB | 16 (tier-1/2/3) | baseline |
+| `0.2.0-beta` | 272 KB | ~60 KB | 24 (+8 foundation) | +17 KB raw |
+| `0.3.0-beta` | 272 KB | ~60 KB | 24 | 0 (no new components) |
+| `0.4.0-beta` | **312 KB** | **68.85 KB** | 29 (+5 tier-4) | **+40 KB raw / +8.85 KB gz** |
+
+The `0.4.0-beta` delta is the cost of 5 new Tier-4 components +
+their 5 Radix UI primitive dependencies (`@radix-ui/react-dialog`,
+`-tabs`, `-tooltip`, `-popover`, `-accordion`). The Radix runtime
+sub-dependencies (`@radix-ui/react-portal`, `-presence`,
+`-dismissable-layer`, etc.) are shared across primitives so the
+marginal cost of each new primitive after the first is smaller.
+
+### Tree-shaken size — per-component source weight
+
+Tree-shaken bundle size depends on the consumer's bundler (Vite,
+webpack, esbuild, Rollup). The TS source size below is a **proxy**
+for the contribution each component makes — not the precise
+tree-shaken cost, which includes the Radix runtime and shared
+helpers (`cn()`, `tailwind-variants`).
+
+| Component | Source bytes | Tier |
+|---|---:|---|
+| Autocomplete | 49,020 | Tier-3 (heaviest — multi-select + free-solo + async) |
+| LeftNav | 18,002 | F6 (navigation) |
+| RadioGroup | 16,946 | Tier-2 |
+| NumberField | 16,289 | Tier-2 |
+| DateTimePicker | 16,075 | Tier-3 |
+| Checkbox | 15,732 | Tier-1 |
+| Grid | 15,086 | F10 (foundation) |
+| TextField | 14,772 | Tier-1 |
+| Snackbar | 14,770 | F7 |
+| Box | 14,039 | F9 (foundation) |
+| ConfirmDialog | 13,361 | F7 |
+| AppShell | 12,734 | F6 |
+| Button | 12,628 | Tier-1 |
+| OTPField | 12,497 | Tier-2 |
+| Breadcrumbs | 11,694 | F6 |
+| Typography | 11,619 | F9 |
+| Divider | 11,026 | F10 |
+| Textarea | 10,310 | Tier-2 |
+| Stack | 9,131 | F9 |
+| Switch | 8,711 | Tier-1 |
+| **Dialog** | **7,421** | **Tier-4 (new)** |
+| Container | 6,754 | F10 |
+| **Accordion** | **6,150** | **Tier-4 (new)** |
+| **Tabs** | **5,303** | **Tier-4 (new)** |
+| AspectRatio | 4,871 | F10 |
+| TopBar | 4,723 | F6 |
+| **Tooltip** | **4,389** | **Tier-4 (new)** |
+| **Popover** | **3,747** | **Tier-4 (new)** |
+| VisuallyHidden | 3,744 | F10 |
+
+The 5 new Tier-4 components contribute **~27 KB of source** combined
+— roughly aligned with the +40 KB raw bundle delta (the extra
+~13 KB is Radix runtime).
+
+### Representative bundle subsets
+
+If a consumer imports only a subset, expected gzipped cost
+(estimated, depends on bundler):
+
+| Subset | Components | Estimated gzipped |
+|---|---|---|
+| Atomic (Button only) | 1 | ~6 KB |
+| Form bundle | TextField + Checkbox + Switch + RadioGroup + NumberField + Textarea + OTPField | ~28 KB |
+| Layout bundle | Box + Stack + Grid + Container + AppShell + LeftNav + TopBar + Breadcrumbs | ~24 KB |
+| Foundation (F9 + F10) | Typography + Box + Stack + Grid + Container + Divider + AspectRatio + VisuallyHidden | ~18 KB |
+| Tier-4 overlay primitives | Dialog + Tabs + Tooltip + Popover + Accordion | ~12 KB |
+| Full library | 29 | **68.85 KB** |
+
+Estimates are upper bounds — actual tree-shaking can do better if
+the consumer doesn't trigger code paths (e.g. importing
+`<Autocomplete>` without using `loadOptions` won't strip the async
+loader code from the bundle, but other unused components are
+fully eliminable).
+
+## Render performance
+
+### Sprint 2 baseline (in `dash` consumer, React Profiler)
+
+Measured in
+`~/projects/web/learn/dash/src/pages/TestFoundation.tsx` — page
+mounts all 8 Foundation primitives × ~6 instances each (50+
+primitives total) inside `<DashforgeTailwindProvider>` wrapped in
+`<React.Profiler>`:
+
+| Operation | Time | Notes |
+|---|---|---|
+| First mount | **12.1 ms** | Cold cache, no styles compiled yet |
+| Re-render (no state change) | **7.0 ms** | After style cache warm |
+| Re-render (state change) | **8.6 ms** | One field updated, sibling fields untouched |
+
+Within the **60 fps budget** (16.67 ms per frame) for the full page
+mount + every subsequent interaction. The primitives are pure (no
+internal `useState`, no `useEffect`, only className resolution via
+`tv()` + `cn()`), so React's reconciler trivially handles re-renders
+without `React.memo`.
+
+### Tier-4 components — expected render cost
+
+Tier-4 components (Dialog, Tabs, Tooltip, Popover, Accordion) carry
+internal Radix state machines. Render cost is dominated by Radix's
+own reconciliation, which is well-optimized. Expected ranges:
+
+| Component | Expected mount | Notes |
+|---|---|---|
+| Tooltip | <1 ms | Renders nothing until hover; portal mount on open is ~2 ms |
+| Popover | <1 ms | Same as Tooltip |
+| Tabs | ~2 ms | Static — all triggers + active panel mount once |
+| Accordion | ~3 ms | Per-item triggers + lazy panel mount |
+| Dialog | ~3 ms | Portal + focus trap setup on open |
+
+These are estimates based on Radix's published benchmarks. Real
+consumer-app numbers will be captured in Sprint 3 follow-up
+end-to-end validation pass (`/test-tier-4` page in `dash`).
+
+## Regression budget policy
+
+**Every PR that touches a component or adds a new export MUST**:
+
+1. Re-run `nx build @dashforge/tw` and check the new
+   `dist/index.esm.js` size (raw + gzipped).
+2. If the gzipped delta is **> +5%** vs the previous release,
+   include in the PR description:
+   - The bytes added (raw + gzipped)
+   - The reason (new component / new feature / new dep / refactor)
+   - A justification for why the cost is worth it
+3. If the gzipped delta is **> +10%**, the PR also requires a
+   reviewer's sign-off on the bundle impact explicitly (not a
+   silent pass).
+
+The 5% threshold at the current 68.85 KB baseline = 3.4 KB. That's
+enough headroom for a typical component-level change (e.g. adding a
+single Radix primitive's worth of code) without the policy
+triggering, but small enough that a careless dep addition gets
+flagged.
+
+## Reference
+
+- **Build command**: `nx build @dashforge/tw`
+- **Measurement script**: `gzip -c dist/index.esm.js | wc -c`
+- **Render perf setup**: see Sprint 2 P1
+  (`/test-foundation` route in `dash` consumer)
+- **CHANGELOG entries**: every release records the bundle delta
+  in the `Compatibility` section