@ai-matrx/design-system 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog
 
+## 0.5.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/design-system/v0.5.0..npm/design-system/v0.5.1 -- apps/shared/design-system`).
+No source changes intended and no consumer action required.
+
+## 0.5.0 — 2026-09-07
+
+**THE GROWTH WAVE (C18).** The 2026-09-07 adoption lane deleted 34 forked
+primitives across four repos but had to KEEP every primitive this package did
+not ship. This release ships them, so those forks can die too.
+
+Thirteen new primitives, each built from EVERY host variant rather than from
+one repo's copy: `Avatar`, `Card`, `Checkbox`, `Collapsible`, `ContextMenu`,
+`Dialog`, `DropdownMenu`, `Progress`, `ScrollArea`, `Switch`, `Table`, `Tabs`,
+`Textarea`. Plus `useIsMobile` / `MOBILE_BREAKPOINT`, lifted out of
+`command.tsx` (where it was private) because Dialog needed the same answer and
+two breakpoint hooks in one package is the duplication this package exists to
+end.
+
+**Density is a prop, never a fork.** The single biggest reason four hosts kept
+four cards and four tables was padding. `Card` (`size` sm/md/lg → p-2/p-4/p-6)
+and `Table` (`size` sm/md → p-2/p-3) declare density ONCE on the root; every
+section reads it from context, so a card cannot end up with a `p-6` header
+above a `p-2` body. `Switch`, `Avatar` and `Checkbox` carry the same treatment
+for the box sizes their forks disagreed on.
+
+**Rulings the forks had already paid for, now carried once:**
+
+- **No hydration mount gates.** Dialog, DropdownMenu, ContextMenu, Tabs and
+  Collapsible all render their roots unconditionally. The gate they inherited
+  rested on a false premise (Radix ids come from React's SSR-stable `useId`)
+  and deleted always-visible triggers from SSR and the first client paint —
+  around a list row, the list painted EMPTY and filled in after hydration.
+- **The dialog is clamped and scrolls inside itself; its footer is sticky.**
+  From the live incident where an 851px dialog in a 657px viewport put its
+  Create button below the fold, leaving only a backdrop click that dismisses
+  WITHOUT writing.
+- **Inactive tab panels UNMOUNT.** `forceMount` is opt-in. Force-mounting every
+  panel once let a HIDDEN tab win a provider tie-break and serve the VISIBLE
+  tab another tab's rows.
+- **A menu longer than the viewport scrolls instead of growing off-screen** —
+  both menus cap at the height Radix measured.
+- **An indeterminate `Progress` no longer renders as a confident 0%.** The
+  shadcn body every host copied computed `translateX(-${100 - (value || 0)}%)`,
+  turning "nobody knows" into "not started". Indeterminate now sweeps and
+  carries `data-state="indeterminate"`.
+- **An indeterminate `Checkbox` shows a different glyph than a checked one** —
+  a half-selected "select all" wearing a full check states something false.
+
+**Seams.** Dialog, DropdownMenu and ContextMenu portal through
+`usePortalContainer`; `DialogContent` PROVIDES that container to its own
+children, so a popover or menu opened inside a dialog mounts inside it (staying
+in the scroll shard where its wheel events work). `useDialogContainer` exposes
+the same element. An explicit `container` prop always wins.
+`ScrollArea` exposes `viewportClassName` / `viewportRef` / `scrollBarClassName`
+— the viewport being unreachable is precisely why workflow-studio forked it,
+and `viewportRef` is the scrolling element programmatic scroll-to-bottom needs.
+
+**CSS (C26):**
+
+- `styles.css` gains `.shadow-textarea` and `.matrx-progress-indeterminate`
+  (plus its keyframes, declared unlayered because keyframes cannot live inside
+  a layer's rule set portably). Still zero hardcoded colour.
+- `tokens.css` gains `--shadow-textarea`, defaulting to `--shadow-input`.
+
+**Corrections shipped with the ports (visual, deliberate, listed so nobody
+reports them as regressions):**
+
+- `shadow-textarea` NOW EXISTS. The ported Textarea asked for it at every call
+  site and NO host defined the token or generated the utility, so ~125 fields
+  rendered flat while their code said otherwise. Set `--shadow-textarea: none`
+  for the old flat look.
+- Textarea colour moves onto tokens (literal black/white body text, raw
+  palette placeholder and focus ring, and a dark elevation referencing a
+  property no host defined — which computed to no shadow at all).
+- `Input` / `BasicInput` gain `file:text-foreground`, so a file input's button
+  label follows the theme instead of the UA default.
+- Switch's OFF track reads `bg-input` everywhere (workflow-studio's fork used
+  `bg-muted`, which makes an off switch vanish into a muted panel).
+- `CardHeader` / `CardFooter` corner rounding is `rounded-t/b-[inherit]`, so it
+  matches whatever radius the card actually has (matrx-frontend's fork rounded
+  sections to `lg` inside an `xl` card).
+- `AvatarFallback` carries defined type (`text-muted-foreground`, sized by the
+  avatar's `size`) instead of inheriting whatever the surrounding row used.
+- `Table` keeps matrx-frontend's horizontal-scroll wrapper as the default
+  (`wrap={false}` to opt out) and offers dashboard's sticky header as
+  `<TableHeader sticky>`.
+
+**Radix packages are ordinary dependencies of this package, not peers** (only
+`react`/`react-dom` are peers), and all of them moved to current latest.
+
+### Consumer action (C28)
+
+Install `@ai-matrx/design-system@0.5.0` and DELETE these forks. Every one is a
+copy of something this version now ships:
+
+- **matrx-frontend** — `components/ui/{avatar,card,checkbox,collapsible,dialog,dropdown-menu,progress,scroll-area,switch,table,tabs,textarea}.tsx`
+  and `components/ui/context-menu/context-menu.tsx`. High-fanout files become
+  re-export shims that bind this repo's historical variant (`Card size="sm"`,
+  `Switch size="sm"`, `Table size="sm"`), matching what the 08-30 swap
+  established for `button` / `badge` / `label` / `separator`. The
+  clipboard/motion variants (`CopyInput`, `FancyInput`, `DeleteInput`,
+  `CopyTextarea`, `FancyTextarea`) stay host-owned under the C8 split-out law.
+- **matrx-extend** — `src/components/ui/{card,scroll-area,switch,tabs,textarea}.tsx`.
+  `src/components/ui/collapsible.tsx` is NOT a fork of this package's
+  `Collapsible` — it is a bespoke labelled-section control with its own API —
+  and stays.
+- **matrx-games** — `components/ui/{avatar,dropdown-menu,progress,tabs}.tsx`
+  (dead code: zero import sites) and `components/ui/scroll-area.tsx`.
+  `card.tsx` and `dialog.tsx` are a different generation (Base UI, not Radix)
+  carrying that app's own visual language; they are DEFERRED, not forgotten —
+  see FEATURE.md § Deferred.
+- **aidream/apps/dashboard** — `src/components/ui/{avatar,card,checkbox,context-menu,dialog,dropdown-menu,scroll-area,switch,table,tabs,textarea}.tsx`.
+  Pass `Card size="lg"` and `Table size="md"` to keep this app's density.
+- **aidream/apps/workflow-studio** — `src/components/ui/{dialog,dropdown-menu,scroll-area,switch,tabs,textarea}.tsx`.
+  Its ScrollArea viewport hack becomes `viewportClassName="[&>div]:!block [&>div]:min-w-0"`.
+
+Hosts that do not already import the stylesheets must, or the new structural
+rules do nothing:
+
+```ts
+import "@ai-matrx/design-system/tokens.css";
+import "@ai-matrx/design-system/styles.css";
+```
+
 ## 0.4.2
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see
@@ -81,12 +207,28 @@ palette colour.
    ```
 
 2. **Declare the layer order once**, as the first line of your Tailwind/CSS
-   entry, so the package's default token values stay below your own:
+   entry:
 
    ```css
    @layer matrx-design-system-tokens, matrx-design-system;
    ```
 
+   **What actually protects your brand (corrected 2026-09-07, learned adopting four
+   more apps):** Tailwind v4 does NOT emit this statement into the built sheet — it
+   survives only as the relative order of the two package layers. Your tokens win
+   because host `:root` declarations are UNLAYERED and unlayered beats every layer.
+   So: keep your `:root { --primary: … }` declarations unlayered (never wrap them in
+   `@layer`), or the package defaults will override them. Verify on the BUILT css:
+   the package `--success` should appear inside `@layer matrx-design-system-tokens`
+   and your own `--success` later, unlayered.
+
+2b. **Map the status colours or Badge/ScoreRing render NO css.** The package's
+   `Badge` `success`/`warning`/`info` variants and the ScoreRing helpers resolve
+   `--color-success` / `--color-warning` / `--color-info`. A host whose `@theme`
+   does not define those three gets empty utilities — silently. Four consumer apps
+   shipped that way for a week (found 2026-09-07). Define them in your `@theme`
+   (or import `theme.css` if you have no theme of your own).
+
 3. **Delete your host copies of the moved rules** — `.matrx-scroll-fade[…]`,
    the `.matrx-mobile-sheet` block, `.matrx-glass-thin-border` (+ its
    `:hover` / `:active` / `:has(> a:…)` states). They now ship in the package;

package/README.md

@@ -1,6 +1,14 @@
 # @ai-matrx/design-system
 
-The small, semantic UI foundation shared by AI Matrx React applications — primitives whose behavior and variants are identical across Vite and Next.js hosts. Version 0.2 ships Button, Badge, Label, Separator, the Input family, Popover, Sheet, Skeleton, EditableLabel, SegmentedControl, ScoreRing, BottomSheet + TabbedBottomSheet, OverflowToolbar, the `useScrollFade` hook, and the `cn` utility.
+The small, semantic UI foundation shared by AI Matrx React applications — primitives whose behavior and variants are identical across Vite and Next.js hosts.
+
+**Controls:** Button, Badge, Label, Separator, the Input family, the Textarea family, Checkbox, Switch, Avatar, Progress.
+**Surfaces:** Card, Table, Tabs, Collapsible, ScrollArea, Popover, Sheet, Dialog, BottomSheet + TabbedBottomSheet, Skeleton.
+**Menus:** DropdownMenu, ContextMenu, Command / CommandDialog, Select, CreatablePicker.
+**Composed:** EditableLabel, SegmentedControl, ScoreRing, OverflowToolbar.
+**Hooks + utilities:** `useScrollFade`, `useIsMobile`, `usePortalContainer`, `useDialogContainer`, `cn`.
+
+Where hosts had forked a primitive over DENSITY, density is a prop, not a fork: `Card size="sm|md|lg"`, `Table size="sm|md"`, `Switch`/`Avatar`/`Checkbox` `size`. It is declared once on the root and every section reads it from context, so a card cannot mix paddings.
 
 ```bash
 pnpm add @ai-matrx/design-system