@dashforge/tw 0.11.0-beta → 1.1.0

package/CHANGELOG.md

@@ -12,6 +12,238 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > duplicated intentionally — no shared "lowest common denominator" headless
 > layer.
 
+## [1.1.0] — 2026-06-18
+
+### Added
+
+- **`<Alert>` + `<AlertTitle>` components.** New inline persistent
+  status surface — companion to `<Snackbar>`'s transient toast. Full
+  MUI Alert API parity (`severity`, `variant`, `icon`, `onClose`,
+  `action`, `role`, `<AlertTitle>` sub-component). Single deliberate
+  divergence: `severity="danger"` instead of MUI's `severity="error"`
+  — aligned with the `danger.*` token palette (semantically identical,
+  documented in the migration guide). Adds the Dashforge-specific
+  `visibleWhen` (engine-reactive predicate) and `access` (RBAC) props,
+  same contract as `<TextField>` / `<Button>` / etc.
+- **Menu family — `<Menu>`, `<MenuTrigger>`, `<MenuContent>`,
+  `<MenuItem>`, `<MenuLabel>`, `<MenuSeparator>`, `<MenuSkeleton>`
+  (P8, Sprint 4.4).** Compound action-menu API built on
+  `@radix-ui/react-dropdown-menu` — the purpose-built primitive
+  ships full WAI-ARIA menu pattern (`role="menu"` / `role="menuitem"`
+  / `role="separator"`), keyboard navigation (↑↓ Home End Enter
+  Esc Tab), type-ahead, focus management, and lazy portal mount.
+  `<MenuItem>` is `React.memo`-wrapped (Atlaskit-style perf — each
+  item re-renders only on prop change, not when siblings mutate).
+  `<MenuSkeleton>` provides Atlaskit-inspired loading state:
+  N placeholder rows matching real-item geometry, useful during
+  fetch-while-open patterns where a generic spinner would be a
+  perceived-perf regression. `<MenuItem color="danger">` highlights
+  destructive actions with a red soft-bg hover state.
+  Bridge integration on `<MenuItem>`: `access` (hide/disable per
+  RBAC) + `visibleWhen` (engine-reactive predicate — falsy → item
+  renders `null`, doesn't occupy a row). `closeOnItemClick` on
+  `<Menu>` (default `true`) for the standard action-menu pattern;
+  flip to `false` for filter / multi-select menus. Skipped for v1:
+  sub-menus (Atlaskit default — composable via Radix primitives if
+  needed later as additive change) and controlled selection mode
+  (use `<CheckboxGroup>` / `<RadioGroup>` standalone instead). New
+  runtime dep: `@radix-ui/react-dropdown-menu` (added to
+  `@dashforge/tw` `dependencies`, transitive — no consumer install
+  step required).
+- **`<Badge>` component (P7, Sprint 4.4).** Anchored indicator
+  (count / dot / short text overlay) — wrapper mode. For inline
+  standalone pills (status labels, removable tags), use `<Chip>` —
+  Badge and Chip are complementary: Chip is interactive
+  (`onClick`, `onDelete`, `selected`), Badge is passive overlay.
+  API: `content` (number/string), `dot` mode, `max` (default 99,
+  overflow renders as `"N+"`), `showZero` (default false — typical
+  notification UX), `invisible` (DOM-stay hide for fade animations),
+  `placement` (4 corners), `overlap` (`'rectangular'` default for
+  IconButton / Card; `'circular'` for Avatar — adds 14% inset to
+  align with the round edge), `withRing` default true (auto-inverting
+  `ring-neutral-50` for visual separation from the anchor surface).
+  Default color `'danger'` matches the standard "needs attention"
+  notification UX (red dot/count). Bridge: `access` + `visibleWhen`
+  — gate the badge while the anchor always renders. Skipped: size
+  axis (badge sizes to content; demand emerges → add later);
+  standalone mode (use `<Chip>` instead — TypeScript enforces
+  `children` required); `<Badge.Ribbon>` corner pattern (AntD-only
+  edge case).
+- **`<Spinner>` component (P6, Sprint 4.4).** Rotating-arc loading
+  indicator. SVG path + Tailwind `animate-spin` (pure CSS,
+  GPU-accelerated, gated on `motion-reduce` per WCAG 2.3.3). Color
+  inherits via `currentColor` when `color` is omitted — works
+  seamlessly inside `<Button>`, `<Alert>`, `<Card>`, or any colored
+  container with zero configuration. Pass an explicit `color`
+  (7 intents) for standalone usage. Size axis (`'xs' | 'sm' | 'md' |
+  'lg' | 'xl'`) maps to spacing tokens; `thickness` (`'thin' | 'md' |
+  'thick'`) maps to SVG `stroke-width`. **`withTrack` opt-in** renders
+  a faint ghost ring (20% opacity of currentColor) behind the
+  spinning arc — the Stripe / Vercel / Linear "premium spinner" look,
+  useful on busy backgrounds and for slow operations. **`delay` prop
+  (Atlassian-style anti-flash)** mounts the spinner as `null` for the
+  first N ms — quick operations that finish before the delay
+  never render the spinner. Pairs naturally with `visibleWhen` for
+  the canonical pattern `<Spinner visibleWhen={() => isSubmitting}
+  delay={150} />`. A11y: `role="status"` + `aria-live="polite"` +
+  visually-hidden label (default `'Loading'`). Decorative mode
+  (`label=""`) suppresses role + label entirely — used internally by
+  Button / IconButton loading state to avoid duplicate
+  announcements (the parent button already carries `aria-busy`).
+  **Refactor**: `<Button>` and `<IconButton>` loading state now
+  delegates to `<Spinner>` internally — single source of truth, the
+  spinner look propagates everywhere automatically if it changes.
+  No `access` (loading state is not permission-driven; wrap in `Box`
+  if needed).
+- **`<Avatar>` + `<AvatarGroup>` components (P5, Sprint 4.4).**
+  Image / initials / icon visual identity primitive. `<Avatar>` falls
+  back through a 4-step chain: `src` loads OK → `<img>`; `src` fails
+  → initials from `name`; no `src` + `name` set → initials from
+  `name` (first letter of first 2 whitespace-separated words,
+  uppercased — Mantine-style auto-generation); everything absent →
+  generic user SVG icon. Visual axes: `shape: 'circle' | 'rounded' |
+  'square'` (semantic shortcut) + `radius` from the full Box token
+  scale (explicit token wins over shape); `size: 'xs' | 'sm' | 'md' |
+  'lg' | 'xl'` mapped to spacing tokens; `color` (7 intents) +
+  optional `tone` (50-900) for type-safe access to any palette shade.
+  Truly custom colours route through `sx`. `<AvatarGroup>` is a thin
+  horizontal wrapper with negative-margin overlap, `max` slice with
+  trailing "+N" overflow indicator, optional `ring-2 ring-white`
+  halo per child (default on), `size` propagation to children.
+  Skipped: built-in status/presence dots (compose with future
+  `<Badge>` via `<Badge dot><Avatar /></Badge>`), MUI-style nested
+  `<AvatarImage>` / `<AvatarFallback>` sub-components (single-element
+  API is more ergonomic). No `access` / `visibleWhen` — Avatar is
+  display-only; wrap in `<Box>` for visibility gating.
+- **`<Card>`, `<CardContent>`, `<CardActionArea>` components (P2,
+  Sprint 4.4).** Opinionated surface preset over `<Box>`. `<Card>` is
+  a thin alias with card-shaped defaults (`variant='outlined'`,
+  `rounded='lg'`, `elevation=1`, no padding) and a restricted variant
+  axis (`'outlined' | 'elevated' | 'plain'` — `'soft'` / `'solid'`
+  belong to Box callouts and banners, not cards). `<CardContent>` is
+  a padded inner section (`p=4` default). `<CardActionArea>` is the
+  real value-add: a clickable wrapper with focus ring + hover state
+  + Radix Slot polymorphism (router `<Link>` without `<a>`-in-
+  `<button>` a11y violation) + `selected` for option-card patterns
+  (`aria-pressed`).
+  Skipped MUI's `CardHeader`, `CardMedia`, `CardActions` —
+  composable via `Stack` + `Box` + `Typography`, no value-add to
+  ship as separate components. Atlassian DS validates the
+  minimalist take (they ship no Card primitive at all).
+- **`access` + `visibleWhen` retrofit to `<Box>` (Sprint 4.4 surface
+  alignment, additive).** The bridge integration is now available on
+  Dashforge's surface primitive too. Use case: dashboard with
+  role-based cards (`access` hides revenue card from non-billing
+  roles), state-driven sections (`visibleWhen` toggles a section
+  based on form / external state) without `{condition && <Box>...}`
+  JSX guards. Idempotent for existing consumers — both props default
+  to no-op. RBAC-disabled / readonly Box surfaces dim visually and
+  carry `aria-disabled` / `aria-readonly` so descendants and
+  assistive tech can react. By extension, `<Card>` (which extends
+  `BoxProps`) inherits both props automatically.
+- **`visibleWhen` prop extended to `<Button>` + `<IconButton>` (Sprint
+  4.4 alignment).** Previously available only on form fields and the
+  new `<Alert>` / `<Chip>`, the engine-reactive visibility predicate
+  now ships on the action-trigger components too. The pattern is now
+  uniform across every interactive Dashforge TW primitive (Button,
+  IconButton, Chip, plus all form fields + Alert): `visibleWhen?:
+  (engine: Engine) => boolean` returns `null` when false; reactive on
+  engine state changes inside `<DashForm>`, closure-based outside.
+  Idempotent for consumers who don't use it.
+- **`<Chip>` component.** Public status / filter / tag pill — promoted
+  from the internal `Table/cells/RenderChip`. The 3 × 7 (variant ×
+  color) matrix is preserved byte-identical and now lives in
+  `Chip/chip.variants.ts` as the single source of truth, consumed by
+  both the public `<Chip>` and (via thin wrapper) the legacy
+  `RenderChip` — zero breaking change for Table cell consumers.
+  Variant axis is `'soft' | 'solid' | 'outline'` (default `'soft'`,
+  Dashforge chip vocabulary — distinct from Button's
+  `'solid' | 'outline' | 'ghost' | 'link'` and Alert's
+  `'standard' | 'filled' | 'outlined'`, see the design note in
+  `MIGRATION.md`). Full MUI Chip API parity: `label`, `icon`, `avatar`
+  (avatar wins over icon when both set), `clickable`, `onClick`,
+  `onDelete`, `deleteIcon`, `deleteLabel`. Plus Dashforge extras:
+  `selected` (filter-pill pressed state with `aria-pressed`) and
+  `access` (RBAC integration, same contract as `<Button>` /
+  `<IconButton>`). Static chips render as `<span>`; clickable chips
+  render as `<button>` with focus ring + hover state. 7 colors, 2
+  sizes.
+- **`<IconButton>` component.** Square, icon-only action button —
+  reuses `buttonVariants` 1:1 (`variant: 'solid' | 'outline' | 'ghost'
+  | 'link'`, `color: 'primary' | 'secondary' | 'success' | 'warning' |
+  'danger'`, `size: 'sm' | 'md' | 'lg'`, `loading`). Adds square
+  geometry (token-driven `w-N + px-0 + aspect-square`), a
+  TS-enforced `aria-label` (icon-only buttons MUST have an accessible
+  name), `asChild` via Radix Slot, and the standard `access` RBAC
+  integration. No `visibleWhen` / `slotProps` by design — mirrors
+  `<Button>`. Bundles `<IconButton>` exports + `ICON_BUTTON_BASE` /
+  `ICON_BUTTON_SIZE_OVERRIDES` constants for advanced overrides.
+- **`_shared/severity/` foundation.** New shared module
+  (`_shared/severity/{severity.types, severityVariants, severityIcons,
+  index}`) consumed by `<Alert>` and the refactored `<Snackbar>` (and
+  future Banner). Centralises the 3×4 (variant × severity) color
+  matrix and the per-severity default icons. Every cell is
+  token-driven via `dashforgePreset()` — no hardcoded hex, no `dark:`
+  variants on neutral.
+
+### Changed (BREAKING — visual only)
+
+- **`<Snackbar>` default appearance updated.** Snackbar now consumes
+  the same 3-variant severity surface as `<Alert>` (`standard` /
+  `filled` / `outlined`), with `standard` (soft tinted) as the new
+  default. Previously, severity discriminated only border + icon
+  colour; the surface bg + text stayed neutral. The new default
+  visually communicates severity at first glance (the previous
+  pattern read as "neutral message with coloured trim"). Consumers
+  who want the closest visual match to 1.0.x can pass
+  `variant="outlined"` on each enqueue or set
+  `<SnackbarProvider defaults={{ variant: 'outlined' }}>`.
+- **`<Snackbar>` Unicode-glyph icons replaced with inline SVG.** The
+  per-severity defaults are no longer `ⓘ ✓ ⚠ ✕` Unicode glyphs but
+  inline stroke SVG icons shared with `<Alert>` via
+  `_shared/severity/severityIcons`. Consumers who want the legacy
+  glyphs can pass `icon={<span>{glyph}</span>}` on each enqueue.
+- **`<Snackbar>` `severity="info"` now uses the dedicated `info-*`
+  token scale.** Previously aliased to `primary-*` (inadvertent
+  inconsistency with the rest of the catalog). `patchTheme({ info:
+  ... })` now correctly targets the info snackbar surface without
+  spilling into primary consumers.
+
+### Added — `<Snackbar>` API extensions
+
+- **`variant` option on `enqueue()` and `defaults`** —
+  `'standard' | 'filled' | 'outlined'`. Same axis as `<Alert>`.
+- **`icon` option on `enqueue()`** — same tristate semantics as Alert
+  (`undefined` → default per severity, `ReactNode` → custom, `false`
+  → no icon).
+- New exported type `SnackbarVariant`.
+
+### Fixed
+
+- **Defensive list-style reset across interactive `<ul>` lists.**
+  `Autocomplete` (listbox), `Pagination`, `LeftNav` (outer list + group
+  children), `DataGrid` column-visibility menu, and `Table` row-actions
+  menu now ship `list-none pl-0 m-0` directly on their `<ul>` variants
+  / inline classes instead of relying on the consumer environment
+  having Tailwind preflight active. Previously, environments without
+  preflight — or with a **scoped** preflight that intentionally omits
+  the `ol, ul { list-style: none }` reset (multi-ecosystem docs sites,
+  apps that opt out of preflight) — would render browser-default disc
+  bullets next to each option / row. The change is idempotent: in
+  consumers that have preflight, the new classes are no-ops; in
+  consumers without, the components render correctly out of the box.
+
+## [1.0.0] — 2026-05-23
+
+**Stable release.** First semver-stable version. The public API is now
+governed by strict semver — any future breaking change requires a major
+bump. Functionally identical to the previous beta tarball.
+
+- Version: `1.0.0`
+- Cross-package `@dashforge/*` peer-dependency ranges updated to `^1.0.0`.
+- See the [top-level CHANGELOG](https://github.com/kensaadi/dashforge/blob/main/CHANGELOG.md#100---2026-05-23) for the coordinated release context.
+- See [`MIGRATION.md`](https://github.com/kensaadi/dashforge/blob/main/MIGRATION.md) for the upgrade guide from any `0.x-beta` to `1.0.0` (no code changes required).
+
 ## [0.11.0-beta] — 2026-05-22
 
 **Sprint 7 — Tabs.** `<Tabs>` rebuilt as a custom, clean-room component.
@@ -137,8 +369,8 @@ Strictly additive — no breaking changes on existing component APIs.
   starts a column-reorder drag. On coarse-pointer (touch) devices the
   reorder `draggable` affordance is disabled — native HTML5
   drag-and-drop does not fire touch events, so it was a dead
-  interaction. (A pointer-event reorder covering touch is tracked in
-  `REFINEMENT-NOTES.md`.)
+  interaction. A pointer-event reorder covering touch is tracked
+  internally.
 - **`Table`** now emits a dev-only `console.warn` when `getRowId` is
   omitted while sort / search / selection / expandable rows are
   active — the positional-index fallback breaks row identity on
@@ -1349,16 +1581,6 @@ have shipped as `0.2.2-beta` in isolation.
   Breadcrumbs in its center slot, so fixing the Breadcrumbs link
   fixes TopBar transitively.
 
-### Internal
-
-- **`libs/dashforge/tw/CONSUMER-VALIDATION.md`** — Sprint 2 P1
-  deliverable. Per-component status table for the dash-consumer
-  end-to-end validation pass (24 components, 7-point check each).
-  Records the pattern lesson that motivated the Autocomplete
-  async fix: the bug was invisible to both unit tests (using
-  static `options`) and the docs lab (static demo) — only a real
-  consumer with `loadOptions` configured exposed it.
-
 ### Compatibility
 
 | Compatibility axis | Pre-`0.3.0` | Post-`0.3.0` |

package/COVERAGE.md

@@ -1,7 +1,7 @@
 # COVERAGE — `@dashforge/tw`
 
-> Sprint 6 P4 deliverable (2026-05-20). Test-coverage audit + the
-> gap-fill done this sprint, plus the tracked debt.
+> Test-coverage audit for `@dashforge/tw`. Current numbers, the gap-fill
+> performed, and the tracked debt.
 
 ## Current coverage (`vitest --coverage`, v8 provider)
 

package/PARITY.md

@@ -1,19 +1,17 @@
 # `@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**.
+> 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:
+> **Motivation.** This audit ensures:
 >
 > 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
+> 2. **Bridge contract validation** — the same `@dashforge/forms`
+>    schema works identically on both lines.
+> 3. **Parallel starter-kit maintainability** — two parallel kits
 >    (one MUI, one TW) require call-site-level parity to stay
->    parallel-maintainable.
+>    in sync.
 
 ## Versions audited
 

package/PERFORMANCE.md

@@ -1,9 +1,8 @@
 # `@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`.
+> Establishes the performance commitment for `@dashforge/tw`. Every
+> subsequent release should hold these numbers or justify any
+> regression in `CHANGELOG.md`.
 
 ## Bundle size
 

package/README.md

@@ -1,38 +1,97 @@
 # @dashforge/tw
 
-> **Status**: `0.1.0-beta` — first public beta. Sixteen components
-> shipped across forms, layout, and providers. The MUI side of
-> Dashforge (`@dashforge/ui`, `@dashforge/theme-mui`,
-> `@dashforge/theme-core`) is **fully isolated** from this package —
-> the two ecosystems share only the bridge layer (`@dashforge/forms` +
+**A props-driven React UI library on top of Tailwind CSS.** Every utility
+that matters for the public API becomes a typed prop — `size`, `color`,
+`variant`, `layout`, … — so you write components that read like a design
+system and render output that's pure Tailwind. Raw `className` / `sx` /
+`slotProps` stay available as escape hatches for the cases the prop
+surface doesn't cover.
+
+> **Status**: `1.0.0` — **stable release**. Public API frozen, semver
+> guaranteed. 37 components shipped across forms, data display,
+> navigation, feedback, layout primitives, and providers. The MUI side
+> of Dashforge (`@dashforge/ui`, `@dashforge/theme-mui`,
+> `@dashforge/theme-core`) is **fully isolated** from this package — the
+> two ecosystems share only the bridge layer (`@dashforge/forms` +
 > `@dashforge/ui-core` + `@dashforge/rbac`).
 
-Tailwind-rendered UI components for the Dashforge ecosystem.
-
-Components are **props-driven** (every Tailwind utility that matters
-for the public API becomes a typed prop — `size`, `color`, `variant`,
-`layout`, …). Raw `className` / `sx` / `slotProps` exist as escape
-hatches for the cases the prop surface doesn't cover.
+## Why Dashforge TW
+
+- **Props, not utility soup** — component APIs that read like MUI,
+  render output that's pure Tailwind. No more 40-class `<button>` tags
+  copied across the codebase.
+- **Dark mode built in** — CSS-variable inversion via the
+  `dashforgePreset` Tailwind preset. Same JSX renders in light and dark
+  without a single `dark:` variant.
+- **RBAC-aware out of the box** — every interactive component takes an
+  `access` prop, hidden / disabled / read-only centrally via
+  `@dashforge/rbac`.
+- **Bridge-integrated forms** — Form Closure v1, controlled error
+  gating, StrictMode-safe registration, per-field re-render isolation
+  via the shared `@dashforge/forms` engine.
+- **Router-agnostic** — pass `linkComponent` to use React Router, Next,
+  TanStack Router, or any other navigation primitive.
+- **TypeScript-first** — typed tokens, typed variants, typed slot
+  overrides, augmentable per-package.
 
 ## Component catalog
 
-### Form components (10)
+### Form components (13)
 
 `Button` · `TextField` · `Checkbox` · `Switch` · `RadioGroup` ·
 `Textarea` · `NumberField` · `OTPField` · `Autocomplete` ·
-`DateTimePicker`
+`DatePicker` · `DateRangePicker` · `TimePicker` · `DateTimePicker`
 
 All bridge-integrated, RBAC-aware (`access` prop), Form Closure v1
 error gating, StrictMode-safe.
 
-### Layout components (4)
+### Navigation & shell (4)
 
-`Breadcrumbs` · `LeftNav` · `TopBar` · `AppShell`
+`AppShell` · `LeftNav` · `TopBar` · `Breadcrumbs`
 
 Router-agnostic — pass a `linkComponent` prop for SPA navigation
 (React Router, Next, TanStack Router, …). Mobile-responsive shell
 with drawer + body scroll lock.
 
+### Layout primitives (8)
+
+`Box` · `Container` · `Stack` · `Grid` · `Divider` · `AspectRatio` ·
+`Typography` · `VisuallyHidden`
+
+Polymorphic via `as` prop, dark-mode-aware, prop-driven spacing /
+sizing / alignment.
+
+### Data display (3)
+
+`Table` · `DataGrid` · `Pagination`
+
+Virtualized rows, sticky columns (left + right), server-side mode,
+per-column filter chips, column resize / reorder / visibility,
+controlled or uncontrolled state.
+
+### Disclosure (2)
+
+`Accordion` · `Tabs`
+
+Radix-based, keyboard-accessible, fully styled through props.
+
+### Overlay (3)
+
+`Dialog` · `Popover` · `Tooltip`
+
+Portal-rendered, focus-trapped, dismiss-on-esc + click-outside
+out of the box.
+
+### Feedback (1)
+
+`Skeleton`
+
+### Date (1)
+
+`Calendar` — standalone month grid. Also powers `DatePicker` /
+`DateRangePicker` / `DateTimePicker` under the hood, but exported on
+its own for custom layouts.
+
 ### Providers (2)
 
 `ConfirmDialogProvider` + `useConfirm()` · `SnackbarProvider` +

package/THEME-AUDIT.md

@@ -1,15 +1,14 @@
 # THEME-AUDIT — @dashforge/tw catalog identity sweep
 
-> Sprint 4.3 deliverable (2026-05-19). Audit of every `@dashforge/tw`
-> component against the **default `dashforgePreset()` identity rule**
-> (memory: `feedback_dashforge_preset_is_identity`).
+> Audit of every `@dashforge/tw` component against the **default
+> `dashforgePreset()` identity rule**.
 >
 > **Rule recap.** The `dashforgePreset()` CSS-variable swap
 > auto-inverts the neutral palette:
 > `bg-neutral-50` / `text-neutral-900` etc. resolve to the
 > appropriate physical color via `--df-tw-color-neutral-N`. Adding a
 > `dark:` variant on a neutral class **double-inverts** the value
-> and breaks dark mode. The Sprint 4.1 Table fix established the
+> and breaks dark mode. The Table fix established the
 > canonical patterns; Sprint 4.3 applies them to the whole catalog.
 
 ## Scoring legend