@sableui/react 0.13.1 → 0.14.0

package/dist/components/tool-call/tool-call.meta.js

@@ -0,0 +1,147 @@
+// src/components/tool-call/tool-call.meta.ts
+var toolCallMeta = {
+  name: "ToolCall",
+  summary: "One tool an agent called, as a quiet row inside its turn: a status glyph, what it did, the tool's name and where it is \u2014 with the arguments and result behind a disclosure.",
+  status: "stable",
+  keywords: [
+    "tool call",
+    "function call",
+    "tool use",
+    "agent step",
+    "mcp",
+    "ai",
+    "tool result",
+    "agent activity"
+  ],
+  usage: {
+    description: "Use it for each tool call in an assistant's turn, so the person can see what the agent did and check any step. The row is the summary \u2014 glyph, a plain-words title, the tool's name, the status \u2014 and stays one line, so a turn with ten calls is still scannable. Input and output sit behind the disclosure, because they are read rarely and, when they are, in full.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: 'Give it a `title` in plain words, in the tense of the status: "Searching the docs" while running, "Searched the docs" once done. The `name` stays beside it in mono for the person who wants to know exactly which tool ran.'
+      },
+      {
+        guidance: "do",
+        description: "Drive `status` from the call's real state and keep the same element mounted as it changes. The spinner swaps for the outcome in place, and the change is announced to screen readers once."
+      },
+      {
+        guidance: "do",
+        description: 'Pass `error` with `status="error"`. It shows under the row without opening anything, because a failure is the one result everyone needs to read.'
+      },
+      {
+        guidance: "do",
+        description: "Pass a rendered result as `children` when the output is something to look at \u2014 a list of hits, a diff \u2014 rather than data to inspect. It replaces the output's code view, and `input` still shows above it."
+      },
+      {
+        guidance: "dont",
+        description: 'Do not put the approve and deny buttons in a ToolCall. A call held for permission is `status="awaiting"` here, and the decision itself is ApprovalBlock, which says what will happen and asks once.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for the agent's thinking or a progress note. A wait with no tool behind it is ThinkingOrb or a Spinner with a status line, and a row that claims a tool ran when none did makes every other row less trustworthy.",
+        instead: ["ThinkingOrb", "Spinner"]
+      },
+      {
+        guidance: "dont",
+        description: "Do not open every call by default. A turn whose calls all show their JSON buries the answer; leave `defaultOpen` for the one call the person is likely to check, if any."
+      }
+    ],
+    anatomy: [
+      { name: "Status glyph", required: true, description: "Spinner while running, then the outcome: check, warning, clock (awaiting approval) or \xD7. The only part that moves." },
+      { name: "Title", required: false, description: "What the call does, in plain words. Without one, the tool's name leads." },
+      { name: "Name", required: true, description: "The tool's own name in mono, after the title. Hidden below the sm breakpoint when a title is present." },
+      { name: "Status", required: true, description: "One word for where the call is: Running, Needs approval, Done, Failed, Denied." },
+      { name: "Error line", required: false, description: "The failure message, under the row and always visible." },
+      { name: "Details", required: false, description: "Input and output as code, or a rendered result. A disclosure; the row is its trigger." }
+    ]
+  },
+  related: {
+    components: ["Message", "ThinkingOrb", "StreamingText", "CodeBlock", "Collapsible", "InlineStatus"]
+  },
+  props: [
+    { name: "name", type: "string", description: "The tool's own name, as the model called it (`search_docs`). Shown in mono." },
+    { name: "title", type: "ReactNode", description: "What the call does, in words a person reads. Leads the row; omit it and `name` leads." },
+    { name: "status", type: '"running" | "awaiting" | "complete" | "error" | "denied"', default: '"running"', description: "Where the call is. `awaiting` is held for the person's approval; `denied` is one they declined." },
+    { name: "statusLabel", type: "string", description: "Overrides the status word, for another language or a more specific phrase." },
+    { name: "input", type: "unknown", description: "The arguments. A string shows as is; anything else as formatted JSON." },
+    { name: "output", type: "unknown", description: "The result, shown the same way as `input`." },
+    { name: "error", type: "ReactNode", description: 'What went wrong, for `status="error"`. Always visible under the row.' },
+    { name: "children", type: "ReactNode", description: "A rendered result in place of `output`'s code view." },
+    { name: "defaultOpen", type: "boolean", default: "false", description: "Open the details on mount." },
+    { name: "open", type: "boolean", description: "Controlled open state of the details." },
+    { name: "onOpenChange", type: "(open: boolean) => void", description: "Called when the details open or close." }
+  ],
+  variants: {
+    status: ["running", "awaiting", "complete", "error", "denied"]
+  },
+  tokensUsed: ["card", "border", "destructive", "muted", "muted-foreground", "foreground", "tone-warning", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "It arrives as part of the assistant's turn, and the turn's own arrival covers it. A second entrance per call would make a busy turn twitch."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Header",
+      why: "The header is the disclosure trigger but reads as a status row. The hover step is what tells the person it opens."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-icon-swap",
+      part: "Status glyph",
+      why: "The spinner becoming a check or a warning is the moment the call settles, and it is the one change in the row worth catching from the corner of the eye. The swap reads as one mark replaced, not a flicker."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-disclosure",
+      part: "Details",
+      why: "The height change connects the code that appears to the row that was pressed, in a thread where several rows look alike."
+    },
+    {
+      slot: "activity",
+      recipe: "motion-spin",
+      part: "Status glyph",
+      why: "While the call runs, the spinner is what separates working from stuck. It pauses once the call settles, so a long thread of finished calls costs nothing."
+    }
+  ],
+  a11y: [
+    "With details, the header is a button with aria-expanded (Base UI Collapsible); its name is the title, the tool name and the status word, so it reads as one sentence.",
+    'A status change after mount is announced once through a polite role=status region ("Searched the docs: Done"). The status a call mounts with is not announced, so a thread restored from history stays quiet.',
+    "The glyph is aria-hidden: the status word beside it carries the meaning, so colour and shape are never the only signal."
+  ],
+  examples: [
+    {
+      label: "A finished call",
+      code: `<ToolCall
+	name="search_docs"
+	title="Searched the docs"
+	status="complete"
+	input={{ query: "date range picker" }}
+	output={{ hits: ["DatePicker", "Calendar", "DateTile"] }}
+/>`
+    },
+    {
+      label: "Running, then failed",
+      code: `<div className="flex flex-col gap-2">
+	<ToolCall name="read_file" title="Reading package.json" status="running" input={{ path: "package.json" }} />
+	<ToolCall
+		name="run_tests"
+		title="Ran the tests"
+		status="error"
+		error="3 of 412 tests failed in date-picker.test.tsx."
+		input={{ filter: "date-picker" }}
+	/>
+</div>`
+    },
+    {
+      label: "Waiting for approval",
+      code: `<ToolCall name="send_email" title="Send the invoice to Ada" status="awaiting" input={{ to: "ada@example.com", subject: "INV-1042" }} />`
+    }
+  ]
+};
+export {
+  toolCallMeta
+};

