@sableui/react 0.13.2 → 0.14.0

package/AGENTS.md

@@ -42,7 +42,7 @@ These are short on purpose. Each links to a foundations doc with the full vocabu
 3. **Space on the 4px scale, by role.** Inset, stack, inline; related things closer than unrelated things. No off-scale `p-[15px]`. Padding, gaps and insets stay on the scale (a step, or `--spacing(n)` inside an arbitrary value) so the density control moves them; fixed `rem`/`px` only for what must not scale, like a hairline. Single-column content in a card is a flex column, not a grid. → `sable docs spacing`
 4. **Controls read the ladder.** Heights come from `--control-*`, so `<Density>` can retune a region at once. Never `h-[40px]`. → `sable docs spacing`
 5. **Shape and depth are roles.** Radii from the `rounded-*` ladder, concentric when nested (inner = outer − inset; `rounded-concentric-*`, `sable-frame-inner`); elevation by transience (resting → raised → overlay → modal → toast), one shadow per surface. → `sable docs shape` · `sable docs surfaces`
-6. **Motion has a reason and a recipe.** Apply a named `motion-*` recipe; drop to `duration-(--motion-duration-*)` + `ease-*` tokens only when none fits. Never Tailwind's `animate-*`, never a raw `duration-150`. Exits are faster than entrances and never overshoot. → `sable docs motion`
+6. **Motion has a reason and a recipe.** Apply a named `motion-*` recipe; drop to `duration-(--motion-duration-*)` + `ease-*` tokens only when none fits. Never Tailwind's `animate-*`, never a raw `duration-150`. Exits are faster than entrances and never overshoot. Components ship their craft (gliding indicators, rolling numbers, drawn ticks) on by default; to calm a dense view use `motion="subtle"` on the component or `<MotionScope level="subtle">` around a region, never a CSS override. → `sable docs motion`
 7. **Icons by semantic name.** `<Icon name="check" />`; size with `text-{size}`, never type utilities. A mark attached to a line of type (dot, bullet, leading icon) sits in an `h-[1lh] items-center` box and is sized in em, never nudged with px. → `sable docs typography`
 8. **Every scroll container declares a policy:** `scrollbar-quiet` (vertical) or `scrollbar-hidden` (horizontal, with an edge fade carrying the affordance).
 9. **Accessible by construction.** WCAG AA contrast (and a label on a brand or status fill also clears APCA Lc 60 — `label-contrast`), 44px hit areas, visible focus, logical properties, live regions that exist before they speak. → `sable docs accessibility`
