@sableui/react 0.13.2 → 0.15.0

package/dist/components/collapsible/collapsible.meta.js

@@ -92,6 +92,38 @@ var collapsibleMeta = {
     }
   ],
   tokensUsed: ["foreground", "muted-foreground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A collapsible is part of the page it sits in, present from first paint. Its trigger is what the reader notices, not an entrance."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "CollapsibleTrigger",
+      why: "The trigger is whatever the consumer renders (usually a Button), and that control brings its own response. Adding one here would double it."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-disclosure",
+      part: "CollapsiblePanel",
+      why: "The height change ties the content that appears to the trigger that was pressed; snapped open, everything below jumps with nothing linking cause to effect."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "CollapsibleIndicator",
+      why: "The chevron turns with the panel rather than flipping in one frame: motion-interactive lists `rotate`, the property rotate-180 writes."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Nothing here is indeterminate; content that loads on open should put its own loader inside the panel."
+    }
+  ],
   a11y: [
     "Base UI wires aria-expanded on the trigger and aria-controls/id between trigger and panel.",
     "Trigger is a real <button>; toggles on click and Enter/Space.",

package/dist/components/color-field/color-field.meta.js

@@ -95,6 +95,32 @@ var colorFieldMeta = {
       description: "Accessible name for the trigger; the current value is appended to it."
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "Popover",
+      why: "The picker grows out of the swatch it edits (PopoverContent's recipe, its origin on the anchor). In a property panel with a column of swatches, that origin is what tells you which colour you are now editing."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Swatch",
+      why: "Preset swatches lift slightly under the pointer. They are 20px chips of colour with no label, and the eased lift is what tells you which one a click will take."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Handles",
+      why: "The saturation, hue and alpha handles follow the pointer exactly. A handle that trailed the drag would misreport the colour under the cursor, and a swatch or a typed hex moving them is the value changing, which the field should show at once."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Picking is synchronous. The EyeDropper is the browser's own modal, with its own feedback."
+    }
+  ],
   a11y: [
     `The trigger's accessible name includes the current value, so a screen reader announces the colour rather than just "button" \u2014 the swatch itself conveys nothing without sight.`,
     "The Transparent entry is a toggle with aria-pressed, because it is a state of the value and not a navigation action.",

package/dist/components/combobox/combobox.meta.js

@@ -203,6 +203,50 @@ var comboboxMeta = {
     "secondary",
     "secondary-foreground"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "ComboboxContent",
+      why: "The list grows from the field it filters, its origin on Base UI's anchor. With several comboboxes in a form, that is what attaches the open list to the one being typed in."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "ComboboxItem",
+      why: "A row's ink eases as the pointer or the arrow keys reach it, so moving through a long filtered list reads as continuous movement rather than rows blinking."
+    },
+    {
+      slot: "response",
+      recipe: "custom",
+      part: "Highlight",
+      why: "One highlight travels to the active row (lib/highlight-glide: a measured translate on the motion tokens) instead of each row painting its own fill. When the list re-filters under the caret, the highlight sliding to the new match is what shows the keyboard target moved."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Toggle",
+      why: "The chevron toggle at the field's edge eases its ink on hover; the change is what tells you it is a separate target from the text box."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Toggle",
+      why: "The chevron turns 180\xB0 as the list opens and closes (motion-interactive lists `rotate`), in step with the popup, so it reads as one control changing direction."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-pop",
+      part: "ComboboxContent",
+      why: "Closing shrinks back toward the field, returning the eye to the input that now holds the value."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Combobox ships no loading part. A list fetched as you type shows a Spinner (motion-spin) in ComboboxEmpty or the content \u2014 where the results will land \u2014 and only the caller knows a fetch is in flight."
+    }
+  ],
   a11y: [
     "Base UI provides role=combobox/listbox/option, roving tabindex, arrow-key navigation, and type-to-filter.",
     "Esc and outside-press dismiss; focus returns to the input on close.",

package/dist/components/command-menu/command-menu.js

@@ -187,8 +187,13 @@ function CommandMenuBody({
       ),
       query ? (
         // Empties the query and hands focus back to the field, which owns
-        // the keyboard (the list is driven from it).
-        /* @__PURE__ */ jsx(
+        // the keyboard (the list is driven from it). It mounts on the first
+        // keystroke, beside the caret the eye is on, so the wrapper fades it
+        // in (motion-appear) rather than letting it blink into the header.
+        // On the wrapper, not the Button: motion-appear declares its own
+        // transition list and would fight motion-interactive for the one
+        // transition-property slot. Removal stays instant.
+        /* @__PURE__ */ jsx("span", { className: "flex motion-appear", children: /* @__PURE__ */ jsx(
           Button,
           {
             variant: "ghost",
@@ -203,7 +208,7 @@ function CommandMenuBody({
             },
             children: /* @__PURE__ */ jsx(Icon, { name: "xmark" })
           }
-        )
+        ) })
       ) : null
     ] }),
     /* @__PURE__ */ jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: resultCount === 0 ? "No results" : `${resultCount} result${resultCount === 1 ? "" : "s"}` }),