package/dist/components/tool-call/tool-call.variants.js

@@ -0,0 +1,33 @@
+// src/components/tool-call/tool-call.variants.ts
+import { cva } from "class-variance-authority";
+var toolCallVariants = cva(
+  "w-full overflow-hidden rounded-md border bg-card text-start",
+  {
+    variants: {
+      status: {
+        running: "border-border",
+        awaiting: "border-border",
+        complete: "border-border",
+        error: "border-destructive/40",
+        denied: "border-border"
+      }
+    },
+    defaultVariants: { status: "running" }
+  }
+);
+var toolCallHeaderVariants = cva(
+  "flex w-full min-w-0 items-center gap-2 px-3 py-2 text-start",
+  {
+    variants: {
+      interactive: {
+        true: "cursor-pointer motion-interactive sable-surface-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+        false: ""
+      }
+    },
+    defaultVariants: { interactive: false }
+  }
+);
+export {
+  toolCallHeaderVariants,
+  toolCallVariants
+};

package/dist/components/toolbar/toolbar.meta.js

@@ -43,7 +43,8 @@ var toolbarMeta = {
       },
       {
         guidance: "dont",
-        description: "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help."
+        description: "Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help.",
+        instead: ["Tabs", "SideNav", "Breadcrumbs"]
       },
       {
         guidance: "dont",

package/dist/components/tooltip/index.js

@@ -6,7 +6,8 @@ import {
   TooltipPortal,
   TooltipContent,
   TooltipArrow,
-  SimpleTooltip
+  SimpleTooltip,
+  TooltipGroup
 } from "./tooltip.js";
 import { tooltipMeta } from "./tooltip.meta.js";
 export {
@@ -14,6 +15,7 @@ export {
   Tooltip,
   TooltipArrow,
   TooltipContent,
+  TooltipGroup,
   TooltipPortal,
   TooltipProvider,
   TooltipTrigger,

package/dist/components/tooltip/tooltip.js

@@ -1,8 +1,10 @@
 // src/components/tooltip/tooltip.tsx
 import { Tooltip as Base } from "@base-ui/react/tooltip";
+import { createContext, useContext, useMemo, useState } from "react";
 import { cn } from "../../lib/cn.js";
 import { withPortalThemeScope } from "../../lib/portal-theme-scope.js";
 import { useAnchoredDensity } from "../../lib/density.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 var TooltipProvider = Base.Provider;
 var Tooltip = Base.Root;
@@ -58,16 +60,98 @@ function SimpleTooltip({
   sideOffset,
   ...root
 }) {
+  const group = useContext(TooltipGroupContext);
+  const payload = useMemo(
+    () => ({ content, side, align, sideOffset }),
+    [content, side, align, sideOffset]
+  );
+  if (group) {
+    return /* @__PURE__ */ jsx(Base.Trigger, { handle: group, payload, disabled: root.disabled, render: children });
+  }
   return /* @__PURE__ */ jsxs(Base.Root, { ...root, children: [
     /* @__PURE__ */ jsx(Base.Trigger, { render: children }),
     /* @__PURE__ */ jsx(TooltipContent, { side, align, sideOffset, children: content })
   ] });
 }
+var TooltipGroupContext = createContext(null);
+var GLIDE_DURATION = "calc(var(--motion-duration-slow) * var(--motion-expressive, 1))";
+var GROUP_POSITIONER = cn(
+  "z-(--z-overlay) h-(--positioner-height) w-(--positioner-width)",
+  "[&:has([data-transitioning])]:[transition-property:top,right,bottom,left]",
+  "[&:has([data-transitioning])]:[transition-duration:calc(var(--motion-duration-slow)*var(--motion-expressive,1))]",
+  "[&:has([data-transitioning])]:ease-emphasized"
+);
+function groupPopupStyle(state) {
+  if (state.transitionStatus === "starting") return void 0;
+  const closing = state.transitionStatus === "ending";
+  return {
+    transitionProperty: "opacity, scale, width, height",
+    transitionDuration: closing ? `var(--motion-duration-exit), var(--motion-duration-exit), ${GLIDE_DURATION}, ${GLIDE_DURATION}` : `var(--motion-duration-fast), var(--motion-duration-fast), ${GLIDE_DURATION}, ${GLIDE_DURATION}`,
+    transitionTimingFunction: closing ? "var(--motion-ease-standard), var(--motion-ease-standard), var(--motion-ease-emphasized), var(--motion-ease-emphasized)" : "var(--motion-ease-standard), var(--motion-ease-spring), var(--motion-ease-emphasized), var(--motion-ease-emphasized)"
+  };
+}
+var GROUP_VIEWPORT = cn(
+  "relative",
+  "[&>*]:[transition-property:opacity,translate]",
+  "[&>*]:[transition-duration:var(--motion-duration-fast),calc(var(--motion-duration-slow)*var(--motion-expressive,1))]",
+  "[&>*]:[transition-timing-function:var(--motion-ease-standard),var(--motion-ease-emphasized)]",
+  "[&>[data-previous]]:w-(--popup-width) [&>[data-previous]]:whitespace-nowrap",
+  "[&>[data-current][data-starting-style]]:opacity-0 [&>[data-previous][data-ending-style]]:opacity-0",
+  // Travelling right: the new label comes in from the right, the old leaves left.
+  "[&[data-activation-direction~=right]>[data-current][data-starting-style]]:translate-x-2",
+  "[&[data-activation-direction~=right]>[data-previous][data-ending-style]]:-translate-x-2",
+  "[&[data-activation-direction~=left]>[data-current][data-starting-style]]:-translate-x-2",
+  "[&[data-activation-direction~=left]>[data-previous][data-ending-style]]:translate-x-2",
+  "[&[data-activation-direction~=down]>[data-current][data-starting-style]]:translate-y-2",
+  "[&[data-activation-direction~=down]>[data-previous][data-ending-style]]:-translate-y-2",
+  "[&[data-activation-direction~=up]>[data-current][data-starting-style]]:-translate-y-2",
+  "[&[data-activation-direction~=up]>[data-previous][data-ending-style]]:translate-y-2"
+);
+function TooltipGroup({ children, motion }) {
+  const [handle] = useState(() => Base.createHandle());
+  return /* @__PURE__ */ jsxs(TooltipGroupContext.Provider, { value: handle, children: [
+    children,
+    /* @__PURE__ */ jsx(Base.Root, { handle, children: ({ payload }) => /* @__PURE__ */ jsx(TooltipGroupContent, { payload, motion }) })
+  ] });
+}
+TooltipGroup.displayName = "TooltipGroup";
+function TooltipGroupContent({
+  payload,
+  motion
+}) {
+  const anchoredDensity = useAnchoredDensity();
+  return /* @__PURE__ */ jsx(TooltipPortal, { children: /* @__PURE__ */ jsx(
+    Base.Positioner,
+    {
+      side: payload?.side ?? "top",
+      align: payload?.align ?? "center",
+      sideOffset: payload?.sideOffset ?? 6,
+      "data-motion": motionAttribute(motion),
+      className: GROUP_POSITIONER,
+      children: /* @__PURE__ */ jsx(
+        Base.Popup,
+        {
+          ...anchoredDensity,
+          style: groupPopupStyle,
+          className: cn(
+            "select-none rounded-sm border border-border-floating bg-popover px-2.5 py-1.5 text-label-md text-popover-foreground shadow-md outline-none",
+            "h-[var(--popup-height,auto)] w-[var(--popup-width,auto)] overflow-clip",
+            // The enter/exit targets and transform origin; the transition
+            // list itself is groupPopupStyle's.
+            "motion-pop"
+          ),
+          children: /* @__PURE__ */ jsx(Base.Viewport, { className: GROUP_VIEWPORT, children: payload?.content })
+        }
+      )
+    }
+  ) });
+}
 export {
   SimpleTooltip,
   Tooltip,
   TooltipArrow,
   TooltipContent,
+  TooltipGroup,
   TooltipPortal,
   TooltipProvider,
   TooltipTrigger

package/dist/components/tooltip/tooltip.meta.js

@@ -22,7 +22,8 @@ var tooltipMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not put critical instructions, errors, or interactive content inside Tooltip."
+        description: "Do not put critical instructions, errors, or interactive content inside Tooltip.",
+        instead: ["Popover", "InlineStatus"]
       },
       {
         guidance: "dont",
@@ -100,7 +101,12 @@ var tooltipMeta = {
     {
       name: "SimpleTooltip",
       type: "Base UI Tooltip.Root props + content: ReactNode + children: ReactElement + side | align | sideOffset",
-      description: "Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use."
+      description: "Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use. Inside a TooltipGroup it becomes a trigger of the group's shared tooltip instead."
+    },
+    {
+      name: "TooltipGroup",
+      type: '{ children: ReactNode; motion?: "full" | "subtle" | "off" }',
+      description: "One tooltip shared by every SimpleTooltip inside it \u2014 for a toolbar or a row of icon buttons. Moving the pointer along the row glides the tooltip to the next trigger and swaps its label (old fades out, new fades in, each sliding toward the direction of travel), instead of closing one tooltip and opening another a few pixels away. Renders no element. Each SimpleTooltip keeps its own content / side / align / sideOffset and `disabled`; root props such as open / onOpenChange belong to the shared tooltip and are ignored inside a group. `motion` turns it down: `subtle` jumps between triggers and only cross-fades the label. The composable Tooltip parts are unaffected."
     }
   ],
   tokensUsed: ["popover", "popover-foreground", "border-floating"],
@@ -128,6 +134,12 @@ var tooltipMeta = {
       recipe: "none",
       part: "Content",
       why: "Tooltip copy is resident before the tooltip opens. Anything that has to be fetched is a Popover with its own loading state."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "TooltipGroup",
+      why: "Moving between triggers in a group, the one tooltip glides to the next trigger, resizes to its label and cross-fades the text with a short slide toward the direction of travel. Separate tooltips would close here and open there, two surfaces blinking side by side; the glide says it is the same hint following the pointer. Base UI's handle + Viewport supply the shared popup and the previous/current content; the timing is the expressive glide (slow, emphasized), so `subtle` keeps only the cross-fade."
     }
   ],
   a11y: [
@@ -148,6 +160,10 @@ var tooltipMeta = {
     {
       label: "Shorthand (SimpleTooltip)",
       code: '<SimpleTooltip content="Saved to your workspace."><Button variant="ghost" size="icon-sm" aria-label="Info"><Icon name="info" /></Button></SimpleTooltip>'
+    },
+    {
+      label: "One tooltip gliding along a toolbar (TooltipGroup)",
+      code: '<TooltipGroup><Toolbar aria-label="Formatting"><SimpleTooltip content="Bold"><ToolbarButton size="icon-sm" aria-label="Bold"><Icon name="bold" /></ToolbarButton></SimpleTooltip><SimpleTooltip content="Italic"><ToolbarButton size="icon-sm" aria-label="Italic"><Icon name="italic" /></ToolbarButton></SimpleTooltip><SimpleTooltip content="Insert link"><ToolbarButton size="icon-sm" aria-label="Insert link"><Icon name="link" /></ToolbarButton></SimpleTooltip></Toolbar></TooltipGroup>'
     }
   ]
 };

package/dist/components/tree/tree.js

@@ -15,6 +15,7 @@ import {
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { hitTargetMin } from "../../lib/hit-target.js";
+import { motionAttribute, useMotionLevel } from "../../motion/MotionProvider.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function treeIndent(depth) {
   return `calc(var(--tree-rail) + var(--tree-indent) * ${Math.max(0, depth)})`;
@@ -43,8 +44,39 @@ function useTreeItem(idProp) {
     claimFocus: () => ctx?.setFocusedId(id)
   };
 }
+var ARRIVAL_CAP = 10;
+var ARRIVAL_STEP_MS = 18;
+function createArrival() {
+  const seen = /* @__PURE__ */ new Map();
+  return {
+    index(id) {
+      let at = seen.get(id);
+      if (at === void 0) {
+        at = seen.size;
+        seen.set(id, at);
+      }
+      return at;
+    }
+  };
+}
+var TreeArrivalContext = createContext(null);
+var TreeMotionContext = createContext(void 0);
+function arrivalProps(index) {
+  return {
+    className: "motion-arrive",
+    style: { "--motion-arrive-delay": `${Math.min(index, ARRIVAL_CAP) * ARRIVAL_STEP_MS}ms` }
+  };
+}
+function useArrival(id) {
+  const arrival = useContext(TreeArrivalContext);
+  const [props, setProps] = useState(() => arrival ? arrivalProps(arrival.index(id)) : {});
+  const onAnimationEnd = useCallback((event) => {
+    if (event.target === event.currentTarget && event.animationName === "sable-arrive") setProps({});
+  }, []);
+  return { ...props, onAnimationEnd };
+}
 var ITEM_FOCUS = "focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring";
-function Tree({ className, children, onKeyDown, ...props }) {
+function Tree({ className, children, onKeyDown, motion, ...props }) {
   const [focusedId, setFocusedId] = useState(null);
   const rootRef = useRef(null);
   const items = () => Array.from(rootRef.current?.querySelectorAll(ITEM) ?? []).filter(
@@ -120,17 +152,18 @@ function Tree({ className, children, onKeyDown, ...props }) {
         break;
     }
   };
-  return /* @__PURE__ */ jsx(TreeContext.Provider, { value: context, children: /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsx(TreeContext.Provider, { value: context, children: /* @__PURE__ */ jsx(TreeMotionContext.Provider, { value: motion, children: /* @__PURE__ */ jsx(
     "div",
     {
       ref: rootRef,
       role: "tree",
+      "data-motion": motionAttribute(motion),
       onKeyDown: handleKeyDown,
       className: cn("flex flex-col py-1", className),
       ...props,
       children
     }
-  ) });
+  ) }) });
 }
 Tree.displayName = "Tree";
 function TreeSection({ title, hint, action, className, children, ...props }) {
@@ -199,10 +232,26 @@ function TreeRow({
   };
   const item = useTreeItem(idProp);
   const nameId = useId();
+  const arrivalOwn = useArrival(item.id);
+  const inheritedArrival = useContext(TreeArrivalContext);
+  const motionLevel = useMotionLevel(useContext(TreeMotionContext));
+  const [seenExpanded, setSeenExpanded] = useState(expanded);
+  const [arrival, setArrival] = useState(null);
+  if (seenExpanded !== expanded) {
+    setSeenExpanded(expanded);
+    setArrival(expanded && subtree !== void 0 && motionLevel.expressive ? createArrival() : null);
+  }
+  useEffect(() => {
+    if (arrival) setArrival(null);
+  }, [arrival]);
   const row = /* @__PURE__ */ jsxs(
     "div",
     {
       ...props,
+      onAnimationEnd: (event) => {
+        arrivalOwn.onAnimationEnd(event);
+        props.onAnimationEnd?.(event);
+      },
       id: item.inTree ? item.id : idProp,
       "data-selected": selected || void 0,
       role: item.inTree ? "treeitem" : void 0,
@@ -217,9 +266,10 @@ function TreeRow({
         onFocus?.(event);
       },
       onClick: onClick ?? (expandable ? () => setExpanded(!expanded) : void 0),
-      style: { paddingInlineStart: treeIndent(depth), ...style },
+      style: { paddingInlineStart: treeIndent(depth), ...arrivalOwn.style, ...style },
       className: cn(
         "group relative flex h-(--control-xs) items-center gap-1.5 rounded-xs pe-1 motion-interactive",
+        arrivalOwn.className,
         selected ? "bg-panel-raised" : "hover:bg-panel-raised/60",
         item.inTree && ITEM_FOCUS,
         dimmed && "opacity-50",
@@ -253,6 +303,8 @@ function TreeRow({
               // The drawn box stays on --tree-column because that column is also
               // the indent step; a bigger button moves every name in the tree.
               hitTargetMin,
+              // motion-interactive lists `rotate` (what -rotate-90 writes), so the
+              // chevron turns with the rows arriving under it instead of snapping.
               "rounded-xs text-muted-foreground motion-interactive hover:text-foreground",
               !expanded && "-rotate-90"
             ),
@@ -268,7 +320,7 @@ function TreeRow({
   if (subtree === void 0) return row;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     row,
-    expanded ? /* @__PURE__ */ jsx(TreeDepthContext.Provider, { value: depth + 1, children: subtree }) : null
+    expanded ? /* @__PURE__ */ jsx(TreeDepthContext.Provider, { value: depth + 1, children: /* @__PURE__ */ jsx(TreeArrivalContext.Provider, { value: arrival ?? inheritedArrival, children: subtree }) }) : null
   ] });
 }
 TreeRow.displayName = "TreeRow";
@@ -283,6 +335,7 @@ function TreeEmpty({
 }) {
   const inheritedDepth = useContext(TreeDepthContext);
   const depth = depthProp ?? inheritedDepth;
+  const arrival = useArrival(useId());
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -290,9 +343,15 @@ function TreeEmpty({
       className: cn(
         "flex flex-col",
         dropTarget && "mx-2 my-1 gap-1 rounded-sm border border-dashed border-hairline-strong p-2",
+        arrival.className,
         className
       ),
       ...props,
+      onAnimationEnd: (event) => {
+        arrival.onAnimationEnd(event);
+        props.onAnimationEnd?.(event);
+      },
+      style: arrival.style ? { ...arrival.style, ...props.style } : props.style,
       children: [
         /* @__PURE__ */ jsx(
           "p",
@@ -325,11 +384,16 @@ function TreeAddRow({
   const inheritedDepth = useContext(TreeDepthContext);
   const depth = depthProp ?? inheritedDepth;
   const item = useTreeItem(idProp);
+  const arrival = useArrival(item.id);
   return /* @__PURE__ */ jsxs(
     "button",
     {
       type: "button",
       ...props,
+      onAnimationEnd: (event) => {
+        arrival.onAnimationEnd(event);
+        props.onAnimationEnd?.(event);
+      },
       id: item.inTree ? item.id : idProp,
       role: item.inTree ? "treeitem" : void 0,
       "aria-level": item.inTree ? depth + 1 : void 0,
@@ -338,9 +402,10 @@ function TreeAddRow({
         item.claimFocus();
         onFocus?.(event);
       },
-      style: { paddingInlineStart: treeIndent(depth), ...style },
+      style: { paddingInlineStart: treeIndent(depth), ...arrival.style, ...style },
       className: cn(
         "group flex h-(--control-xs) w-full items-center gap-1.5 rounded-xs pe-1 motion-interactive",
+        arrival.className,
         "text-ui-md text-muted-foreground hover:bg-panel-raised/60 hover:text-foreground",
         ITEM_FOCUS,
         className

package/dist/components/tree/tree.meta.js

@@ -167,6 +167,12 @@ var treeMeta = {
       name: "label",
       type: "ReactNode",
       description: "TreeAddRow's visible label. Name what gets added \u2014 'Add effect', not 'Add'."
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "On Tree. 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. Under `subtle` expanded rows appear at once instead of unfolding; the chevron still turns."
     }
   ],
   subcomponents: [
@@ -208,6 +214,32 @@ var treeMeta = {
     "Right-rail controls that appear on hover must also appear on focus-visible, or they are unreachable by keyboard."
   ],
   tokensUsed: ["panel-raised", "hairline", "foreground", "muted-foreground", "primary", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "motion-arrive",
+      part: "TreeRow",
+      why: "Rows a user's expand reveals fade down into place in document order (a capped 18ms stagger), so the eye can follow where the children came from. An animation (motion-arrive) rather than a transition, because the rows already wear motion-interactive and a second transition list would fight it. Only on a user expand of a `subtree` \u2014 a tree that mounts open shows its rows at once, and rows added later to an open folder do not cascade. Expressive: `subtle` shows them at once."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "TreeRow",
+      why: "Hover and selection fills ease, so sweeping the pointer down a dense panel reads as a highlight following it rather than rows flickering."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Disclosure",
+      why: "The chevron turns with the rows arriving under it; motion-interactive lists `rotate`, which is what -rotate-90 writes, so it no longer flips in one frame."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Tree",
+      why: "A tree has no indeterminate state of its own; a branch that loads its children should render a TreeEmpty or a loading row inside it."
+    }
+  ],
   examples: [
     {
       label: "File tree",

package/dist/components/video/video.meta.js

@@ -57,6 +57,38 @@ var videoMeta = {
     }
   ],
   tokensUsed: ["border", "overlay", "overlay-foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The frame arrives with its page. Once there is a source, the poster and controls are the browser's."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Play button",
+      why: "With `onRequestPlay`, the play disc firms its scrim on hover, eased, so the mark reads as pressable over any image."
+    },
+    {
+      slot: "response",
+      recipe: "motion-press",
+      part: "Play button",
+      why: "Loading a source can take a moment; the settle on press confirms the tap before the player appears."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Root",
+      why: "Placeholder to player is a swap of elements: the native video mounts where the poster was. Animating the swap would delay the playback the person just asked for."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Buffering belongs to the native controls, which draw their own indicator. A second loader over the frame would compete with the browser's."
+    }
+  ],
   a11y: [
     "Mounts a native <video> element, preserving built-in keyboard controls when controls is enabled.",
     'Without onRequestPlay the placeholder play mark is decorative (aria-hidden) \u2014 nothing on the frame pretends to be pressable. With it, the mark is a native button named "Play video".'