@dashforge/tw 0.3.0-beta → 0.5.0-beta

package/CHANGELOG.md

@@ -12,6 +12,252 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > duplicated intentionally — no shared "lowest common denominator" headless
 > layer.
 
+## [0.5.0-beta] — 2026-05-19
+
+**Sprint 4 release.** Two TW-only utility primitives — `<Skeleton>`
+and `<Pagination>` — that were missing from the catalog and are
+prerequisite visuals for the upcoming Sprint 4.1 (Table + DataGrid).
+Both are pure-UI, no bridge integration, no RBAC sensible — they
+exist to compose with the data layer arriving next sprint.
+
+**MUI side note.** Neither component ships in `@dashforge/ui`:
+`@mui/material/Skeleton` and `@mui/material/Pagination` already
+cover the bridge-free use case fully. Per the Dashforge design rule
+(`@dashforge/ui` wraps MUI only when adding bridge / RBAC /
+validation / custom-behavior value), MUI consumers reach for the
+upstream components directly.
+
+**Minor bump** for 2 new public exports. Strictly additive — zero
+breaking changes. Drop-in upgrade from `0.4.0-beta`.
+
+### Added
+
+- **`<Skeleton>`** — loading placeholder primitive.
+  Three shapes (`text` default · `rectangle` · `circle`), three
+  animations (`pulse` default · `wave` · `none`). Width / height as
+  inline CSS lengths; circle's height defaults to its width.
+  Rendered as `<span aria-hidden="true" role="presentation">` — screen
+  readers skip it; the surrounding container is responsible for
+  `aria-busy` / `aria-live` announcements. **WCAG 2.3.3**: both
+  animations gated on `prefers-reduced-motion: reduce`. Compose
+  multiple `<Skeleton>`s to mimic card / row shapes during fetch.
+  19 unit tests covering variants × animations × sizing × sx +
+  slotProps override + a11y attributes.
+- **`<Pagination>`** — controlled pagination primitive. Three
+  variants:
+    - `default` — summary + page numbers + first/prev/next/last +
+      page-size selector + direct jump input
+    - `compact` — page numbers + nav buttons only
+    - `minimal` — "Page X of Y" + prev/next (mobile-friendly)
+  Three sizes (`sm` / `md` / `lg`). Configurable
+  `siblingCount` / `boundaryCount` for the ellipsis range
+  algorithm — small totals (≤ `2·boundary + 2·sibling + 3` pages)
+  short-circuit to the full range, no ellipsis. Full i18n via
+  `labels` prop (English defaults). A11Y: `<nav aria-label="Pagination">`
+  landmark, `aria-current="page"` on the active button, native
+  `<select>` for page size, native `<input type="number">` for
+  the jump input (commit on Enter / blur, clamped to range).
+  Page-size selector hidden when `onPageSizeChange` is omitted.
+  Jump input toggle via `showJumpInput`. 28 unit tests covering
+  the range helper (7) + rendering / interactions / variants /
+  i18n / disabled / overrides / edge cases (21).
+
+### Internal
+
+- **47 new unit tests** for the 2 components — full TW suite at
+  **681/681 passing** (39 files).
+- **`TestUtilities.tsx`** added to the `dash` consumer
+  (`/test-utilities`) as the Sprint 4 smoke-test page: variant
+  matrix for both components + card-placeholder compose pattern +
+  Pagination i18n / size / variant / edge cases + a 50-instance
+  Skeleton stress test wrapped in `React.Profiler`. Validated
+  end-to-end before docs were written (per Dashforge workflow
+  policy: dash smoke test PRECEDES docs).
+- **Sidebar entries** for the new `Skeleton` + `Pagination` doc
+  pages added to `dashforge-docs-lab/src/tw-docs/sidebar.model.ts`.
+
+### Compatibility
+
+| Axis | Pre-`0.5.0` | Post-`0.5.0` |
+|---|---|---|
+| Public API surface | 29 components | **+ 2 (`Skeleton`, `Pagination`)** + their `*Props` / `*SlotProps` types + `*Variants` recipes + `PaginationLabels` i18n type |
+| Peer deps | `react ^18 \|\| ^19`, `tw-theme workspace`, `tw-tokens workspace` | unchanged |
+| Bridge deps | `forms` / `rbac` / `ui-core` `workspace:*` | unchanged |
+| New runtime deps | — | **none** (no new external libraries — constraint honored) |
+| Breaking changes | — | Zero |
+| Bundle size | 312 KB raw / 68.85 KB gzipped | **336 KB raw / 73.9 KB gzipped** (+24 KB raw / +5.05 KB gz / **+7.3% gz**) |
+| Migration | — | Drop-in. Zero code changes required on existing usages. |
+
+> **Bundle regression note**: the +7.3% gzipped delta is **above
+> the 5% threshold** documented in `PERFORMANCE.md`. Justification:
+> Pagination contributes ~4 KB gz (3 variants × 3 sizes × i18n
+> surface + range-computation helper + jump-input commit logic);
+> Skeleton contributes ~1 KB gz. The delta sits well under the
+> 10% reviewer-sign-off threshold and is the necessary cost of
+> adding two new public components. Filed as informational per
+> the regression policy.
+
+### Migration
+
+No code changes required:
+
+```bash
+pnpm up @dashforge/tw@^0.5.0-beta
+```
+
+To adopt the new components:
+
+```tsx
+import { Skeleton, Pagination } from '@dashforge/tw';
+
+// Loading placeholder while fetching
+{isLoading ? (
+  <Skeleton variant="text" width="200px" />
+) : (
+  <UserName>{user.name}</UserName>
+)}
+
+// Paginated list (controlled — wire to your data slice)
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(20);
+
+<Pagination
+  page={page}
+  pageSize={pageSize}
+  totalCount={users.length}
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+/>
+```
+
+MUI consumers: continue using `@mui/material/Skeleton` and
+`@mui/material/Pagination` directly. `@dashforge/ui` will NOT ship
+wrappers for these (per the design rule documented in
+`PARITY.md` — no value-add wrappers).
+
+## [0.4.0-beta] — 2026-05-19
+
+**Sprint 3 release.** Five new Tier-4 overlay & disclosure
+components (Dialog, Tabs, Tooltip, Popover, Accordion) + the
+internal **MUI ↔ TW parity audit** (`PARITY.md`) + the
+**customization escape hatch playbook** in the docs lab + the
+first **performance baseline** (`PERFORMANCE.md`). Strictly
+additive — zero breaking changes on the existing 24-component
+surface.
+
+**Minor bump** for the 5 new public exports + new types. All
+existing usages keep working byte-identical. Drop-in upgrade from
+`0.3.0-beta`.
+
+### Added
+
+- **`<Dialog>`** — declarative modal dialog (Radix `Dialog`-backed).
+  Three size variants (`sm` / `md` / `lg`), controlled `open` /
+  `onOpenChange`, optional title + description (wired to
+  `aria-labelledby` / `aria-describedby`), `showCloseButton` toggle,
+  `disableBackdropClose` / `disableEscapeClose` escapes. APG dialog
+  pattern out of the box: focus trap, restore focus on close, Esc
+  dismissal, scroll lock. Portal-rendered.
+- **`<Tabs>`** — declarative tab navigation (Radix `Tabs`-backed).
+  Two variants (`underline` default / `pill`), two orientations
+  (`horizontal` default / `vertical`), controlled / uncontrolled
+  modes. APG tabs pattern: arrow-key navigation,
+  `role="tablist"` / `role="tab"` / `role="tabpanel"` wiring,
+  `aria-orientation`.
+- **`<Tooltip>`** — hover/focus tooltip (Radix `Tooltip`-backed).
+  Per-component provider for delay configuration (default 200ms),
+  four placement sides, alignment options, optional arrow
+  indicator. APG tooltip pattern: `role="tooltip"`,
+  `aria-describedby` wired automatically.
+- **`<Popover>`** — clickable floating panel (Radix
+  `Popover`-backed). For richer floating UI than tooltip — action
+  menus, color pickers, settings panels. Focus trap inside,
+  outside-click + Escape dismiss, portal-rendered.
+- **`<Accordion>`** — collapsible section list (Radix
+  `Accordion`-backed). Two modes (`single` default with
+  `collapsible: true` / `multiple`), per-item disabled flag,
+  CSS-only chevron flip via `data-state=open` selector. APG
+  accordion pattern: arrow-key navigation between triggers,
+  `aria-expanded` on triggers, `role="region"` on panels.
+- **`PARITY.md`** — internal parity audit between `@dashforge/tw`
+  and `@dashforge/ui` (MUI line). Covers the 10 bridge-integrated
+  components. Documents intentional deltas (Radix callback
+  signatures `onCheckedChange` / `onValueChange` vs MUI
+  `onChange(event, value)`; variant taxonomy `solid` / `outline` /
+  `soft` / `ghost` vs MUI's `contained` / `outlined` / `text`;
+  TW-only features like `loadOptions` async loader on Autocomplete,
+  `slotProps.prefix` / `suffix` on TextField, `showStepper` on
+  NumberField). Motivation: internal consistency + foundation for
+  Sprint 5 starter kits. Not a customer migration document — the
+  switch story was scrapped as a non-existent use case.
+- **`/docs/guides/customization.mdx`** — customization escape
+  hatch playbook. Three sections: `sx` vs `slotProps` decision
+  tree with 4 canonical examples (outer wrapper styling, slot
+  styling, conflict resolution, combining both), preset extension
+  recipes (`extendPreset({ colors: { brand: { … } } })` + custom
+  intent augmentation + custom font stack), and a custom-component
+  tutorial (`PhoneInput` built on `useDashFieldMeta` +
+  `useAccessState`).
+- **`PERFORMANCE.md`** — first formal performance baseline. Bundle
+  raw + gzipped (312 KB / 68.85 KB for 29 components),
+  per-component source size proxy, representative bundle subsets
+  (form / layout / foundation / tier-4 / full), render perf table
+  (12.1 ms mount / 7-8.6 ms update from `dash` consumer). Sets
+  the regression budget policy: any PR with >+5% gzipped delta
+  requires a justification line in the CHANGELOG; >+10% requires
+  explicit reviewer sign-off.
+
+### Internal
+
+- **MUI ↔ TW parity audit pact.** Every release that touches a
+  bridge-integrated component on either line MUST re-run the
+  parity audit (low cost — ~30 min per component-level diff). The
+  pact is documented at the end of `PARITY.md`.
+- **Performance regression budget.** 5% / 10% gzipped thresholds
+  documented in `PERFORMANCE.md`. To be enforced via CI in Sprint
+  4+ (out of scope for Sprint 3 — the policy is the foundation).
+- **Sidebar entry** for the new `Customization` guide added to
+  `dashforge-docs-lab/src/tw-docs/sidebar.model.ts`.
+- **42 new unit tests** for the 5 Tier-4 components — full TW suite
+  now at 634/634 passing (37 files).
+
+### Compatibility
+
+| Axis | Pre-`0.4.0` | Post-`0.4.0` |
+|---|---|---|
+| Public API surface | 24 components + foundation + bridge hooks | **+5 components + their `*Props` / `*SlotProps` types + their `*Variants` recipes** |
+| Peer deps | `react ^18 \|\| ^19`, `tw-theme workspace`, `tw-tokens workspace` | unchanged |
+| Bridge deps | `forms` / `rbac` / `ui-core` `workspace:*` | unchanged |
+| New runtime deps | — | `@radix-ui/react-dialog ^1.1.0` · `@radix-ui/react-tabs ^1.1.0` · `@radix-ui/react-tooltip ^1.1.0` · `@radix-ui/react-popover ^1.1.0` · `@radix-ui/react-accordion ^1.2.0` |
+| Breaking changes | — | **Zero**. The `sx` + `slotProps` design discussion concluded with "keep both, document only" — no rename. |
+| Bundle size | 272 KB raw / ~60 KB gzipped | **312 KB raw / 68.85 KB gzipped** (+40 KB raw / +8.85 KB gz; within the projected 14% budget for 5 Radix-backed components) |
+| Migration | — | Drop-in. Zero code changes required on existing usages. |
+
+### Migration
+
+No code changes required:
+
+```bash
+pnpm up @dashforge/tw@^0.4.0-beta
+```
+
+To adopt the new Tier-4 components:
+
+```tsx
+import { Dialog, Tabs, Tooltip, Popover, Accordion } from '@dashforge/tw';
+
+<Tooltip content="Delete this item">
+  <Button variant="ghost"><TrashIcon /></Button>
+</Tooltip>
+
+<Tabs items={[
+  { value: 'overview', label: 'Overview', content: <OverviewPanel /> },
+  { value: 'details',  label: 'Details',  content: <DetailsPanel /> },
+]} />
+
+<Accordion items={faqItems} type="single" defaultValue="q-1" />
+```
+
 ## [0.3.0-beta] — 2026-05-18
 
 **Sprint 2 release.** Bundle of 9 fixes across 7 components + 1 new