@ai-matrx/design-system 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,232 @@
 # Changelog
 
+## 0.10.1 — 2026-09-07
+
+**THE CENTRED DIALOG FLEW IN FROM OFF THE SCREEN.** 0.10.0 shipped a live
+regression: `Dialog`, `AlertDialog` and `CommandDialog` entered from beyond the
+top-left corner of the viewport and SNAPPED into place at the end of their
+200ms animation. Independent review caught it on the live surface, measured it,
+and proved the cause rather than inferring it.
+
+**The cause is that one Tailwind class means two different things.**
+
+| | `translate-x-[-50%] translate-y-[-50%]` compiles to |
+|---|---|
+| Tailwind **v3** | `transform: translate(-50%, -50%)` — REPLACED by an animation of `transform` |
+| Tailwind **v4** | `translate: -50% -50%` — an independent property that **composes with** `transform` |
+
+0.10.0's keyframes restated the centring inside `transform`
+(`translate(-50%,-48%)` -> `translate(-50%,-50%)`), which is correct under v3
+and doubles the centring under v4. Measured on the live element, viewport
+2560x1289, `getComputedStyle(el).translate === "-50% -50%"` while
+`transform === "none"` at rest:
+
+| | x | y |
+|---|---|---|
+| resting (correct) | 128 | 32 |
+| `currentTime = 0` | **-966** | **-525** |
+| `currentTime = 100` | **-1015** | **-571** |
+| `currentTime = 199`, `el.style.translate = "none"` | 137 | 41 |
+
+That last row is the proof: removing the `translate` property mid-animation
+restores the resting position exactly, because the element was wearing the
+centring twice.
+
+**The fix is not a different spelling of the keyframes** — there isn't one that
+works in both hosts. Restate the offset and v4 applies it twice; omit it and v3
+drops it for the animation's duration and snaps at the end. So the offset stops
+being a Tailwind utility at all. This package now owns it, in the `translate`
+property, in its own stylesheet:
+
+- `.matrx-dialog-centered` (`translate: -50% -50%`) carries the centring, and
+  the keyframes carry ONLY the delta — `opacity`, plus a 2% rise scaled up from
+  95% in `transform`, ending on `transform: none`. Resting geometry is
+  byte-identical to 0.10.0's; `transform` and `translate` never restate each
+  other again, in any host.
+- **Census — the same hazard, one more surface.** `Select` in `popper` position
+  held its 4px gap from the trigger with `data-[side=bottom]:translate-y-1` and
+  three siblings, while `matrx-popper-*` keyframes animate `transform`. Same
+  defect, 4px instead of half a viewport, failing the other way round (a v3
+  host ate the gap for the animation and snapped it back). It is now
+  `.matrx-popper-offset`, sized by the new `--matrx-popper-offset` token.
+- `Sheet`, the mobile bottom sheet and every other popper were **not** affected
+  and are unchanged — their translate utilities are zero-valued or absent.
+
+**The guard, proven failing-then-passing.** jsdom cannot measure a composite
+transform, so the hazard is asserted as a RULE over the sources in
+`motion.test.tsx`: *no component may pair a NON-ZERO Tailwind translate utility
+with a package motion class*, plus the centred keyframes may not mention `-50%`
+and must end on `transform: none`, plus each of the three surfaces must render
+the package's centring class. Restoring 0.10.0's exact shape (the utility in
+`DIALOG_DESKTOP_CLASSES` and the centring back in the keyframes) turns 4 of
+these red; the fix turns them green. `motion.test.tsx`'s old assertion that
+`translate-x-[-50%]` survives `animated={false}` PINNED the defect — it now
+asserts the centring class survives and the utility is gone. The C26 canaries
+grew too: both new rules are required in `styles.test.ts` and in the packed
+tarball.
+
+### Consumer action (C28)
+
+**None.** No API changed, no class a consumer writes changed, and resting
+geometry is identical. Take the patch.
+
+Named, because they are the ones that regressed: **aidream/dashboard**,
+**aidream/workflow-studio** and **matrx-extend** loaded no animation rules at
+all before 0.10.0, so their dialogs had always appeared instantly and correctly
+centred — 0.10.0 is what gave them a dialog that flies in from off-screen.
+matrx-frontend was NOT visibly changed by either release: its pre-0.10.0
+`tw-animate-css` spelling had the identical stacking flaw. All four are correct
+on 0.10.1.
+
+## 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
@@ -229,9 +456,19 @@ Install `@ai-matrx/design-system@0.7.0` (and `@ai-matrx/tap-target@0.2.0`), then
      `alert-dialog.tsx`, `alert.tsx`, `slider.tsx`, `resizable.tsx`,
      `matrx/resizable.tsx`, `radio-group.tsx`, `hover-card.tsx`,
      `toggle-group.tsx`, `toggle.tsx`, `radix-dialog-modal-context.tsx`.
-   - No other consumer repo carries a fork of these — verified by census on
+   - ~~No other consumer repo carries a fork of these — verified by census on
      2026-09-07 across matrx-extend, matrx-games, aidream `apps/dashboard` and
-     `apps/workflow-studio`.
+     `apps/workflow-studio`.~~ 🚨 **WRONG, corrected 2026-09-07.** That census
+     swept FOUR repos and there are FIVE: **matrx-local** (`desktop/`, the
+     Tauri app) carried its own `tooltip.tsx`, `slider.tsx`, `popover.tsx` and
+     `select.tsx` the whole time — plus ten more from the 0.5.0 list below,
+     whose Consumer action omitted it for the same reason. The sentence was
+     repeated verbatim into census row 19, and every later wave that read it
+     kept skipping the repo. matrx-local was adopted on 0.10.0 the same day
+     this was found: all seventeen forks swapped, fourteen files deleted, 131
+     files repointed, 56 twin-register rows added. **The lesson is the
+     sentence, not the repo — a "no other consumer" claim must name the repos
+     it swept, and the list must be checked against the actual consumer set.**
 3. **`matrx/resizable.tsx` callers keep their `size` prop** — it is the same
    eight-step scale, now on the one component. Callers of the plain
    `resizable.tsx` get the identical 2px default (`size="sm"`).
@@ -418,6 +655,11 @@ copy of something this version now ships:
   Bind `Card size="lg"` to keep this app's density (Table defaults to md as of 0.5.1).
 - **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"`.
+- **matrx-local** — `desktop/src/components/ui/{avatar,card,checkbox,dialog,progress,scroll-area,switch,tabs,textarea}.tsx`.
+  **Added 2026-09-07**: this repo was missing from the list above (see the
+  correction under 0.7.0 Consumer action 2). Adopted on 0.10.0 — `card` and
+  `dialog` keep one-prop binding shims for this app's `lg` density and its
+  glass surface; everything else re-points straight at the package.
 
 Hosts that do not already import the stylesheets must, or the new structural
 rules do nothing:

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.