package/dist/components/command-menu/command-menu.meta.js

@@ -229,6 +229,44 @@ var commandMenuMeta = {
     "accent",
     "accent-foreground"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-pop",
+      part: "Dialog",
+      why: "The palette opens on DialogContent's recipe over a fading backdrop. It is summoned by a keystroke from nowhere on screen, and the short scale-in is what says a layer arrived rather than the page changing. The inline CommandMenuPanel has no entrance: it is part of the page."
+    },
+    {
+      slot: "arrival",
+      recipe: "motion-appear",
+      part: "Clear button",
+      why: "The clear button mounts on the first keystroke, beside the caret the eye is already on. Fading in, it reads as the field offering a way back instead of a control blinking into the header. Removal is instant, so an emptied query does not wait on its X."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "CommandItem",
+      why: "The active row follows both the arrow keys and the pointer, and its fill eases between rows, so scanning results while typing reads as one highlight moving rather than rows flashing in turn."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "CommandMenuTrigger",
+      why: "The search-shaped trigger eases its ink on hover like the field shell it imitates, so it reads as the field it opens."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-pop",
+      part: "Dialog",
+      why: "Closing on Enter or Esc shrinks the palette away fast and returns focus where it came from; the exit is the confirmation that the command ran or was dismissed."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "List",
+      why: "Results are filtered synchronously from the items passed in. Async results are the caller's to mark with a Spinner (motion-spin) in the list, where the person is already looking."
+    }
+  ],
   a11y: [
     "CommandMenuTrigger is a real <button> named by its visible placeholder, with aria-haspopup=dialog and aria-keyshortcuts (Meta+K on macOS, Control+K elsewhere). Its Kbd hint is aria-hidden, so the shortcut is announced once rather than read as part of the name.",
     "The shortcut never fires from inside a text field, textarea, select or contenteditable (Ctrl+K is delete-to-end-of-line in macOS text views), except the palette's own input.",

package/dist/components/confirm-button/confirm-button.js

@@ -0,0 +1,179 @@
+"use client";
+
+// src/components/confirm-button/confirm-button.tsx
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { isPromise } from "../../lib/is-promise.js";
+import { StackedActionsContext } from "../../lib/presentation.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
+import { useAutoSize } from "../../motion/useAutoSize.js";
+import { Button } from "../button/button.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var OPTICAL_START = "[--button-ps:calc(var(--button-px)-(--spacing(0.5)))] ps-(--button-ps)";
+var DOUBLE_PRESS_GUARD_MS = 300;
+function defaultConfirmLabel(label) {
+  if (typeof label !== "string" || label.trim() === "") return "Confirm?";
+  return `Confirm ${label.charAt(0).toLowerCase()}${label.slice(1)}?`;
+}
+function ConfirmButton({
+  children,
+  confirmLabel,
+  onConfirm,
+  timeout = 3e3,
+  variant = "secondary",
+  confirmVariant = "destructive",
+  size,
+  icon,
+  confirmHint = "Press again to confirm.",
+  motion,
+  disabled,
+  className,
+  onBlur,
+  onKeyDown,
+  ref,
+  ...props
+}) {
+  const stacked = useContext(StackedActionsContext);
+  const callerSized = /(^|\s)([\w-]+:)*(w-|flex-1|grow(\s|$)|basis-)/.test(className ?? "");
+  const autoSize = useAutoSize({ enabled: !stacked && !callerSized });
+  const [phase, setPhase] = useState("idle");
+  const armedAt = useRef(0);
+  const rootRef = useRef(null);
+  const armed = phase !== "idle";
+  const prompt = confirmLabel ?? defaultConfirmLabel(children);
+  const disarm = useCallback(() => setPhase((p) => p === "armed" ? "idle" : p), []);
+  useEffect(() => {
+    if (phase !== "armed") return;
+    const timer = setTimeout(disarm, timeout);
+    return () => clearTimeout(timer);
+  }, [phase, timeout, disarm]);
+  useEffect(() => {
+    if (phase !== "armed") return;
+    const onPointerDown = (event) => {
+      if (!rootRef.current?.contains(event.target)) disarm();
+    };
+    document.addEventListener("pointerdown", onPointerDown, true);
+    return () => document.removeEventListener("pointerdown", onPointerDown, true);
+  }, [phase, disarm]);
+  useEffect(() => {
+    if (disabled) setPhase((p) => p === "armed" ? "idle" : p);
+  }, [disabled]);
+  const handleClick = (_event) => {
+    if (phase === "idle") {
+      armedAt.current = Date.now();
+      setPhase("armed");
+      return;
+    }
+    if (phase !== "armed" || Date.now() - armedAt.current < DOUBLE_PRESS_GUARD_MS) return;
+    const result = onConfirm();
+    if (isPromise(result)) {
+      setPhase("confirming");
+      const idle = () => setPhase("idle");
+      result.then(idle, idle);
+      return result;
+    }
+    setPhase("idle");
+    return result;
+  };
+  const handleKeyDown = (event) => {
+    if (event.key === "Escape" && phase === "armed") {
+      event.preventDefault();
+      event.stopPropagation();
+      disarm();
+    }
+    onKeyDown?.(event);
+  };
+  const handleBlur = (event) => {
+    disarm();
+    onBlur?.(event);
+  };
+  const setRefs = (node) => {
+    rootRef.current = node;
+    autoSize.outerRef.current = node;
+    if (typeof ref === "function") ref(node);
+    else if (ref) ref.current = node;
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        ...props,
+        ref: setRefs,
+        size,
+        variant: armed ? confirmVariant : variant,
+        disabled,
+        "data-state": armed ? "armed" : "idle",
+        "data-motion": motionAttribute(motion),
+        className: cn(
+          // overflow-clip: while the width eases, the content is already at
+          // its new size, so it is clipped to the button rather than painting
+          // past its fill. A ring is a box-shadow and is not clipped.
+          "relative overflow-clip motion-size",
+          // The icon lives inside the measured span (below), not in Button's
+          // iconStart slot, so Button's optical start padding is restated.
+          icon != null && OPTICAL_START,
+          className
+        ),
+        onClick: handleClick,
+        onKeyDown: handleKeyDown,
+        onBlur: handleBlur,
+        children: [
+          /* @__PURE__ */ jsxs(
+            "span",
+            {
+              ref: autoSize.innerRef,
+              className: "inline-flex w-max items-center gap-(--control-gap) transition-opacity duration-(--motion-duration-fast) ease-standard",
+              children: [
+                icon,
+                /* @__PURE__ */ jsxs("span", { className: "inline-grid overflow-x-clip", children: [
+                  /* @__PURE__ */ jsx(ConfirmLabel, { active: !armed, children }),
+                  /* @__PURE__ */ jsx(ConfirmLabel, { active: armed, children: prompt })
+                ] })
+              ]
+            }
+          ),
+          phase === "armed" ? /* @__PURE__ */ jsx(
+            "span",
+            {
+              "aria-hidden": "true",
+              "data-slot": "confirm-countdown",
+              className: "pointer-events-none absolute inset-x-(--button-px) bottom-1 h-0.5 origin-left rounded-full bg-current opacity-40 transition-[scale] ease-linear scale-x-0 starting:scale-x-100 rtl:origin-right",
+              style: {
+                transitionDuration: `calc(${timeout}ms * var(--motion-scale, 1) * var(--motion-expressive, 1))`
+              }
+            }
+          ) : null
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { role: "status", className: "sr-only", children: phase === "armed" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      prompt,
+      " ",
+      confirmHint
+    ] }) : null })
+  ] });
+}
+ConfirmButton.displayName = "ConfirmButton";
+function ConfirmLabel({ active, children }) {
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      "aria-hidden": active ? void 0 : "true",
+      "data-active": active,
+      className: cn(
+        "col-start-1 row-start-1 flex justify-center transition-opacity duration-(--motion-duration-fast) ease-standard",
+        active ? "w-max" : "w-0 opacity-0"
+      ),
+      children: /* @__PURE__ */ jsx("span", { className: "sable-label-trim", children })
+    }
+  );
+}
+export {
+  ConfirmButton
+};