@@ -65,7 +65,7 @@ The machine-readable version of this section is the `consume` block in `registry
 
    `styles.css` carries **Sable only** — the default theme, and the layout floor every other theme inherits (`--page-inset`, `--region-*`, `--rhythm-unit` on a bare `:root`). The bundled **alternates are opt-in**, because they are `[data-sable-theme]`-scoped and an app that never sets the attribute ships CSS that can never match: 5.5 KB gzip of permanently-dead weight, which is exactly how a real app's build audit found this. Using one? `@import "@sableui/react/theme/prism.css";`. Offering the whole set through a `<ThemeSelector>`? `@import "@sableui/react/themes.css";`. **Symptom of forgetting:** `data-sable-theme` is set, nothing matches, and the page silently renders as the Sable theme — no error, just the wrong theme.
 4. **Fonts:** load Figtree (sans) + DM Mono (mono) — the theme declares the stacks, the host provides the files. Apply `antialiased` (`-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale`) **once on the app root**: Sable's type scale was drawn against smoothed text, and without it macOS renders every weight heavier than designed. The package deliberately doesn't set it — a library has no business styling the host's whole page — so it has to happen here.
-5. **Providers:** `<IconProvider>` is **required** — wrap the app once in `<IconProvider set={reiconIconSet}>` with `import { reiconIconSet } from "@sableui/react/icons/reicon"` (without it every `<Icon>` renders nothing; development builds warn once). Pass another icon package's set instead to replace Reicon, or extend it using `composeIconSets(appExtras, reiconIconSet)` (list the added names in `.sable/icons.json` as `{ "names": [...] }` so `sable grade` accepts them); `<MotionProvider>` is optional too. Use `<SableThemeProvider>` + `useSableTheme()` when the app should expose user-selectable themes; pair `themeId` / `setThemeId` with `<ThemeSelector>` and `preference` / `setPreference` with `<ThemeSwitcher>`. The provider stores `light` / `dark` / `system`, toggles the `dark` class on `<html>`, stores the active design theme, and writes `data-sable-theme` for non-default themes. Apps with their own state layer can call `applySableColorMode()` / `applySableTheme()` instead. You only need a Tailwind `@custom-variant dark` if **your** app code uses `dark:` utilities (Sable ships none).
+5. **Providers:** `<IconProvider>` is **required** — wrap the app once in `<IconProvider set={reiconIconSet}>` with `import { reiconIconSet } from "@sableui/react/icons/reicon"` (without it every `<Icon>` renders nothing; development builds warn once). Pass another icon package's set instead to replace Reicon, or extend it using `composeIconSets(appExtras, reiconIconSet)` (list the added names in `.sable/icons.json` as `{ "names": [...] }` so `sable grade` accepts them); `<MotionProvider>` is optional too (`policy="subtle"` keeps feedback and drops flourishes app-wide). Use `<SableThemeProvider>` + `useSableTheme()` when the app should expose user-selectable themes; pair `themeId` / `setThemeId` with `<ThemeSelector>` and `preference` / `setPreference` with `<ThemeSwitcher>`. The provider stores `light` / `dark` / `system`, toggles the `dark` class on `<html>`, stores the active design theme, and writes `data-sable-theme` for non-default themes. Apps with their own state layer can call `applySableColorMode()` / `applySableTheme()` instead. You only need a Tailwind `@custom-variant dark` if **your** app code uses `dark:` utilities (Sable ships none).
 6. Import from the root barrel: `import { Button } from "@sableui/react"`. Page shells live on the `patterns` subpath (`import { SettingsPage } from "@sableui/react/patterns"`) — preview one, then copy its source from `registry.json → patterns` when the route needs to diverge. Blocks — section-sized compositions such as a sign-in card or a pricing card — live on the `blocks` subpath (`import { SignInBlock } from "@sableui/react/blocks"`) and ship the same way (`registry.json → blocks`); copy one and edit its content constants. A block's props are only `className`, `framed` and its primary action's callback, never content.
 
 7. **Check the wiring:** `npx sable doctor`. Every check it runs corresponds to a way Sable fails *silently* — a second React (blank page, "invalid hook call"), a missing `@source` (Tailwind emits none of the package's classes, everything renders unstyled), or `data-sable-theme` set with no theme CSS imported (every theme renders as the Sable theme and the switcher looks broken). Exits 1 on any failure; `--json` for the structured report.

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # What's new
 
+## 0.14.0
+
+Motion that is crafted by default and calm on request, and the first pieces for agent products.
+
+- **New: two motion levels, and `subtle`.** Motion is now *essential*
+  (colour and focus feedback, press, overlay arrival, disclosure, loaders,
+  chart hover) or *expressive* (glides, rolling numbers, drawn ticks,
+  shakes, staggers, chart arrival and morph, scroll reveals, spring
+  overshoot). Expressive durations also multiply by `--motion-expressive`,
+  which the new `subtle` policy sets to 0, and `subtle` takes the overshoot
+  out of `ease-spring` and `ease-bounce`. So `full` (the default) plays both,
+  `subtle` keeps every answer and drops every flourish, and `off` stills
+  everything. Set it app-wide with `<MotionProvider policy="subtle">`, for a
+  region with the new `<MotionScope level="subtle">`, or per component with a
+  new `motion` prop. Scopes and props can only turn motion **down**: `full`
+  on a component means "inherit", so nothing can override a reader's
+  reduce-motion setting. `useMotion()` gains `expressive`, and
+  `useMotionLevel(motion)` resolves a component's prop against everything
+  around it. `Reveal` and `TextReveal` are expressive: under `subtle` the
+  content is simply there.
+- **New recipes:** `motion-glide` (one indicator travelling to the selected
+  option), `motion-shake` (a refused answer, driven by the new `useShake()`),
+  `motion-tick` (a mark that draws itself in), `motion-appear` (a small
+  control mounting in place, through `@starting-style`), `motion-arrive`
+  (items a user action adds to a list, staggered) and `motion-size` (easing
+  between sizes, with the new `useAutoSize()` measuring a label change).
+  `sable utility <name>` has each one.
+- **New: `NumberTicker`.** A number that rolls to its new value, digit by
+  digit, keyed by place value, so 999 → 1,000 rolls the columns it keeps and
+  grows the one it gains. It formats through `Intl.NumberFormat`, reads as
+  plain text to assistive tech and copy, and lands without a roll under
+  `subtle`. `NotificationBadge` counts and the `PieChart` / `RadialChart`
+  centre values now roll through it.
+- **New: `ConfirmButton`.** An inline two-step for low-stakes destructive
+  actions. The first press arms it: the label changes, the button eases to
+  the new width, a thin line drains while it waits, and the armed state is
+  announced. A second press within `timeout` confirms; Escape, a click
+  elsewhere, blur or the timeout disarms it, and a double-click cannot
+  confirm. `DestructiveActionModal` stays the answer for high stakes.
+- **New: `TooltipGroup`.** Wrap a row of `SimpleTooltip`s and they share one
+  tooltip: moving along a toolbar, it glides to the next button and its label
+  slides across instead of closing and reopening.
+- **Selections travel.** `Tabs` renders a gliding indicator in both variants
+  (the underline and the pill), and a changed panel fades in. Single-select
+  `ToggleGroup appearance="segmented"` has one fill that glides and resizes
+  to the pressed option. `ThemeSwitcher` uses the same recipe, and
+  `Carousel`'s active dot eases its width. `SideNav` and `SidebarNav` draw
+  the current page as one fill that glides to the new item when the page
+  changes inside a persistent layout. Menu, Select and Combobox highlights
+  keep their glide, which is now expressive.
+- **Calendar pages with direction.** Going to the next or previous month
+  slides the old grid out toward the edge it leaves by and the new one in
+  from the other, over a short travel with a fade (react-day-picker's
+  `animate` mode on Sable keyframes, mirrored in RTL). It is on at full
+  motion only (a `DatePicker`'s calendar follows the app or scope policy);
+  `Calendar` takes `motion`, and an explicit `animate` still wins.
+- **Sidebar collapse eases.** Collapsing to the icon rail eases the width
+  instead of jumping 192px in one frame, so the content beside it visibly
+  takes the room. Icons stay on one column throughout and labels fade back
+  in on reopen. `Sidebar` takes `motion`; `subtle` snaps.
+- **Focus outlines ease in.** `motion-interactive` now also transitions
+  `outline-color`, `outline-width` and `outline-offset`, so a keyboard focus
+  ring drawn with `outline-*` grows from the element's edge over the fast
+  step instead of appearing in one frame. Instant under reduced motion.
+- **States finish their story.** `OtpField` shakes once when it turns
+  invalid, and its digits take the destructive colour. `CodeBlock`'s copy
+  button swaps to a check in place and announces "Copied". `Feedback` shows a
+  drawn check and a thank-you before it closes. A loading `Button` keeps its
+  width: the spinner lays over the label instead of replacing it. The
+  `ChatComposer` grows with an ease, and its send and stop swap in one
+  button. `SearchInput` and `CommandMenu`'s clear buttons appear rather than
+  pop. Expanding a `Tree` folder settles its rows in, staggered. The
+  `Checkbox` tick draws in from its leading stroke.
+- **Fixed: disclosure chevrons snapped.** Tailwind v4's `rotate-*` writes the
+  standalone `rotate` property, which `motion-interactive` did not list, so
+  the chevrons on `Accordion`, `Collapsible`, `Tree` and `ShowMore` jumped
+  180° in one frame while the panel beside them eased. The recipe now lists
+  `rotate`. `DataTable`'s sort chevron rotates instead of swapping glyphs.
+- **Chart hover dims mix toward the surface.** The bars, slices and rings
+  that are not under the pointer now step back by mixing toward the surface
+  colour instead of fading, so gridlines no longer strike through a dimmed
+  bar and a dimmed ring stays solid over its track.
+- **Deprecated: `animate` on charts.** Every chart takes `motion` instead.
+  `animate={false}` maps to `motion="subtle"` (no arrival or morph, hover
+  feedback kept); use `motion="off"` to still everything.
+- **Motion declaration is a build gate.** A component that reacts to the
+  pointer or carries state must declare its four motion slots (arrival,
+  response, transition, activity) in its meta, or decline each with a reason.
+  It used to be a report, and 36 components said nothing; all of them now
+  answer.
+- **Docs:** a new **Interactions** page shows the catalog by task (inspect,
+  select, confirm, recover, succeed, finish loading, type, point, notify).
+  Every preview has its own motion level and Replay. Playgrounds gain a Motion
+  row and **Copy for agent**, which copies the exact JSX, imports, install
+  commands, the active theme and `sable component <Name>`. The Motion page
+  sets the policy to Full, Subtle or Off and shows the two levels side by
+  side.
+
+- **New: `ToolCall`.** One tool an agent called, as a quiet row inside its
+  turn: a status glyph, what it did in plain words, the tool's name in mono,
+  and one word for where it is (`running`, `awaiting`, `complete`, `error`,
+  `denied`). Input and output sit behind a disclosure, as formatted JSON or
+  as a rendered result passed as `children`. A failure's message shows under
+  the row without opening anything. When a call settles, its spinner swaps
+  for the outcome in place (`motion-icon-swap`), and that's the only motion
+  in the row. The change is announced once, and a thread restored from
+  history announces nothing.
+- **New: `ApprovalBlock`**, in a new "AI & agents" block family. An agent
+  asking permission for one call: the question in plain words, what can't be
+  undone, the call's details, an "allow for the rest of this chat" Checkbox,
+  and Deny / Allow. Neither button is focused on arrival. After a decision,
+  one status line replaces the buttons, focus moves to it, and it's
+  announced. `onApprove({ remember })` and `onDeny()` report the answer.
+
 ## 0.13.2
 
 What to use instead, wherever a component is the wrong pick.

package/CONTRIBUTING.md

@@ -168,7 +168,9 @@ artwork, and nothing in the core graph imports `src/icon-sets/`.
 
 ## Motion
 
-Motion is a first-class layer — **subtle by default, tasteful spring welcome, zero runtime dependency** (CSS tokens/recipes + tiny browser-native JS). When a component has any interaction, wire it to the system; don't leave it static or hand-roll a transition.
+Motion is a first-class layer — **crafted by default, calm on request, zero runtime dependency** (CSS tokens/recipes + tiny browser-native JS). When a component has any interaction, wire it to the system; don't leave it static or hand-roll a transition. When its selection, value or mark changes in place, move the one element that represents it (`motion-glide`, `NumberTicker`, `motion-tick`, `motion-icon-swap`) rather than switching two things on and off.
+
+**Two levels.** Essential motion (feedback, press, overlay arrival, disclosure, loaders) runs on the plain tokens. Expressive motion (glides, rolling numbers, drawn ticks, shakes, staggers, arrival choreography, overshoot) multiplies its durations by `var(--motion-expressive, 1)` as well — the shipped expressive recipes already do — and JS-driven flourishes gate on `useMotionLevel(motion).expressive`. A component that owns a flourish takes `motion?: MotionLevel` (`full` | `subtle` | `off`) and spreads `data-motion={motionAttribute(motion)}` on its root; the prop only turns motion down.
 
 **Four slots.** Every component answers all four — by filling the slot, or by declining it in `meta.motion` with `recipe: "none"` and a reason:
 
@@ -179,13 +181,13 @@ Motion is a first-class layer — **subtle by default, tasteful spring welcome,
 | `transition` | how does it move between its own states? | `motion-disclosure`, or ease the transform |
 | `activity` | how do you tell "working" from "frozen"? | `motion-spin` · `motion-pulse` · `motion-shimmer` |
 
-This paragraph said "don't leave it static" for many releases while **nothing checked it**. The four motion rules below are all prohibitive — they fire on motion that is present and wrong, and none can fire on motion that is absent — so a component that snapped between every state passed the whole contract, and motion stayed a thing a human had to request by name. Two gates now close that: `static-interactive` (lint, fires on an element styled for pointer states with no recipe on it) and `meta.motion` + `pnpm build:registry -- --motion-report` (declaration and coverage).
+This paragraph said "don't leave it static" for many releases while **nothing checked it**. The four motion rules below are all prohibitive — they fire on motion that is present and wrong, and none can fire on motion that is absent — so a component that snapped between every state passed the whole contract, and motion stayed a thing a human had to request by name. Two gates now close that: `static-interactive` (lint, fires on an element styled for pointer states with no recipe on it) and `meta.motion` — `build-registry` **fails** when a component that reacts to the pointer or carries state declares no `motion` array (`pnpm build:registry -- --motion-report` prints the slot-by-slot coverage).
 
-1. **Reach for a recipe first** — apply one named class instead of a bespoke transition string: `motion-interactive` (default hover/focus/press chrome — **replaces** `transition-colors`), `motion-press` (tactile press; always pair with `motion-interactive`), `motion-fade`/`motion-pop`/`motion-slide-{up,down,left,right}` (overlay enter/exit, on Base UI `data-[starting-style]`/`data-[ending-style]`), `motion-disclosure` (height), and loaders `motion-{spin,shimmer,pulse,dot-bounce,ping}`.
+1. **Reach for a recipe first** — apply one named class instead of a bespoke transition string: `motion-interactive` (default hover/focus/press chrome — **replaces** `transition-colors`), `motion-press` (tactile press; always pair with `motion-interactive`), `motion-fade`/`motion-pop`/`motion-slide-{up,down,left,right}` (overlay enter/exit, on Base UI `data-[starting-style]`/`data-[ending-style]`), `motion-disclosure` (height), `motion-icon-swap` (a glyph that changes with state), the expressive `motion-{glide,shake,tick,appear,arrive,size}`, and loaders `motion-{spin,shimmer,pulse,dot-bounce,ping}`.
 2. **Drop to tokens only when a recipe doesn't fit.** Durations via `duration-(--motion-duration-{instant|fast|base|slow|slower})` — **never** a raw `duration-150` (it bypasses the kill-switch). Easings via `ease-{standard|decelerate|emphasized|spring|bounce}`. Spring/bounce overshoot is **enter-only**; exits stay clean.
 3. **Never** use Tailwind's built-in `animate-spin`/`animate-pulse`/`animate-ping`/`animate-bounce` — they ignore `--motion-scale`, so the on/off policy can't freeze them. Use the scale-aware `motion-*` loader recipes.
 4. **Compositor-first & subtle:** animate opacity + transform (scale/translate) only; short durations; no exit overshoot; no gaudy motion.
-5. **Policy:** all token-driven motion collapses to static under `prefers-reduced-motion` or `<MotionProvider>` off (one `--motion-scale: 0`). JS primitives read `useMotion().enabled` and must no-op when motion is off.
+5. **Policy:** all token-driven motion collapses to static under `prefers-reduced-motion` or `<MotionProvider>` off (one `--motion-scale: 0`); `subtle` zeroes `--motion-expressive` only. JS primitives read `useMotion().enabled` and must no-op when motion is off; JS flourishes read `expressive`.
 6. **JS motion lives in `src/motion/`** (zero-dep, browser-native: WAAPI / IntersectionObserver / View Transitions). Do **not** add the `motion` library to core — drag/gesture, FLIP layout, and velocity springs are the future optional `@sableui/motion` adapter (peer-dep `motion`).
 
 Full token table + rationale: `DESIGN.md → Motion`. Live demo: docs → Foundations → Motion (also the on/off toggle).

package/DESIGN.md

@@ -477,7 +477,11 @@ Reference via `z-(--z-overlay)`, never a raw `z-[9999]`. Base UI overlays portal
 
 ## Motion
 
-Motion is a first-class token layer, not an afterthought. **Subtle by default, with room for tasteful delight** — quick, deliberate, skippable, and never gaudy. The feel is restrained but alive, built compositor-first (opacity + transform only).
+Motion is a first-class token layer, not an afterthought. **Crafted by default, calm on request** — quick, deliberate, skippable, and never gaudy. Sable components ship the small continuity that makes an interface feel made rather than assembled: one indicator travels to the selected tab instead of two fills blinking, a total rolls to its new value, a check draws itself in, a wrong code shakes and clears. Built compositor-first (opacity + transform, with height and an absolutely positioned glider's size as the sanctioned exceptions).
+
+**The principle behind the craft: one thing travels; two things do not blink.** When a selection, a value or a mark changes in place, move the element that represents it. And finish the story — a refused answer shakes *and* says why, a success confirms where it happened, an armed action asks again before it acts.
+
+**Two levels.** *Essential* motion answers the user — colour and focus feedback, press, overlay arrival, disclosure height, loaders, chart hover. *Expressive* motion narrates — glides, rolling numbers, drawn ticks, shakes, staggers, chart arrival and morph, scroll reveals, spring overshoot. Expressive durations are multiplied by a second factor, `--motion-expressive`, which `data-motion="subtle"` sets to 0 (and which takes the overshoot out of `ease-spring`). So the policy ladder is `full` (default: both) → `subtle` (essential only) → `off` (nothing moves; every state still changes). Set it app-wide on `<MotionProvider policy>`, for a region with `<MotionScope level>`, or per component with the `motion` prop that every component owning a flourish takes. Scopes and props can only turn motion **down** — `full` on a component means "inherit", so nothing below the provider can override a reader's reduce-motion setting.
 
 **Three parts:**
 
@@ -487,9 +491,10 @@ Motion is a first-class token layer, not an afterthought. **Subtle by default, w
    - Consume easings via the `ease-*` utilities; durations via `duration-(--motion-duration-*)` (so the kill-switch always applies).
 
 2. **Recipes** (`styles.css`) — named, reusable behaviours a component opts into with one class instead of a bespoke transition string:
-   - `motion-interactive` (hover/focus colour + transform transitions) · `motion-press` (tactile press settle) · `motion-fade` (scrims) · `motion-pop` (anchored/centred surfaces — gentle spring on open) · `motion-slide-{up,down,left,right}` (directional fade-slide) · `motion-disclosure` (height) · `motion-draw` (SVG line-art draw-on — a `pathLength="1"` path inside a `<Reveal>` draws in when scrolled into view; stagger siblings via `--motion-draw-delay`) · loaders `motion-spin`/`motion-pulse`/`motion-shimmer`/`motion-dot-bounce`. Enter/exit recipes drive off Base UI's `data-[starting-style]`/`data-[ending-style]`.
+   - `motion-interactive` (hover/focus colour + transform transitions, including `rotate`) · `motion-press` (tactile press settle) · `motion-fade` (scrims) · `motion-pop` (anchored/centred surfaces — gentle spring on open) · `motion-slide-{up,down,left,right}` (directional fade-slide) · `motion-disclosure` (height) · `motion-draw` (SVG line-art draw-on — a `pathLength="1"` path inside a `<Reveal>` draws in when scrolled into view; stagger siblings via `--motion-draw-delay`) · loaders `motion-spin`/`motion-pulse`/`motion-shimmer`/`motion-dot-bounce`. Enter/exit recipes drive off Base UI's `data-[starting-style]`/`data-[ending-style]`.
+   - Expressive: `motion-glide` (one indicator travelling to the selection) · `motion-shake` (a refused answer, driven by `useShake()`) · `motion-tick` (a mark that draws itself in) · `motion-appear` (a small control mounting via `@starting-style`) · `motion-arrive` (items a user action adds to a list, staggered) · `motion-size` (easing between intrinsic sizes via `interpolate-size`). `NumberTicker` is the rolling-number primitive.
 
-3. **Policy** — `prefers-reduced-motion` and `<MotionProvider>` collapse `--motion-scale` to 0 in one place: transitions resolve instantly, loaders hold their first frame. Motion is fully **toggleable on/off** in-app via `useMotion()`.
+3. **Policy** — `prefers-reduced-motion` and `<MotionProvider>` collapse `--motion-scale` to 0 in one place: transitions resolve instantly, loaders hold their first frame. `subtle` zeroes `--motion-expressive` instead, so essential motion keeps playing. In-app, `useMotion()` reads and sets the policy; `useMotionLevel(motion)` resolves a component's own prop against everything around it, and JS-driven flourishes gate on its `expressive`.
 
 Richer physics (interruptible velocity-springs, FLIP layout, drag/gesture) is intentionally **out of core** — it's the future optional `@sableui/motion` adapter (peer-dep `motion`), reached for only when CSS genuinely can't express a surface.
 

package/dist/blocks/approval-block.js

@@ -0,0 +1,93 @@
+// src/blocks/approval-block.tsx
+import { useEffect, useId, useRef, useState } from "react";
+import { Button } from "../components/button/index.js";
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "../components/card/index.js";
+import { Checkbox } from "../components/checkbox/index.js";
+import { Code } from "../components/code/index.js";
+import { InlineStatus } from "../components/inline-status/index.js";
+import { Label } from "../components/label/index.js";
+import { cn } from "../lib/cn.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var request = {
+  tool: "send_email",
+  title: "Send the invoice to Ada?",
+  description: "The agent wants to email invoice INV-1042. An email can't be unsent.",
+  details: [
+    { label: "To", value: "ada@example.com" },
+    { label: "Subject", value: "INV-1042 for October" },
+    { label: "Attached", value: "INV-1042.pdf" }
+  ],
+  allowed: "Allowed. Sending the email.",
+  denied: "Denied. The agent won't send it."
+};
+function ApprovalBlock({ className, framed = true, onApprove, onDeny }) {
+  const [decision, setDecision] = useState(null);
+  const [remember, setRemember] = useState(false);
+  const id = useId();
+  const outcome = useRef(null);
+  useEffect(() => {
+    if (decision) outcome.current?.focus();
+  }, [decision]);
+  return /* @__PURE__ */ jsxs(Card, { variant: framed ? "default" : "flat", className: cn("w-full max-w-md", className), children: [
+    /* @__PURE__ */ jsxs(CardHeader, { children: [
+      /* @__PURE__ */ jsx(CardTitle, { children: request.title }),
+      /* @__PURE__ */ jsx(CardDescription, { children: request.description })
+    ] }),
+    /* @__PURE__ */ jsxs(CardContent, { className: "flex flex-col gap-4", children: [
+      /* @__PURE__ */ jsxs("dl", { className: "grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm", children: [
+        request.details.map((d) => /* @__PURE__ */ jsxs("div", { className: "contents", children: [
+          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: d.label }),
+          /* @__PURE__ */ jsx("dd", { className: "truncate text-foreground", children: d.value })
+        ] }, d.label)),
+        /* @__PURE__ */ jsxs("div", { className: "contents", children: [
+          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: "Tool" }),
+          /* @__PURE__ */ jsx("dd", { className: "min-w-0", children: /* @__PURE__ */ jsx(Code, { children: request.tool }) })
+        ] })
+      ] }),
+      decision ? null : /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+        /* @__PURE__ */ jsx(Checkbox, { id: `${id}-remember`, checked: remember, onCheckedChange: (v) => setRemember(v) }),
+        /* @__PURE__ */ jsxs(Label, { htmlFor: `${id}-remember`, className: "text-body-sm", children: [
+          "Allow ",
+          /* @__PURE__ */ jsx(Code, { children: request.tool }),
+          " for the rest of this chat"
+        ] })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx(CardFooter, { actions: true, className: "justify-end", children: decision ? /* @__PURE__ */ jsx(
+      InlineStatus,
+      {
+        ref: outcome,
+        tabIndex: -1,
+        role: "status",
+        tone: decision === "allowed" ? "success" : "neutral",
+        className: "me-auto outline-none",
+        children: decision === "allowed" ? request.allowed : request.denied
+      }
+    ) : /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(
+        Button,
+        {
+          variant: "outline",
+          onClick: () => {
+            setDecision("denied");
+            onDeny?.();
+          },
+          children: "Deny"
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        Button,
+        {
+          onClick: () => {
+            setDecision("allowed");
+            onApprove?.({ remember });
+          },
+          children: "Allow"
+        }
+      )
+    ] }) })
+  ] });
+}
+export {
+  ApprovalBlock
+};

package/dist/blocks/approval-block.meta.js

@@ -0,0 +1,23 @@
+// src/blocks/approval-block.meta.ts
+var approvalBlockMeta = {
+  name: "ApprovalBlock",
+  family: "AI & agents",
+  kind: "card",
+  width: { min: "18rem", max: "28rem" },
+  summary: `An agent asking permission for one tool call: the question, what will happen and what can't be undone, the call's details, an "allow for the rest of this chat" Checkbox, and Deny / Allow.`,
+  intent: 'Reach for this in a chat or agent run when a tool call waits on the person \u2014 sending, paying, deleting, publishing. The call itself, before and after the decision, is a ToolCall with status="awaiting", then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.',
+  notes: [
+    `The title is the question in plain words ("Send the invoice to Ada?"), not the tool's name; the tool's name is one row of the details, for the person who wants to know exactly what runs.`,
+    "The description says what can't be undone. That sentence is what the person is deciding on.",
+    "Deny comes first and Allow is the primary on the end, the same order as every Sable confirmation. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.",
+    "After a decision the buttons give way to one InlineStatus line saying what happened, so the thread keeps a record of the answer."
+  ],
+  a11y: [
+    "Focus moves to the outcome line when the buttons leave, instead of dropping to the page; the line is a role=status region, so the decision is announced.",
+    "The details are a dl, so each value is read with its label.",
+    "The remember Checkbox has its own Label, so the tool name inside it is part of its accessible name."
+  ]
+};
+export {
+  approvalBlockMeta
+};

package/dist/blocks/index.d.ts

@@ -13,6 +13,21 @@ declare function ApiKeysBlock({ className, framed, onCreate, onKeyAction }: ApiK
 
 declare const apiKeysBlockMeta: BlockMeta;
 
+interface ApprovalBlockProps {
+    className?: string;
+    /** false drops the card's surface and border — for a chat column that already frames it. */
+    framed?: boolean;
+    /** The person allowed the call. `remember` is the "for the rest of this chat" choice. */
+    onApprove?: (options: {
+        remember: boolean;
+    }) => void;
+    /** The person declined the call. */
+    onDeny?: () => void;
+}
+declare function ApprovalBlock({ className, framed, onApprove, onDeny }: ApprovalBlockProps): react.JSX.Element;
+
+declare const approvalBlockMeta: BlockMeta;
+
 interface ChatThreadBlockProps {
     className?: string;
     /** false drops the card's surface and border. Keep it framed on a muted page: incoming bubbles are the muted surface too. */
@@ -393,4 +408,4 @@ declare function WalletBlock({ className, framed, onSend, onReceive }: WalletBlo
 
 declare const walletBlockMeta: BlockMeta;
 
-export { ApiKeysBlock, ChatThreadBlock, CommandPaletteBlock, CtaBandBlock, DangerZoneBlock, DeviceComparisonBlock, EventCardBlock, FaqBlock, FeatureGridBlock, FeedbackFormBlock, GoalProgressBlock, HeroBlock, InviteTeamBlock, InvoiceHistoryBlock, KpiSparklineBlock, MediaPlayerBlock, NewsletterBlock, NotFoundBlock, NotificationListBlock, NotificationSettingsBlock, OrderTrackingBlock, PricingCardBlock, PricingTableBlock, ProductCardBlock, ProfileCardBlock, ProfileFormBlock, RevenueBreakdownBlock, SignInBlock, SignUpBlock, SiteFooterBlock, StatRowBlock, StepsBlock, TaskListBlock, TeamMembersBlock, TestimonialBlock, TrafficSourcesBlock, TrafficTrendBlock, UploadListBlock, VerifyCodeBlock, WalletBlock, apiKeysBlockMeta, chatThreadBlockMeta, commandPaletteBlockMeta, ctaBandBlockMeta, dangerZoneBlockMeta, deviceComparisonBlockMeta, eventCardBlockMeta, faqBlockMeta, featureGridBlockMeta, feedbackFormBlockMeta, goalProgressBlockMeta, heroBlockMeta, inviteTeamBlockMeta, invoiceHistoryBlockMeta, kpiSparklineBlockMeta, mediaPlayerBlockMeta, newsletterBlockMeta, notFoundBlockMeta, notificationListBlockMeta, notificationSettingsBlockMeta, orderTrackingBlockMeta, pricingCardBlockMeta, pricingTableBlockMeta, productCardBlockMeta, profileCardBlockMeta, profileFormBlockMeta, revenueBreakdownBlockMeta, signInBlockMeta, signUpBlockMeta, siteFooterBlockMeta, statRowBlockMeta, stepsBlockMeta, taskListBlockMeta, teamMembersBlockMeta, testimonialBlockMeta, trafficSourcesBlockMeta, trafficTrendBlockMeta, uploadListBlockMeta, verifyCodeBlockMeta, walletBlockMeta };
+export { ApiKeysBlock, ApprovalBlock, ChatThreadBlock, CommandPaletteBlock, CtaBandBlock, DangerZoneBlock, DeviceComparisonBlock, EventCardBlock, FaqBlock, FeatureGridBlock, FeedbackFormBlock, GoalProgressBlock, HeroBlock, InviteTeamBlock, InvoiceHistoryBlock, KpiSparklineBlock, MediaPlayerBlock, NewsletterBlock, NotFoundBlock, NotificationListBlock, NotificationSettingsBlock, OrderTrackingBlock, PricingCardBlock, PricingTableBlock, ProductCardBlock, ProfileCardBlock, ProfileFormBlock, RevenueBreakdownBlock, SignInBlock, SignUpBlock, SiteFooterBlock, StatRowBlock, StepsBlock, TaskListBlock, TeamMembersBlock, TestimonialBlock, TrafficSourcesBlock, TrafficTrendBlock, UploadListBlock, VerifyCodeBlock, WalletBlock, apiKeysBlockMeta, approvalBlockMeta, chatThreadBlockMeta, commandPaletteBlockMeta, ctaBandBlockMeta, dangerZoneBlockMeta, deviceComparisonBlockMeta, eventCardBlockMeta, faqBlockMeta, featureGridBlockMeta, feedbackFormBlockMeta, goalProgressBlockMeta, heroBlockMeta, inviteTeamBlockMeta, invoiceHistoryBlockMeta, kpiSparklineBlockMeta, mediaPlayerBlockMeta, newsletterBlockMeta, notFoundBlockMeta, notificationListBlockMeta, notificationSettingsBlockMeta, orderTrackingBlockMeta, pricingCardBlockMeta, pricingTableBlockMeta, productCardBlockMeta, profileCardBlockMeta, profileFormBlockMeta, revenueBreakdownBlockMeta, signInBlockMeta, signUpBlockMeta, siteFooterBlockMeta, statRowBlockMeta, stepsBlockMeta, taskListBlockMeta, teamMembersBlockMeta, testimonialBlockMeta, trafficSourcesBlockMeta, trafficTrendBlockMeta, uploadListBlockMeta, verifyCodeBlockMeta, walletBlockMeta };

package/dist/blocks/index.js

@@ -1,6 +1,8 @@
 // src/blocks/index.ts
 import { ApiKeysBlock } from "./api-keys-block.js";
 import { apiKeysBlockMeta } from "./api-keys-block.meta.js";
+import { ApprovalBlock } from "./approval-block.js";
+import { approvalBlockMeta } from "./approval-block.meta.js";
 import { ChatThreadBlock } from "./chat-thread-block.js";
 import { chatThreadBlockMeta } from "./chat-thread-block.meta.js";
 import { CommandPaletteBlock } from "./command-palette-block.js";
@@ -81,6 +83,7 @@ import { WalletBlock } from "./wallet-block.js";
 import { walletBlockMeta } from "./wallet-block.meta.js";
 export {
   ApiKeysBlock,
+  ApprovalBlock,
   ChatThreadBlock,
   CommandPaletteBlock,
   CtaBandBlock,
@@ -121,6 +124,7 @@ export {
   VerifyCodeBlock,
   WalletBlock,
   apiKeysBlockMeta,
+  approvalBlockMeta,
   chatThreadBlockMeta,
   commandPaletteBlockMeta,
   ctaBandBlockMeta,

package/dist/components/accordion/accordion.meta.js

@@ -122,6 +122,12 @@ var accordionMeta = {
       part: "AccordionPanel",
       why: "Panel height is the only cue that content came from THIS header rather than appearing at the bottom of the page. Snapping it open moves everything below by a screenful with nothing connecting cause to effect."
     },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Chevron",
+      why: "The chevron turning is the header's half of the same event as the panel opening. motion-interactive lists `rotate` (what Tailwind's rotate-* writes), so it turns with the panel instead of flipping 180\xB0 in one frame beside an easing panel. A custom `indicator` that rotates should carry motion-interactive itself."
+    },
     {
       slot: "activity",
       recipe: "none",
@@ -134,7 +140,7 @@ var accordionMeta = {
     "Arrow keys move roving focus between triggers; Home/End jump to the first/last; loopFocus wraps by default.",
     "Each trigger toggles its panel with Enter/Space; the panel is announced as a labelled region.",
     "A disabled AccordionItem dims and is skipped by keyboard focus while neighbouring items stay interactive.",
-    "The chevron rotation is driven by data-[panel-open] and the focus ring by focus-visible \u2014 both honor reduced-motion via the consumer's transitions."
+    "The chevron rotation is driven by data-[panel-open] and the focus ring by focus-visible; both ride motion-interactive, so reduced motion stills them with everything else."
   ],
   examples: [
     {
@@ -147,7 +153,7 @@ var accordionMeta = {
     },
     {
       label: "Custom indicator (plus-becomes-\xD7)",
-      code: '<Accordion defaultValue={["a"]}><AccordionItem value="a"><AccordionTrigger indicator={<Icon name="plus" className="text-xs text-muted-foreground transition-transform [[data-panel-open]_&]:rotate-45" />}>Can I cancel anytime?</AccordionTrigger><AccordionPanel>Yes \u2014 from billing settings.</AccordionPanel></AccordionItem></Accordion>'
+      code: '<Accordion defaultValue={["a"]}><AccordionItem value="a"><AccordionTrigger indicator={<Icon name="plus" className="text-xs text-muted-foreground motion-interactive [[data-panel-open]_&]:rotate-45" />}>Can I cancel anytime?</AccordionTrigger><AccordionPanel>Yes \u2014 from billing settings.</AccordionPanel></AccordionItem></Accordion>'
     }
   ]
 };

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

@@ -117,11 +117,18 @@ var areaChartMeta = {
       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 (draw-on, rising fill) and the data-change morph are the flourish; the gliding cursor and tooltip 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",
@@ -176,7 +183,7 @@ var areaChartMeta = {
       slot: "arrival",
       recipe: "custom",
       part: "Area + line",
-      why: "Once on screen, each line draws on (stroke-dashoffset) and its fill rises from the baseline, series staggered \u2014 the trend is read as it is drawn. On the motion tokens; reduced motion shows the finished chart."
+      why: 'Once on screen, each line draws on (stroke-dashoffset) and its fill rises from the baseline, series staggered \u2014 the trend is read as it is drawn. 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",
@@ -188,7 +195,7 @@ var areaChartMeta = {
       slot: "transition",
       recipe: "custom",
       part: "Area + line",
-      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/attachment/attachment.meta.js

@@ -148,6 +148,32 @@ var attachmentMeta = {
     "overlay-foreground",
     "ring"
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "An attachment lands as part of a composer or a message, and that surface owns the entrance. A card that animated in on its own would read as a second, separate event \u2014 as if another file had been added."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "With `onOpen`, the edge steps up under the pointer; it is the only cue that the card itself opens the file, not just its actions. Eased, it reads as the card answering the cursor rather than a border flickering as the pointer crosses a busy composer."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Root",
+      why: "Uploading to failed re-colours the edge and fill without changing the shape. The ease keeps it legible as the same file turning red; snapped, a failed card looks like a different card replaced the one that was sent."
+    },
+    {
+      slot: "activity",
+      recipe: "motion-pulse",
+      part: "Progress",
+      why: "While uploading with no known `progress`, the bar is indeterminate and pulses (Progress's own recipe); with a number, the fill eases toward each new value. A still bar at a fixed width is indistinguishable from an upload that has stalled."
+    }
+  ],
   a11y: [
     "The full-card trigger is a real stretched `<button>` with an accessible label, not a click handler on a div \u2014 so it is one tab stop, keyboard-activatable, and focus-ringed.",
     "Actions sit above that trigger in the stacking order, which keeps them individually focusable and stops a click on `remove` from also opening the file. Text is only made click-through when a trigger is present, so a filename stays selectable otherwise.",

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.",