@ai-matrx/design-system 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # 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

package/README.md

@@ -12,7 +12,21 @@ 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.** `Accordion` and `Collapsible` animate open and closed out of the box (200ms, `prefers-reduced-motion` honoured) from rules in `styles.css` — you never define keyframes or add an `animate-*` utility for them. `CollapsibleContent` also clips its body while it moves; pass `animated={false}` for the rare panel with a child that must overflow its bounds.
+**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.