package/dist/components/confirm-button/confirm-button.meta.js

@@ -0,0 +1,143 @@
+// src/components/confirm-button/confirm-button.meta.ts
+var confirmButtonMeta = {
+  name: "ConfirmButton",
+  summary: 'An inline two-step confirm for a low-stakes destructive or irreversible action: the first press arms it ("Delete" \u2192 "Confirm delete?", destructive), a second press within a few seconds runs it, and leaving it disarms it.',
+  status: "stable",
+  keywords: [
+    "confirm",
+    "confirmation",
+    "two-step",
+    "press again",
+    "click again",
+    "arm",
+    "delete",
+    "remove",
+    "destructive",
+    "inline confirm",
+    "hold to confirm"
+  ],
+  usage: {
+    description: "Use ConfirmButton when an action deserves one beat of second thought but not a modal: deleting a draft, removing a row, revoking one token, clearing a list that can be rebuilt. The question appears on the button the user is already pressing, so confirming costs one more press in the same place and backing out costs nothing.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Keep the idle label a plain verb ("Delete", "Remove", "Revoke") and let the confirm label ask about it ("Confirm delete?" by default, or `confirmLabel`). The user should read the consequence on the very control they are about to press again.'
+      },
+      {
+        guidance: "do",
+        description: "Leave room for it to grow. The button eases wider to fit the question, so give it space at the end of a row or in a table's action column rather than wedging it between fixed-width neighbours."
+      },
+      {
+        guidance: "do",
+        description: "Return the promise from `onConfirm` when the action is async. The button stays armed with a spinner until it settles and refuses further presses, so a slow network cannot run it twice."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for high-stakes or wide-reaching actions \u2014 deleting a project, an account, anything other people depend on. Those need the consequence spelled out and a typed or deliberate confirmation; use DestructiveActionModal.",
+        instead: ["DestructiveActionModal"]
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it where an undo is possible. If the action can be reversed, run it on the first press and offer Undo in a Toast \u2014 no question at all is faster than a good question.",
+        instead: ["Toast"]
+      },
+      {
+        guidance: "dont",
+        description: 'Do not use it for a non-destructive primary action ("Save", "Send"). Asking twice for something harmless teaches people to press twice without reading, which is what defeats the confirm when it matters; use Button.',
+        instead: ["Button"]
+      }
+    ]
+  },
+  related: {
+    components: ["Button", "DestructiveActionModal", "Toast", "OverflowMenu"]
+  },
+  props: [
+    { name: "children", type: "ReactNode", description: 'The idle label \u2014 the action, e.g. "Delete".' },
+    {
+      name: "confirmLabel",
+      type: "ReactNode",
+      default: '"Confirm <label>?"',
+      description: 'The label while armed. Defaults to "Confirm delete?" for a text label "Delete" (first letter lowered) and "Confirm?" otherwise. Pass it to localise.'
+    },
+    {
+      name: "onConfirm",
+      type: "() => unknown",
+      description: "Runs on the second press while armed. Return a promise to hold the button armed with a spinner until it settles."
+    },
+    { name: "timeout", type: "number", default: "3000", description: "How long it waits for the second press, in ms. A decision time, so it is not scaled by motion settings." },
+    { name: "variant", type: "ButtonVariant", default: '"secondary"', description: "The idle look \u2014 any Button variant." },
+    { name: "confirmVariant", type: "ButtonVariant", default: '"destructive"', description: "The armed look \u2014 any Button variant." },
+    { name: "size", type: '"xs" | "sm" | "md" | "cta"', default: '"md"', description: "A labelled Button size. Icon-only sizes are excluded: the label is the interaction." },
+    { name: "icon", type: "ReactNode", description: 'A leading icon kept through both states, e.g. `<Icon name="trash" />`.' },
+    { name: "disabled", type: "boolean", default: "false", description: "Disables it; disabling while armed also disarms." },
+    {
+      name: "confirmHint",
+      type: "string",
+      default: '"Press again to confirm."',
+      description: "Read to assistive tech after the armed label when it arms. Override to localise."
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` (default) inherits the app's policy, `subtle` keeps feedback and drops the flourish, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting. The width easing and the draining countdown are the flourish; the label cross-fade and colour change stay."
+    }
+  ],
+  variants: {
+    variant: ["primary", "secondary", "ghost", "outline", "destructive", "link", "floating", "field", "on-color", "on-color-outline", "on-color-ghost"],
+    confirmVariant: ["destructive", "primary", "secondary", "outline"],
+    size: ["xs", "sm", "md", "cta"]
+  },
+  tokensUsed: ["secondary", "secondary-foreground", "destructive", "destructive-foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "It is a button in a row of actions, and arrives with that row. Its moment is the arming, not the mount."
+    },
+    {
+      slot: "response",
+      recipe: "motion-press",
+      part: "Root",
+      why: "Inherited from Button with motion-interactive. The press settle confirms the first press landed even before the label has finished changing \u2014 which is what stops a second, accidental press."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-size",
+      part: "Root",
+      why: "Arming changes the label, so the button's width changes. Easing it makes the button visibly grow into the question and its neighbours travel, instead of the row jumping under the pointer that is about to press again. useAutoSize measures the content and writes a px width for motion-size to ease between (a content-sized box is width:auto before and after, which cannot transition). The labels cross-fade in one cell so there is never a frame with both or neither."
+    },
+    {
+      slot: "activity",
+      recipe: "custom",
+      part: "Countdown",
+      why: "While armed, a thin line drains along the foot of the button over the timeout \u2014 the only way to see that the question expires. A transition on scale, timed by the `timeout` prop and multiplied by the motion scale and expressive factor, so under reduced motion or `subtle` it is absent rather than frozen full."
+    }
+  ],
+  a11y: [
+    "A native <button> through Button. Focus stays on it through both presses; Enter and Space confirm exactly as a click does.",
+    "Only the current label is in the accessible name \u2014 the other is aria-hidden \u2014 so the name changes to the question while armed.",
+    `Arming is also announced through a polite role=status region outside the button ("Confirm delete? Press again to confirm."), because a focused button's name change is not read by every screen reader.`,
+    "Escape disarms and is consumed, so it does not also close the dialog or popover around it. Focus leaving, a press elsewhere, or the timeout disarm it too.",
+    "A second press within 300ms of arming is ignored: a double-click is a habit, not a decision.",
+    "Under reduced motion the label still changes and the colour still turns; only the width easing and countdown are dropped."
+  ],
+  examples: [
+    {
+      label: "Delete a row",
+      code: '<ConfirmButton icon={<Icon name="trash" />} onConfirm={() => removeRow(id)}>Delete</ConfirmButton>'
+    },
+    {
+      label: "Custom question, longer wait",
+      code: '<ConfirmButton variant="ghost" size="sm" confirmLabel="Revoke this key?" timeout={5000} onConfirm={revokeKey}>Revoke</ConfirmButton>'
+    },
+    {
+      label: "Async confirm",
+      code: "<ConfirmButton onConfirm={() => api.deleteDraft(draft.id)}>Discard draft</ConfirmButton>"
+    }
+  ]
+};
+export {
+  confirmButtonMeta
+};

