@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/CHANGELOG.md

@@ -12,6 +12,114 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > duplicated intentionally — no shared "lowest common denominator" headless
 > layer.
 
+## [0.2.0-beta] — 2026-05-17
+
+**Foundation release.** Eight layout / structural primitives added on top of
+the F3–F7 component catalogue, plus extensive edge-case test hardening across
+the whole package.
+
+This is a strictly additive minor bump — no breaking changes to the existing
+16 components. Consumers upgrading from `0.1.0-beta` can adopt the new
+primitives incrementally; existing code keeps working unchanged.
+
+### Added — Foundation primitives (F9)
+
+The `Box ≠ flex`, `Stack = flex 1D`, `Grid = flex 2D` rule is the spine of
+this layer: each primitive has a single, non-overlapping responsibility so
+"which one do I use?" has one answer per scenario.
+
+- **`Typography`** — semantic typed text. Twelve variants (h1–h6,
+  subtitle1/2, body1/2, caption, overline) × nine intent colors × five
+  weight overrides + alignment + truncate / noWrap / gutterBottom. Default
+  HTML tag inferred from variant (h1→`<h1>`, body1→`<p>`, …), overridable
+  via `as` or `asChild` (Radix Slot). Reads color from a parent `<Box>` via
+  `color="inherit"`.
+- **`Box`** — surface primitive consolidating MUI's Box + Paper + Card +
+  Surface into one. Five variants (`plain` · `outlined` · `elevated` ·
+  `soft` · `solid`) × seven intent colors = 21 compound visuals + six
+  elevation levels (0–5) + token-scale spacing (`p`/`px`/`py`/`m`/`mx`/`my`)
+  + rounded scale + `fullWidth`/`fullHeight`. Strictly no flex / no grid by
+  design — wrap in Stack/Grid for layout.
+- **`Stack`** — the **only** flex container in `@dashforge/tw`. Direction +
+  align + justify + token-scale gap + wrap, plus a runtime `divider` prop
+  that inserts N-1 separators between children (Children.toArray semantics
+  documented; Fragments count as one child).
+- **`Grid`** — CSS Grid container + item, polymorphic in role. MUI v2 API
+  surface (`<Grid container>` + `<Grid xs={6}>`) backed by real CSS Grid
+  (`display: grid` + `col-span-*`), not flexbox. Discriminated-union
+  TypeScript — `<Grid container xs={6}>` is a compile error. 70-entry
+  responsive col-span mapping (xs/sm/md/lg/xl × 1..12/auto/full).
+
+### Added — Foundation completions (F10)
+
+Closes the foundation surface to match what Chakra/Mantine/Joy ship at the
+layout-primitive level.
+
+- **`Container`** — centered max-width page wrapper with the canonical
+  responsive padding ramp (`px-4 sm:px-6 lg:px-8`). Six sizes
+  (sm/md/lg/xl/2xl/fluid) mapped to Tailwind's screen breakpoints +
+  `centerContent` opt-in for marketing/sign-in layouts.
+- **`Divider`** — visual separator with two rendering modes. Line-only
+  renders `<hr>` with `role="separator"` + `aria-orientation`; labeled
+  mode (with children) renders the "OR" separator pattern as two flex
+  segments around the label. orientation / variant (solid/dashed/dotted)
+  / color (7 intents) / align (start/center/end) axes.
+- **`AspectRatio`** — content-shape primitive using the native CSS
+  `aspect-ratio` property (supported since 2021, ~98% browser coverage).
+  Number or CSS-string ratio. Pairs with `sx="rounded-xl overflow-hidden"`
+  for the canonical clipped media pattern (documented as the #1 gotcha).
+- **`VisuallyHidden`** — the a11y primitive. Uses Tailwind's `sr-only`
+  (WebAIM clip technique). Hides children from sighted users while keeping
+  them in the accessibility tree — icon button labels, status announcers,
+  skip links. Default tag is `<span>` for the 99% case (inline label).
+
+### Added — Test coverage hardening (F11-bis)
+
+- **+132 new edge case tests** across the eight Foundation primitives,
+  bringing total package coverage from **460 → 592 tests** (32 files).
+- **Box (+33)**: all 21 compound variants (outlined / soft / solid × 7
+  intents) asserted explicitly with light + dark pairs; plain / elevated
+  color-agnostic invariants; spacing axis coexistence; elevation × variant
+  interaction; rounded edge values.
+- **Grid (+38)**: every responsive breakpoint × representative span (5 ×
+  5 = 25), full cascade test (xs→xl), every `autoFlow` value, every `cols`
+  value, `spacingX`/`spacingY` independence, empty container + orphan item
+  handling, deep nesting.
+- **Stack (+29)**: array divider, conditional / null children, mixed
+  text + element children, nested Stack with divider key stability, every
+  gap step (11 token values), every align/justify value (11), empty Stack
+  with and without divider.
+- **Typography, Container, Divider, AspectRatio, VisuallyHidden (+32)**:
+  multi-axis combinations, full variant catalogues, extreme ratio values,
+  nested fluid/capped Container pattern, aria-live announcement pattern.
+
+### Validated
+
+End-to-end smoke test in the `dash` consumer app (linked via `file:`
+override): all eight primitives mount + render correctly in light and dark
+modes; React Profiler shows **mount 12.1 ms / re-render 7–8.6 ms** for a
+page with 50+ primitive instances — well within the 60 fps frame budget.
+No `React.memo` needed because the primitives are pure (no internal state,
+no `useEffect`, only className resolution).
+
+### Architecture note
+
+The `Box ≠ flex` / `Stack = flex` / `Grid = 2D` separation is intentional
+and enforced at the type level: passing flex/grid props to `Box` is a
+compile error. This rules out the "Box is universal, every `<div>` ends up
+as a `<Box display="flex">`" failure mode that drowns the surface-vs-layout
+distinction in MUI codebases.
+
+### Compatibility
+
+- **Peer deps unchanged**: `@dashforge/tw-theme@^0.1.0-beta` and
+  `@dashforge/tw-tokens@^0.1.0-beta` (neither was modified).
+- **Bridge layer unchanged**: still pinned to `@dashforge/forms` +
+  `@dashforge/ui-core` + `@dashforge/rbac` at the workspace version.
+- **No breaking changes**: existing 16 components' APIs are byte-identical.
+
+---
+
 ## [0.1.0-beta] — 2026-05-16
 
 First public beta. Sixteen components shipped across forms, layout, and

package/dist/index.d.ts

@@ -1,82 +1 @@
-/**
- * @dashforge/tw
- *
- * Tailwind-rendered UI components for the Dashforge ecosystem.
- *
- * Architectural contract (plan v2 — 2026-05-15):
- *  - **Props-driven**: each Tailwind utility that matters for the public
- *    API becomes a typed prop. `sx` + `slotProps` are escape hatches.
- *  - **Tokens as source of truth**: components reference colors /
- *    spacing / radius / fontSize through `@dashforge/tw-tokens` via the
- *    `dashforgePreset()` from `@dashforge/tw-theme`.
- *  - **Shared bridge with MUI side**: both ecosystems consume
- *    `@dashforge/forms` + `@dashforge/ui-core` + `@dashforge/rbac`.
- *    No styling code is shared.
- *  - **Variant API**: `tailwind-variants` (TV) with `slots` +
- *    `compoundVariants`.
- *
- * F3 surface (tier-1, this release):
- *  - `<Button>` (action, RBAC only, `asChild` polymorphism)
- *  - `<TextField>` (bridge-integrated, 7 slots)
- *  - `<Checkbox>` (bridge-integrated, Radix Checkbox primitive)
- *  - `<Switch>` (bridge-integrated, Radix Switch primitive)
- *
- * @module @dashforge/tw
- */
-export { Button } from './components/Button/Button.js';
-export type { ButtonProps } from './components/Button/button.types.js';
-export { buttonVariants } from './components/Button/button.variants.js';
-export { TextField } from './components/TextField/TextField.js';
-export type { TextFieldProps, TextFieldSlotProps, } from './components/TextField/textField.types.js';
-export { textFieldVariants } from './components/TextField/textField.variants.js';
-export { Checkbox } from './components/Checkbox/Checkbox.js';
-export type { CheckboxProps, CheckboxSlotProps, } from './components/Checkbox/checkbox.types.js';
-export { checkboxVariants } from './components/Checkbox/checkbox.variants.js';
-export { Switch } from './components/Switch/Switch.js';
-export type { SwitchProps, SwitchSlotProps, } from './components/Switch/switch.types.js';
-export { switchVariants } from './components/Switch/switch.variants.js';
-export { RadioGroup } from './components/RadioGroup/RadioGroup.js';
-export type { RadioGroupProps, RadioGroupOption, RadioGroupSlotProps, } from './components/RadioGroup/radioGroup.types.js';
-export { radioGroupVariants } from './components/RadioGroup/radioGroup.variants.js';
-export { Textarea } from './components/Textarea/Textarea.js';
-export type { TextareaProps, TextareaSlotProps, } from './components/Textarea/textarea.types.js';
-export { textareaVariants } from './components/Textarea/textarea.variants.js';
-export { NumberField } from './components/NumberField/NumberField.js';
-export type { NumberFieldProps, NumberFieldSlotProps, } from './components/NumberField/numberField.types.js';
-export { numberFieldVariants } from './components/NumberField/numberField.variants.js';
-export { OTPField } from './components/OTPField/OTPField.js';
-export type { OTPFieldProps, OTPFieldSlotProps, OTPFieldMode, } from './components/OTPField/otpField.types.js';
-export { otpFieldVariants } from './components/OTPField/otpField.variants.js';
-export { Autocomplete } from './components/Autocomplete/Autocomplete.js';
-export type { AutocompleteProps, AutocompleteOption, AutocompleteSlotProps, AutocompleteValue, } from './components/Autocomplete/autocomplete.types.js';
-export { autocompleteVariants } from './components/Autocomplete/autocomplete.variants.js';
-export { DateTimePicker, isoToInputValue, } from './components/DateTimePicker/DateTimePicker.js';
-export type { DateTimePickerProps, DateTimePickerMode, DateTimePickerSlotProps, } from './components/DateTimePicker/dateTimePicker.types.js';
-export { dateTimePickerVariants } from './components/DateTimePicker/dateTimePicker.variants.js';
-export { Breadcrumbs } from './components/Breadcrumbs/Breadcrumbs.js';
-export type { BreadcrumbsProps, BreadcrumbItem, BreadcrumbsSlotProps, BreadcrumbLinkComponent, } from './components/Breadcrumbs/breadcrumbs.types.js';
-export { breadcrumbsVariants } from './components/Breadcrumbs/breadcrumbs.variants.js';
-export { LeftNav } from './components/LeftNav/LeftNav.js';
-export type { LeftNavProps, LeftNavNode, LeftNavItem, LeftNavGroup, LeftNavSlotProps, LeftNavLinkComponent, } from './components/LeftNav/leftNav.types.js';
-export { leftNavVariants } from './components/LeftNav/leftNav.variants.js';
-export { TopBar } from './components/TopBar/TopBar.js';
-export type { TopBarProps, TopBarSlotProps, } from './components/TopBar/topBar.types.js';
-export { topBarVariants } from './components/TopBar/topBar.variants.js';
-export { AppShell } from './components/AppShell/AppShell.js';
-export type { AppShellProps, AppShellSlotProps, } from './components/AppShell/appShell.types.js';
-export { appShellVariants } from './components/AppShell/appShell.variants.js';
-export { ConfirmDialogProvider, useConfirm, } from './components/ConfirmDialog/ConfirmDialog.js';
-export type { ConfirmDialogProviderProps, ConfirmDialogSlotProps, ConfirmFn, ConfirmOptions, ConfirmSeverity, } from './components/ConfirmDialog/confirmDialog.types.js';
-export { confirmDialogVariants } from './components/ConfirmDialog/confirmDialog.variants.js';
-export { SnackbarProvider, useSnackbar, } from './components/Snackbar/Snackbar.js';
-export type { SnackbarProviderProps, SnackbarApi, SnackbarOptions, SnackbarRecord, SnackbarSeverity, SnackbarPosition, SnackbarSlotProps, } from './components/Snackbar/snackbar.types.js';
-export { snackbarVariants } from './components/Snackbar/snackbar.variants.js';
-export { useAccessState } from './hooks/useAccessState.js';
-export { cn } from './utils/cn.js';
-export { tv } from 'tailwind-variants';
-export type { VariantProps } from 'tailwind-variants';
-/**
- * Package version (synced with `package.json` at publish time).
- */
-export declare const VERSION = "0.1.0-beta";
-//# sourceMappingURL=index.d.ts.map
+export * from "./src/index";