@sableui/react 0.13.1 → 0.14.0

package/dist/components/bar-chart/bar-chart.meta.js

@@ -117,11 +117,18 @@ var barChartMeta = {
       default: "false for columns; true for horizontal bars",
       description: "The vertical axis."
     },
+    {
+      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 arrival (bars rising in sequence) and the data-change morph are the flourish; the hover dim and gliding cursor are the feedback `subtle` keeps."
+    },
     {
       name: "animate",
       type: "boolean",
       default: "true",
-      description: "Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart."
+      description: 'Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. `animate={false}` is `motion="subtle"`.',
+      deprecated: 'motion="subtle" (what animate={false} now maps to: no arrival, hover kept) or motion="off"'
     },
     {
       name: "activeIndex",
@@ -199,19 +206,19 @@ var barChartMeta = {
       slot: "arrival",
       recipe: "custom",
       part: "Bar",
-      why: "Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart."
+      why: 'Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart. The arrival is expressive: it plays at the full motion level only, so `motion="subtle"` (or a subtle app policy) shows the finished chart while hover feedback stays.'
     },
     {
       slot: "response",
       recipe: "none",
       part: "Cursor + tooltip",
-      why: "The hovered category gets a band behind it and the other bars dim at once \u2014 a lagging highlight reads as a slow chart."
+      why: "The hovered category gets a band behind it and the other bars dim at once \u2014 a lagging highlight reads as a slow chart. The dim mixes each bar toward the surface instead of fading it, so gridlines never strike through a dimmed column and stacked segments stay solid. Essential: `subtle` keeps it."
     },
     {
       slot: "transition",
       recipe: "custom",
       part: "Bar",
-      why: "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place."
+      why: "Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place. Expressive, like the arrival: under `subtle` new data swaps in place."
     },
     {
       slot: "activity",

package/dist/components/bottom-nav/bottom-nav.js

@@ -38,8 +38,10 @@ function BottomNavItem({
       "data-active": active ? "" : void 0,
       "aria-current": active ? "page" : void 0,
       className: cn(
+        // motion-press: on a phone there is no hover to say the tap landed, and
+        // a route change can take a beat to paint — the settle is the receipt.
         // design-lint-disable-next-line raw-control-height -- the WCAG 2.5.5 touch-target floor, deliberately density-independent: a compact register still owes a 44px hit area.
-        "relative flex min-h-[44px] min-w-[44px] flex-col items-center justify-center gap-0.5 rounded-lg text-muted-foreground motion-interactive hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[active]:text-foreground",
+        "relative flex min-h-[44px] min-w-[44px] flex-col items-center justify-center gap-0.5 rounded-lg text-muted-foreground motion-interactive motion-press hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[active]:text-foreground",
         className
       ),
       children: /* @__PURE__ */ jsxs(Fragment, { children: [

package/dist/components/bottom-nav/bottom-nav.meta.js

@@ -57,6 +57,38 @@ var bottomNavMeta = {
       description: 'A single tab, placed as a child of BottomNav. `label` is the accessible name (aria-label) and optional visible label; `icon` is the glyph node (consumer swaps fill weight for the active state); `active` marks the current route (active ink + aria-current); `badge` overlays a corner dot/count on the icon; `showLabel` shows the label text beneath the icon \u2014 defaults to false (icon-only); turn it on when the icons alone are not self-evident; `render` renders as another element, e.g. render={<Link to="/x" />}.'
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Fixed app chrome, present from the first paint of every screen. Animating it in on navigation would make each route change look like the app restarting."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "BottomNavItem",
+      why: "The ink steps up on hover and the focus ring eases in, so a pointer or a keyboard on a tablet gets the same answer as every other control in the app."
+    },
+    {
+      slot: "response",
+      recipe: "motion-press",
+      part: "BottomNavItem",
+      why: "On a phone there is no hover to say a tap landed, and a route can take a beat to paint. The settle on press is the receipt; without it people tap the tab a second time."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "BottomNavItem",
+      why: "Changing tab eases the active ink out of one item and into the next. It is a cross-fade, not a travelling indicator: each item owns its colour, so there is no single mark to glide."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Navigation has no working state of its own. A slow route shows its pending state in the page it is loading, not in the tab bar."
+    }
+  ],
   a11y: [
     "BottomNav renders a <nav> landmark.",
     "Each tab is a 44px minimum touch target with an aria-label.",

package/dist/components/breadcrumbs/breadcrumbs.meta.js

@@ -89,6 +89,32 @@ var breadcrumbsMeta = {
     }
   ],
   tokensUsed: ["muted-foreground", "foreground"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The trail is page furniture, rendered with the page header. An entrance would replay on every navigation, which is exactly when the reader looks at it to get their bearings."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "BreadcrumbLink",
+      why: "Ancestors are muted until hovered or focused. Easing the ink makes the trail read as links answering the pointer; a hard snap across a row of small text looks like flicker."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Root",
+      why: "A breadcrumb has no state of its own. The current page changes by navigation, which replaces the trail; animating between two trails would imply the path itself moved."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "It never works in the background. A route that is still loading says so in the page, not in its address."
+    }
+  ],
   a11y: [
     'The <nav> carries aria-label="Breadcrumb" so assistive tech announces the landmark.',
     "Crumbs sit in an ordered list (<ol>) to convey hierarchy and position.",

package/dist/components/button/button.js

@@ -21,6 +21,7 @@ var BLEED_CLASS = {
   end: "-me-(--button-pe,var(--button-px))",
   both: "-ms-(--button-ps,var(--button-px)) -me-(--button-pe,var(--button-px))"
 };
+var LABEL_FADE = "[&>.sable-label-trim]:transition-opacity [&>.sable-label-trim]:duration-(--motion-duration-fast) [&>.sable-label-trim]:ease-standard";
 function Button({
   variant,
   size,
@@ -71,12 +72,19 @@ function Button({
   const stacked = useContext(StackedActionsContext) && !String(size ?? "md").startsWith("icon");
   const resolvedSize = stacked ? "cta" : size ?? "md";
   const hasLabel = children != null && children !== false;
-  const spinner = /* @__PURE__ */ jsx(Spinner, { className: "size-(--button-icon)", thickness: 2 });
-  const start = busy ? spinner : iconStart;
   const iconOnly = String(resolvedSize).startsWith("icon");
+  const overlay = busy && !iconOnly && hasLabel && iconStart == null && loadingLabel == null && badge == null;
+  const spinner = /* @__PURE__ */ jsx(
+    Spinner,
+    {
+      className: cn("size-(--button-icon) motion-appear", overlay && "absolute inset-0 m-auto"),
+      thickness: 2
+    }
+  );
+  const start = busy ? spinner : iconStart;
   const inner = busy && iconOnly ? spinner : /* @__PURE__ */ jsxs(Fragment, { children: [
     start,
-    trimLabel(busy ? loadingLabel ?? children : children),
+    trimLabel(busy && !overlay ? loadingLabel ?? children : children),
     iconEnd
   ] });
   const content = badge != null ? /* @__PURE__ */ jsxs("span", { "data-slot": "button-badge-anchor", className: "relative inline-flex items-center gap-(--control-gap)", children: [
@@ -84,7 +92,9 @@ function Button({
     /* @__PURE__ */ jsx("span", { className: "pointer-events-none absolute -end-1 -top-1 flex", children: badge })
   ] }) : inner;
   const optical = cn(
-    start && hasLabel && !iconOnly ? OPTICAL_START : null,
+    // An overlaid spinner is not a leading glyph: trimming the padding for it
+    // changed the width by 2px, the exact shift the overlay exists to avoid.
+    start && hasLabel && !iconOnly && !overlay ? OPTICAL_START : null,
     iconEnd && hasLabel && !iconOnly ? OPTICAL_END : null
   );
   const bleedable = BORDERLESS.has(variant ?? "primary") && !stacked;
@@ -104,6 +114,13 @@ function Button({
         // double-fire, but fading it to 50% made a working button read as an
         // unavailable one. It keeps full colour; the spinner says "working".
         busy ? "cursor-progress disabled:opacity-100 aria-disabled:opacity-100" : null,
+        // The label hands over to the spinner laid on top of it (see
+        // `overlay`). Its fade is declared at rest too, so the label also
+        // fades BACK when the work settles instead of snapping in. Only the
+        // trimLabel span is targeted: a caller's icon may carry a transition
+        // of its own (a chevron's rotate) that a child selector would clobber.
+        LABEL_FADE,
+        overlay ? "relative [&>:not([role=status])]:opacity-0" : null,
         className
       ),
       children: content,

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

@@ -33,7 +33,7 @@ var buttonMeta = {
       },
       {
         guidance: "do",
-        description: "For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click."
+        description: 'For a copy control, pair an icon Button with `useCopy(text, { timeout? })`. It takes the text when the hook is called and returns `{ copy, copied }`; `copy()` takes no argument, so pass the value the button copies to the hook, not to `copy`. Text that costs something to produce (a file to fetch) goes in as a function, `useCopy(() => fetch(url).then((r) => r.text()))`, called only on click. Keep both glyphs mounted in a `motion-icon-swap` cell so the copy mark visibly becomes a check (a `copied ? "check" : "copy"` swap snaps between frames and is easy to miss), and say "Copied" in a polite `role="status"` region: the glyph change is silent to a screen reader.'
       },
       {
         guidance: "do",
@@ -126,7 +126,7 @@ var buttonMeta = {
       name: "loading",
       type: "boolean",
       default: "false",
-      description: "Show a leading Spinner while an action is in flight and refuse presses. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
+      description: "Show a Spinner while an action is in flight and refuse presses. The spinner takes the iconStart slot when there is one; otherwise it lays over the label, which fades out in place, so the button keeps its width. Sets aria-busy and aria-disabled, never the native disabled: disabling the focused button sent focus to <body>, so a sheet the action opened had nowhere to return it."
     },
     {
       name: "onClick",
@@ -141,7 +141,7 @@ var buttonMeta = {
     {
       name: "loadingLabel",
       type: "ReactNode",
-      description: "Optional text shown in place of children while loading."
+      description: "Optional text shown in place of children while loading, with the spinner beside it. The width follows the new text, so prefer no loadingLabel where the row must not move."
     },
     {
       name: "iconStart",
@@ -211,9 +211,9 @@ var buttonMeta = {
     },
     {
       slot: "transition",
-      recipe: "none",
-      part: "Root",
-      why: "A button has no state of its own to move between. A control that toggles is a Switch or a Toggle, and those carry the transition."
+      recipe: "motion-appear",
+      part: "Spinner",
+      why: "Going busy is the one state change a button has. The spinner fades in where it mounts \u2014 in the icon slot, or laid over a plain label that fades out beneath it and keeps its place \u2014 so the width never changes and the row does not shift under the pointer that just pressed it. The label fades back when the work settles. A toggling control is a Switch or a Toggle; those carry their own transition."
     },
     {
       slot: "activity",
@@ -247,7 +247,7 @@ var buttonMeta = {
     },
     {
       label: "Copy to clipboard",
-      code: 'const { copy, copied } = useCopy(address)\n<Button variant="ghost" size="icon-sm" aria-label="Copy address" onClick={copy}><Icon name={copied ? "check" : "copy"} /></Button>'
+      code: 'const { copy, copied } = useCopy(address)\n<Row gap={1}><Button variant="ghost" size="icon-sm" aria-label="Copy address" onClick={copy}><span aria-hidden="true" className="motion-icon-swap"><span data-active={!copied} className="inline-flex"><Icon name="copy" /></span><span data-active={copied} className="inline-flex"><Icon name="check" /></span></span></Button><span role="status" className="sr-only">{copied ? "Copied" : ""}</span></Row>'
     },
     {
       label: "As link",

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

@@ -25,7 +25,8 @@ var buttonGroupMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state."
+        description: "Do not use it for a selection that stays on. That is ToggleGroup, which carries the pressed state.",
+        instead: ["ToggleGroup"]
       }
     ]
   },

package/dist/components/calendar/calendar.js

@@ -3,6 +3,7 @@
 // src/components/calendar/calendar.tsx
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
+import { motionAttribute, useMotionLevel } from "../../motion/MotionProvider.js";
 import { buttonVariants } from "../button/button.variants.js";
 import {
   DayPicker
@@ -23,13 +24,18 @@ function Calendar({
   showOutsideDays = true,
   components,
   bare = false,
+  motion,
+  animate,
   ...props
 }) {
+  const level = useMotionLevel(motion);
   return /* @__PURE__ */ jsx(
     DayPicker,
     {
       "data-slot": "calendar",
+      "data-motion": motionAttribute(motion),
       showOutsideDays,
+      animate: animate ?? level.expressive,
       className: cn(
         // relative: the nav is absolutely positioned (react-day-picker v9
         // renders it inside `months`, not inside each month), and with no
@@ -53,7 +59,10 @@ function Calendar({
         weekdays: "flex",
         weekday: "flex size-9 items-center justify-center text-caption text-muted-foreground",
         week: "mt-1 flex w-full",
-        day: "p-0 text-center",
+        // motion-interactive on the cell too: a range's fill is painted on the
+        // cells (see range_* below), so without it the band between the
+        // endpoints snapped while the endpoint buttons eased.
+        day: "p-0 text-center motion-interactive",
         day_button: "inline-flex size-9 items-center justify-center rounded-md text-body-sm motion-interactive outline-none hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring",
         // Range fill lives on the CELL so it forms one continuous bar; only the
         // outer ends are rounded. The selected (primary) endpoint buttons sit on
@@ -76,6 +85,14 @@ function Calendar({
         outside: "[&>button]:text-muted-foreground",
         disabled: "[&>button]:pointer-events-none [&>button]:text-muted-foreground [&>button]:opacity-50",
         hidden: "invisible",
+        weeks_after_enter: "sable-month-enter-after",
+        weeks_before_enter: "sable-month-enter-before",
+        weeks_after_exit: "sable-month-exit-after",
+        weeks_before_exit: "sable-month-exit-before",
+        caption_after_enter: "sable-caption-enter",
+        caption_before_enter: "sable-caption-enter",
+        caption_after_exit: "sable-caption-exit",
+        caption_before_exit: "sable-caption-exit",
         ...classNames
       },
       components: { Chevron: CalendarChevron, ...components },

package/dist/components/calendar/calendar.meta.js

@@ -84,6 +84,12 @@ var calendarMeta = {
       default: "false",
       description: "Drop the card frame (border, fill, padding) so the grid sits flush inside a surface that already has one, such as a Popover. DatePicker renders its Calendar this way."
     },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the month slide, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting."
+    },
     {
       name: "className",
       type: "string",
@@ -114,6 +120,38 @@ var calendarMeta = {
     "muted-foreground",
     "ring"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Inline, it arrives with its form; in a DatePicker the Popover carries the entrance. A grid that animated in by itself would put a second motion on the same opening."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Day",
+      why: "Days ease their hover wash, and the month arrows are ghost Buttons on Button's own recipe. Across a seven-column grid the pointer crosses many cells at once, and an eased wash reads as a cursor travelling rather than a grid flashing."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Day",
+      why: "Picking a day eases the primary fill onto it and off the previous one, so a click reads as the selection moving rather than two cells flipping. A range's band is painted on the cells, which carry the same recipe, so the band eases along with its endpoints as the range grows."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Days are resident data; nothing in the grid loads. Availability fetched per month belongs to the surface around the calendar."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Month",
+      why: "Paging months slides the outgoing grid toward the edge it is leaving by and brings the new one in from the other, over a short travel with a fade (react-day-picker's `animate` mode on Sable keyframes in styles.css), so forward and back read as direction rather than a grid swapping in one frame. RDP adds a single class per part, which a recipe utility cannot be; mirrored in RTL. Expressive: Calendar turns `animate` on only at full motion, and an explicit `animate` prop still wins."
+    }
+  ],
   a11y: [
     "react-day-picker manages the roving-tabindex grid, arrow-key navigation, and ARIA roles/labels for the calendar.",
     "Selected days use bg-primary/text-primary-foreground for AA contrast; today is marked with a dot under the number (not a ring, which is reserved for keyboard focus) rather than color alone.",

package/dist/components/carousel/carousel.js

@@ -14,7 +14,7 @@ import { Icon } from "../../icon/Icon.js";
 import { cn } from "../../lib/cn.js";
 import { PlayPauseGlyph } from "../../lib/glyphs.js";
 import { useResizeObserver } from "../../lib/use-resize-observer.js";
-import { useMotion } from "../../motion/MotionProvider.js";
+import { useMotionLevel } from "../../motion/MotionProvider.js";
 import { Button } from "../button/button.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var CAROUSEL_BREAKPOINTS = [
@@ -92,9 +92,10 @@ function Carousel({
   label,
   className,
   slideClassName,
-  arrowClassName
+  arrowClassName,
+  motion
 }) {
-  const { enabled } = useMotion();
+  const { enabled, attribute: motionAttr } = useMotionLevel(motion);
   const slides = Children.toArray(children);
   const count = slides.length;
   const perView = Math.min(
@@ -278,6 +279,7 @@ function Carousel({
     {
       "aria-roledescription": "carousel",
       "aria-label": label ?? "Slides",
+      "data-motion": motionAttr,
       className: cn("relative flex flex-col", className),
       onMouseEnter: () => setHovered(true),
       onMouseLeave: () => setHovered(false),
@@ -401,7 +403,7 @@ function Carousel({
                       {
                         "aria-hidden": true,
                         className: cn(
-                          "h-1.5 rounded-full motion-interactive",
+                          "h-1.5 rounded-full motion-glide",
                           i === logical ? "w-4 bg-foreground" : "w-1.5 bg-muted-foreground/40 group-hover/dot:bg-muted-foreground/70"
                         )
                       }

package/dist/components/carousel/carousel.meta.js

@@ -60,6 +60,12 @@ var carouselMeta = {
       name: "arrowClassName",
       type: "string",
       description: "Class for both prev/next arrow buttons. Merged through cn(), so a radius or shadow utility replaces the default rounded-full shadow-md rather than stacking with it."
+    },
+    {
+      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 glide, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting. Under subtle the slides still travel and the active dot snaps; off also cuts between slides and pauses autoplay."
     }
   ],
   tokensUsed: [
@@ -70,6 +76,38 @@ var carouselMeta = {
     "foreground",
     "muted-foreground"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "A carousel arrives with its section. Its content already moves on every advance; an entrance on top would make the first view feel like an advance nobody asked for."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Dot",
+      why: "The dot's 24px hit area eases its focus ring and the dot brightens under the pointer, which is how a 6px mark tells you it is a button."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Track",
+      why: `The slide track's translate is set inline from the measured slide pitch, on --motion-duration-slow and the emphasized easing, and switched off during a drag so the track follows the finger. A recipe cannot carry a measured, drag-interrupted offset. Essential: it is the answer to "next", so it plays under subtle.`
+    },
+    {
+      slot: "transition",
+      recipe: "motion-glide",
+      part: "Dot",
+      why: 'The active dot stretches to a bar while the one it left shrinks, on one timeline, so the row keeps its length and the mark reads as travelling with the slide. It used to change width unanimated and jumped while the slides beside it glided. Expressive: motion="subtle" snaps it.'
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Autoplay's progress is the slides themselves advancing and the play/pause control; a separate timer animation would put a second clock beside the first."
+    }
+  ],
   a11y: [
     "Region carries aria-roledescription='carousel'; each slide is a group with aria-roledescription='slide' and an 'N of M' label; clones are aria-hidden.",
     "Arrows and dots are real buttons (dots set aria-current); Left/Right arrow keys navigate when the viewport is focused.",
@@ -92,6 +130,10 @@ var carouselMeta = {
     {
       label: "Autoplay",
       code: "<Carousel loop autoplay={4000} counter>{slides}</Carousel>"
+    },
+    {
+      label: "Subtle motion",
+      code: '<Carousel loop motion="subtle" label="Gallery">{slides}</Carousel>'
     }
   ]
 };

package/dist/components/chat-composer/chat-composer.js

@@ -6,9 +6,11 @@ import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { useTypeTier } from "../../lib/density.js";
 import { setRef } from "../../lib/refs.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
 import { Button } from "../button/index.js";
 import { Textarea } from "../textarea/index.js";
 import { chatComposerVariants } from "./chat-composer.variants.js";
+import { useEasedGrowth } from "./use-eased-growth.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 function ChatComposer({
   value,
@@ -31,6 +33,7 @@ function ChatComposer({
   stopLabel = "Stop generating",
   footer,
   fieldRef,
+  motion,
   className,
   children,
   ...props
@@ -82,9 +85,11 @@ function ChatComposer({
     [send, mode]
   );
   const showStop = busy && Boolean(onStop);
+  useEasedGrowth(field, text);
   return /* @__PURE__ */ jsxs(
     "form",
     {
+      "data-motion": motionAttribute(motion),
       onSubmit: handleSubmit,
       className: cn(chatComposerVariants({ invalid }), className),
       ...props,
@@ -120,6 +125,9 @@ function ChatComposer({
               // Inline padding puts the text on the attach glyph's edge: an
               // icon-sm button centres a 1.125rem glyph in --control-sm.
               "min-h-0 max-h-40 resize-none border-0 bg-transparent px-[calc((var(--control-sm)-1.125rem)/2)] py-1 focus-visible:ring-0",
+              // Past the cap the field scrolls; the platform bar (stepper arrows on
+              // Windows) would poke into the composer's rounded corner.
+              "scrollbar-quiet",
               // What you type has to match what it becomes: the field and the
               // Bubble it turns into both read `prose`, so the message does not
               // change size the moment it is sent.
@@ -143,33 +151,25 @@ function ChatComposer({
           leading,
           /* @__PURE__ */ jsx("div", { className: "flex-1" }),
           actions,
-          showStop ? /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx(
             Button,
             {
-              type: "button",
-              variant: "secondary",
+              type: showStop ? "button" : "submit",
+              variant: showStop ? "secondary" : "primary",
               size: "icon-sm",
-              "aria-label": stopLabel,
-              onClick: () => {
+              "aria-label": showStop ? stopLabel : sendLabel,
+              disabled: showStop ? false : !canSend,
+              loading: !showStop && busy,
+              onClick: showStop ? (event) => {
+                event.preventDefault();
                 onStop?.();
                 if (!coarse) field.current?.focus();
-              },
-              children: /* @__PURE__ */ jsx(Icon, { name: "stop", variant: "solid", className: "text-[0.75em]" })
+              } : void 0,
+              children: /* @__PURE__ */ jsxs("span", { "aria-hidden": "true", className: "motion-icon-swap", children: [
+                /* @__PURE__ */ jsx("span", { "data-active": !showStop, className: "inline-flex", children: /* @__PURE__ */ jsx(Icon, { name: "arrow-up" }) }),
+                /* @__PURE__ */ jsx("span", { "data-active": showStop, className: "inline-flex", children: /* @__PURE__ */ jsx(Icon, { name: "stop", variant: "solid", className: "text-[0.75em]" }) })
+              ] })
             }
-          ) : (
-            // Busy without a stop handler: Button's own `loading` swaps the glyph
-            // for its Spinner and keeps full colour, rather than a hand-spun icon.
-            /* @__PURE__ */ jsx(
-              Button,
-              {
-                type: "submit",
-                size: "icon-sm",
-                "aria-label": sendLabel,
-                disabled: !canSend,
-                loading: busy,
-                children: /* @__PURE__ */ jsx(Icon, { name: "arrow-up" })
-              }
-            )
           )
         ] }),
         footerContent ? /* @__PURE__ */ jsx("p", { className: cn("px-[calc((var(--control-sm)-1.125rem)/2)] text-muted-foreground", tier.secondary), children: footerContent }) : null,

package/dist/components/chat-composer/chat-composer.meta.js

@@ -209,6 +209,12 @@ var chatComposerMeta = {
       type: "Ref<HTMLTextAreaElement>",
       description: "Ref to the underlying textarea \u2014 for focusing after a send, or on mount, and the extension point for anything that listens to the field. Pass `useCaretTrigger`'s `fieldRef` here for mentions and slash commands (CaretMenu). An Enter another listener already handled (`preventDefault()`) does not send."
     },
+    {
+      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. Under `subtle` the field snaps to its new height and the send/stop glyphs swap without the morph."
+    },
     {
       name: "...form props",
       type: 'Omit<ComponentPropsWithRef<"form">, "onSubmit" | "defaultValue">',
@@ -230,6 +236,38 @@ var chatComposerMeta = {
     "accent",
     "accent-foreground"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The composer is the fixed foot of a thread, there before anything else is. An entrance would only delay the first keystroke."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "The surface's focus ring and invalid border ease in, so focusing the field reads as the whole box waking up rather than a frame flicker."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Field",
+      why: "As a line breaks or a paste lands, the field eases to its new height (up to its cap) instead of jumping, so the transcript above is visibly pushed rather than teleported. `field-sizing` alone cannot ease \u2014 its height stays `auto` \u2014 so a small hook measures and pins a pixel height. Expressive and short (`fast`): the text itself lands at once, and `subtle` snaps the box."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-icon-swap",
+      part: "Send button",
+      why: "Send turning into stop is the moment a reply starts, and stop turning back is the moment it is over. One button changes role in place \u2014 the fill eases, the arrow collapses into the square \u2014 so it reads as the same control changing what it does, not a different button appearing under the cursor."
+    },
+    {
+      slot: "activity",
+      recipe: "motion-spin",
+      part: "Send button",
+      why: "Busy with no stop handler, Button's own loading Spinner replaces the arrow, so a send in flight is not mistaken for a disabled one."
+    }
+  ],
   a11y: [
     "A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.",
     "Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.",