package/dist/components/confirm-button/index.js

@@ -0,0 +1,7 @@
+// src/components/confirm-button/index.ts
+import { ConfirmButton } from "./confirm-button.js";
+import { confirmButtonMeta } from "./confirm-button.meta.js";
+export {
+  ConfirmButton,
+  confirmButtonMeta
+};

package/dist/components/data-table/data-table.js

@@ -122,8 +122,12 @@ function DataTable({
                     /* @__PURE__ */ jsx(
                       Icon,
                       {
-                        name: active && sort.direction === "desc" ? "chevron-down" : "chevron-up",
-                        className: cn("text-xs", !active && "opacity-60")
+                        name: "chevron-up",
+                        className: cn(
+                          "text-xs motion-interactive",
+                          active && sort.direction === "desc" && "rotate-180",
+                          !active && "opacity-60"
+                        )
                       }
                     )
                   ]

package/dist/components/data-table/data-table.meta.js

@@ -139,6 +139,38 @@ var dataTableMeta = {
     }
   ],
   tokensUsed: ["muted-foreground", "foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Rows render with the page or the query that produced them. Staggering rows in delays reading a table someone opened to scan."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Row",
+      why: "Body rows ease to a muted wash under the pointer (TableRow's recipe), which keeps the eye on the right line across a wide row of numbers. Sortable headers are ghost Buttons and answer on Button's recipe."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Sort chevron",
+      why: "One chevron turns to show direction instead of two glyphs swapping, so ascending to descending reads as the same column reversing. Its opacity rises from the resting 60% as the column becomes the sort."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Row",
+      why: "A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "DataTable has no loading state. While data is fetched, render Skeleton rows (motion-shimmer) in its place \u2014 only the caller knows a fetch is in flight."
+    }
+  ],
   a11y: [
     "Sorted columns set aria-sort=ascending/descending on the header cell.",
     "Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.",

package/dist/components/entity/entity.meta.js

@@ -86,6 +86,32 @@ var entityMeta = {
     density: ["compact", "comfortable"]
   },
   tokensUsed: ["accent", "accent-foreground", "foreground", "muted-foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Rows arrive with the list they belong to. Entering one at a time is a stagger, and a stagger on a list someone opened to scan is a delay."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "Only the interactive row reacts: its hover fill, a step off the surface it sits on, eases in. A static row never fakes clickability, and an interactive one answers the pointer without flicker as it moves down a list."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "`selected` eases the fill onto the current row of a list\u2013detail view, so opening another record reads as the selection moving rather than two rows flashing."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "A record row has nothing of its own to wait for. A row whose action is pending puts a loading Button in `action`."
+    }
+  ],
   a11y: [
     "Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.",
     "interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row \u2014 native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.",