@ai-matrx/design-system 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,222 @@
 # Changelog
 
+## 0.10.0 — 2026-09-07
+
+**THE MOTION SWEEP. Ten more primitives were animating with a host plugin this
+package never declared and cannot declare — and three of the four consumers
+never loaded it.** 0.8.0 and 0.9.0 closed the coin flip for `Accordion` and
+`Collapsible` one primitive at a time. This release swept the rest of the
+package for the same shape and found it everywhere at once.
+
+Every floating surface here — `Dialog`, `AlertDialog`, `Sheet`,
+`CommandDialog`, `Popover`, `DropdownMenu`, `ContextMenu`, `HoverCard`,
+`Select`, `Tooltip` — carried a correctly spelled
+`data-[state=open]:animate-in data-[state=closed]:animate-out
+data-[state=closed]:fade-out-0 data-[state=open]:zoom-in-95
+data-[side=bottom]:slide-in-from-top-2 …`. None of those is a Tailwind
+utility. They come from the `tailwindcss-animate` plugin (or its v4 successor
+`tw-animate-css`), which a host loads from its own CSS entry — something a
+node_modules package can neither ship nor require.
+
+Measured on each consumer's BUILT stylesheet before any of this landed
+(`grep -c 'animate-in\|slide-in-from'`):
+
+| Consumer | plugin | rules in built CSS |
+|---|---|---|
+| matrx-frontend | `@import "tw-animate-css"` in `globals.css` | present — animated |
+| aidream/dashboard | none | **0** |
+| aidream/workflow-studio | none | **0** |
+| matrx-extend | `tailwindcss-animate` in `package.json`, **never loaded** (a Tailwind v3 plugin; extend is on v4 with no `@plugin` directive) | **0** |
+
+So every dialog, dropdown, popover, tooltip, select and sheet in the two
+aidream admin apps and the Chrome extension appeared instantly, with no
+animation and no error, for as long as those components existed. The one host
+that worked, worked by accident of its own CSS entry. That is the doctrine
+sentence from `FEATURE.md` proven at scale: a primitive that leaves motion to
+the host has not shipped motion, it has shipped a coin flip.
+
+**The package now owns all of it.** `styles.css` gains a documented motion
+layer: package-declared `@keyframes matrx-*`, applied through `matrx-`-prefixed
+classes the components put on the DOM themselves, unlayered like the accordion
+and collapsible rules so every consumer gets identical motion even where the
+host plugin is still loaded.
+
+| Motion | Class | Primitives |
+|---|---|---|
+| scrim fade | `matrx-motion-overlay` | Dialog, AlertDialog, Sheet, CommandDialog |
+| centred card | `matrx-motion-dialog` | Dialog (desktop), AlertDialog, CommandDialog (desktop) |
+| bottom sheet | `matrx-motion-bottom-sheet` | Dialog / CommandDialog below the mobile breakpoint |
+| edge sheet | `matrx-motion-sheet-{top,bottom,left,right,center}` | Sheet, per `side` |
+| popper | `matrx-motion-popper` | Popover, DropdownMenu, ContextMenu, HoverCard, Select, Tooltip |
+| pulse | `matrx-pulse` | Skeleton |
+| spin | `matrx-spin` | every inline busy indicator in the package |
+
+Three things changed for the better on the way through:
+
+- **The popper grows out of its trigger, not out of itself.** The rule reads
+  the anchor-facing origin Radix publishes — as a fallback CHAIN over
+  `--radix-popper-transform-origin` and each primitive's own alias
+  (`--radix-select-content-transform-origin`,
+  `--radix-tooltip-content-transform-origin`, …), because reusing one
+  primitive's measured variable on another is precisely the silent death
+  census row 19f recorded. The `zoom-in-95` original always scaled from the
+  element's centre.
+- **Timing is a knob.** Every duration and easing resolves from a
+  `--matrx-motion-*` token in `tokens.css` (fast 150ms, base 200ms, slow
+  300ms, sheet 500ms, plus the two easings and the popper travel distance). An
+  org that wants calmer motion sets seven values instead of overriding twenty
+  rules. `prefers-reduced-motion` is NOT one of them — it is honoured in the
+  stylesheet regardless.
+- **`animate-pulse` / `animate-spin` came home too.** Those two ARE core
+  Tailwind, so they survived in a Tailwind host — but a Skeleton that does not
+  pulse is an empty grey box and a spinner that does not spin says the work
+  stopped. Both are four lines; the package owns them. Under reduced motion
+  they SLOW rather than stop, because stopping them removes information rather
+  than removing motion.
+
+**Where the line is, stated in the sheet:** this layer owns keyframe
+animation — motion that either happens or silently does not. It deliberately
+does not own Tailwind's `transition-*` / `duration-*` / `ease-*` utilities the
+primitives also carry (a hover colour, the progress bar's width, a close
+button's opacity). Those are core Tailwind, present in every Tailwind host,
+and their absence degrades to an instant-but-correct change rather than to a
+surface that lies about its state. Re-implementing them here would mean
+shipping a copy of Tailwind.
+
+**Opt-out:** `animated={false}` on `DialogContent`, `AlertDialogContent`,
+`SheetContent`, `PopoverContent`, `HoverCardContent`, `TooltipContent`,
+`SelectContent` and `Skeleton` returns the surface to instant. It is not the
+reduced-motion switch; the stylesheet already handles that.
+
+Guards, all proven failing-then-passing by re-introducing a
+`data-[state=open]:animate-in` on `PopoverContent`:
+
+- `motion.ts` — ONE exported constant per motion shape, so the eleventh
+  primitive cannot invent an eleventh spelling. Exported publicly
+  (`ALL_MOTION_CLASSES`, `FORBIDDEN_HOST_MOTION_UTILITIES`) so a consumer can
+  audit its own CSS against the same list.
+- `motion.test.tsx` — one case per primitive, asserting BOTH halves: the
+  rendered element carries the class, AND `styles.css` defines a rule for it
+  whose keyframe that same sheet declares. A class-name assertion alone would
+  have passed throughout the defect. Plus: every Sheet side wears its own edge
+  class and no other; the mobile bottom sheet does not wear the card's
+  keyframe; every opt-out actually opts out and leaves geometry alone.
+- `styles.test.ts` — no component may reference a host-plugin utility again;
+  every keyframe referenced is declared; every keyframe is `matrx-` prefixed;
+  every overlay duration comes from a token; every motion class appears in a
+  `prefers-reduced-motion` block; the popper origin chain is complete; and the
+  class list is exhaustive in BOTH directions.
+- The packed-tarball canary asserts thirteen rules, six keyframes, both origin
+  variables, the timing tokens, and — the assertion that would have caught
+  this whole release from outside — that **every keyframe the packed sheet
+  references is declared in that same packed sheet**, read from the artifact a
+  consumer installs with no host in the room.
+
+### Consumer action (C28)
+
+- 🔶 **This is a VISIBLE change in three of the four consumers, on purpose.**
+  `aidream/dashboard`, `aidream/workflow-studio` and `matrx-extend` get open /
+  close animation on every dialog, dropdown, popover, tooltip, select and
+  sheet **for the first time**. They need no code change and no CSS: they
+  already import `@ai-matrx/design-system/styles.css`, so bumping the version
+  is the whole adoption. If a specific surface must not move, pass
+  `animated={false}` — do not re-add a host plugin.
+- **matrx-frontend: `tw-animate-css` is no longer required by anything this
+  package renders.** Every `animate-in` / `slide-in-from-*` this package
+  emitted is gone. Audit your own components for remaining uses before
+  deleting the `@import "tw-animate-css"` from `app/globals.css` and the
+  dependency from `package.json`; the package no longer needs either.
+- **matrx-extend: delete `tailwindcss-animate` from `package.json`.** It has
+  never been loaded — it is a Tailwind v3 plugin in a v4 app with no `@plugin`
+  directive, and the built stylesheet proves it contributed zero rules. It is
+  dead weight that also makes the app look like it has motion support.
+- **Retiming is a token change now.** Do not override the motion rules; set
+  `--matrx-motion-duration-*` / `--matrx-motion-ease-*` /
+  `--matrx-motion-popper-travel`.
+- New type exports: `PopoverContentProps`, `SelectContentProps`,
+  `SkeletonProps`. New value exports: `ALL_MOTION_CLASSES`,
+  `FORBIDDEN_HOST_MOTION_UTILITIES`, `MOTION_OVERLAY`, `MOTION_DIALOG`,
+  `MOTION_BOTTOM_SHEET`, `MOTION_POPPER`, `MOTION_SHEET`, `MOTION_PULSE`,
+  `MOTION_SPIN`.
+- **Not fixed here, and named so it is not lost:** `@ai-matrx/kit`'s
+  `src/confirm/alert-dialog.tsx` carries the identical defect (`animate-in`,
+  `zoom-in-95`, `slide-in-from-top-[48%]`) and ships NO stylesheet at all, so
+  its confirm dialog is unanimated in the same three consumers. It cannot
+  import these rules: `@ai-matrx/design-system` depends on `@ai-matrx/kit`,
+  so the fix is a package-graph decision (move the confirm dialog, or invert
+  the dependency), not a class rename. `@ai-matrx/tap-target` has one
+  `animate-spin` in `src/tap-buttons.tsx` — core Tailwind, so it survives in
+  every current consumer, but it is the same class of host reliance and rides
+  the next tap-target release.
+
+## 0.9.0 — 2026-09-07
+
+**`Collapsible` gets the open/close transition the package never shipped
+(census row 19f, the tail 0.8.0 left open).** Until now `collapsible.tsx` was a
+bare re-export of Radix, and Radix ships no motion — it only publishes the
+measured height as `--radix-collapsible-content-height` and leaves the
+keyframes to you. So every consumer invented the transition itself, and the
+inventions are the reason this is a package change and not a host one:
+
+- **Two matrx-frontend collapsibles had never animated, silently.**
+  `components/matrx/matrx-collapsible/matrx-collapsible.tsx` and
+  `enhanced-collapsible.tsx` carried `animate-accordion-down`/`-up` on a
+  COLLAPSIBLE panel. Those keyframes interpolate to
+  `--radix-ACCORDION-content-height`, which Radix never sets on a collapsible,
+  so the target height was always an undefined variable. No animation, no
+  error, for as long as the components existed. (Found while deleting the host
+  keyframes in 0.8.0; the dead classes were removed then, with the finding
+  recorded in place.)
+- **Six more animated correctly — in exactly one app.** `ChatCollapsible`,
+  `ChatCollapsibleWrapper`, `TranscriptBlock`, `StructuredPlanBlock`,
+  `AdvancedCollapsible` and `armani-collapsible` used
+  `animate-slide-down`/`-up`, whose keyframes lived only in matrx-frontend's
+  `globals.css`. Same C26 silent host contract as the accordion's, wearing a
+  working coat: any other consumer of this package got nothing.
+
+`CollapsibleContent` now applies `.matrx-collapsible-content overflow-hidden`
+by default. The rule and its keyframes ship in `styles.css`, keyed off the
+COLLAPSIBLE height variable, at the same 200ms ease-out as
+`.matrx-accordion-content` so the two primitives agree on the same screen, and
+`prefers-reduced-motion: reduce` drops the animation while keeping the
+clipping. The panel also carries `data-slot="collapsible-content"`.
+
+Unlike `AccordionContent`, this does NOT wrap children in a padding div —
+collapsibles in the fleet pad their own bodies, and inserting a box would move
+every one of them.
+
+**Opt-out:** `<CollapsibleContent animated={false}>` returns bare Radix — no
+class, no clipping, instant open — for the rare panel with a child that must
+overflow its bounds (a non-portalled popover, a sticky header). It is not the
+reduced-motion switch; the stylesheet already handles that.
+
+Guards: `collapsible.test.tsx` (transition class present and not either host
+utility; the keyframes read the collapsible variable and not the accordion's;
+both reduced-motion states silenced; the opt-out removing class AND clipping),
+`matrx-accordion-content` + `matrx-collapsible-content` added to
+`styles.test.ts`'s required-rule list, and the packed-tarball canary now
+asserts both rules, the collapsible height variable, and a reduced-motion
+block actually ship in `dist/styles.css`. Proven failing-then-passing by
+re-pointing the keyframes at the accordion variable.
+
+### Consumer action (C28)
+
+- 🔶 **This is a VISIBLE change, on purpose.** Every `CollapsibleContent` in
+  every consumer now animates open and closed at 200ms where most of them
+  previously snapped. If a panel must not move or must not clip, pass
+  `animated={false}` — do not re-add host keyframes.
+- **Delete host collapsible keyframes and the per-site classes that used
+  them.** In matrx-frontend that is `slide-down` / `slide-up` in
+  `app/globals.css`, the `--animate-slide-down` / `--animate-slide-up` theme
+  entries, and the `data-[state=open]:animate-slide-down
+  data-[state=closed]:animate-slide-up` pairs on the six components listed
+  above (all done in this same session, per THE SAME-SESSION LAW).
+- **The two components named at the top of this entry —
+  `matrx-collapsible.tsx` and `enhanced-collapsible.tsx` — animate for the
+  first time ever** with this release. They need no code change; they get the
+  transition from the package.
+- New type export: `CollapsibleContentProps`.
+
 ## 0.8.0 — 2026-09-07
 
 **Accordion — the last stand-in in the fleet (census row 19c).** Growth waves 1

package/README.md

@@ -12,6 +12,22 @@ The small, semantic UI foundation shared by AI Matrx React applications — prim
 
 Where hosts had forked a primitive over DENSITY, density is a prop, not a fork: `Card size="sm|md|lg"`, `Table size="sm|md"`, `Accordion size="sm|md"`, `Switch`/`Avatar`/`Checkbox`/`Slider`/`RadioGroup`/`Toggle` `size`, `ResizableHandle size="xs".."4xl"`. It is declared once on the root and every item reads it from context, so a card cannot mix paddings and a radio group cannot mix control sizes.
 
+**Motion ships with the component — ALL of it.** Every animated surface here
+(`Dialog`, `AlertDialog`, `Sheet`, `CommandDialog`, `Popover`, `DropdownMenu`,
+`ContextMenu`, `HoverCard`, `Select`, `Tooltip`, `Accordion`, `Collapsible`,
+`Skeleton`) animates out of the box from keyframes in `styles.css`. **You never
+define keyframes, add an `animate-*` utility, or install `tailwindcss-animate`
+/ `tw-animate-css` for anything this package renders** — that plugin is loaded
+from a host's CSS entry, which is why three of the four apps that already used
+this package had zero animation on every overlay and no error to show for it
+(0.10.0). `prefers-reduced-motion` is honoured in the sheet.
+
+Retiming is a token change, not an override — set `--matrx-motion-duration-fast`
+/ `-base` / `-slow` / `-sheet`, `--matrx-motion-ease-out` / `-in`, or
+`--matrx-motion-popper-travel`. For one surface that must appear instantly,
+pass `animated={false}`; `CollapsibleContent`'s opt-out additionally stops it
+clipping its body, for the rare panel with a child that must overflow.
+
 **Mobile is the Drawer's job.** `Drawer` owns the iOS rules every host was re-deriving — `dvh` never `vh`, `pb-safe`/`pt-safe` safe-area padding, a 44px grab-handle target, `DrawerBody` as the `flex-1 min-h-0` scroll shard — and `direction` makes a top/side drawer a prop rather than a fork. Every touch control (`Slider`, `RadioGroup`, `ResizableHandle`) carries an invisible 44px target on coarse pointers, with desktop density untouched.
 
 ```bash