@sableui/react 0.13.1 → 0.14.0

package/dist/components/number-ticker/number-ticker.js

@@ -0,0 +1,246 @@
+"use client";
+
+// src/components/number-ticker/number-ticker.tsx
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { useIsomorphicLayoutEffect } from "../../lib/use-isomorphic-layout-effect.js";
+import { motionAttribute, useMotionLevel } from "../../motion/MotionProvider.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var COPIES = 3;
+var CELLS = COPIES * 10;
+var MIDDLE = 10;
+var ROLL = "calc(var(--motion-duration-slower) * var(--motion-expressive, 1)) var(--motion-ease-emphasized)";
+var RESIZE = `width ${ROLL}, opacity var(--motion-duration-fast) var(--motion-ease-standard)`;
+function rollDelay(placeFromRight) {
+  return `calc(${Math.min(placeFromRight, 8) * 30}ms * var(--motion-scale, 1) * var(--motion-expressive, 1))`;
+}
+function cellsFor(parts, glyphs, prefix, suffix) {
+  const digitOf = (ch) => glyphs.indexOf(ch);
+  const integerDigits = parts.filter((p) => p.type === "integer").reduce((n, p) => n + [...p.value].filter((ch) => digitOf(ch) >= 0).length, 0);
+  const cells = [];
+  if (prefix) cells.push({ key: "prefix", rank: 0, kind: "static", char: prefix });
+  let seenInteger = 0;
+  let fraction = 0;
+  let after = 0;
+  let afterNumber = false;
+  const before = [];
+  const typeCount = /* @__PURE__ */ new Map();
+  for (const part of parts) {
+    if (part.type === "integer") {
+      afterNumber = true;
+      for (const ch of part.value) {
+        const digit = digitOf(ch);
+        const place = integerDigits - 1 - seenInteger;
+        if (digit < 0) {
+          cells.push({ key: `i${place}x`, rank: 2e6 - place * 2, kind: "static", char: ch });
+          continue;
+        }
+        seenInteger++;
+        cells.push({ key: `i${place}`, rank: 2e6 - place * 2, kind: "digit", digit });
+      }
+    } else if (part.type === "group") {
+      const place = integerDigits - seenInteger;
+      cells.push({ key: `g${place}`, rank: 2e6 - place * 2 + 1, kind: "static", char: part.value });
+    } else if (part.type === "decimal") {
+      afterNumber = true;
+      cells.push({ key: "decimal", rank: 3e6, kind: "static", char: part.value });
+    } else if (part.type === "fraction") {
+      for (const ch of part.value) {
+        const digit = digitOf(ch);
+        const at = fraction++;
+        cells.push(
+          digit < 0 ? { key: `f${at}x`, rank: 4e6 + at, kind: "static", char: ch } : { key: `f${at}`, rank: 4e6 + at, kind: "digit", digit }
+        );
+      }
+    } else {
+      const side = afterNumber ? "a" : "b";
+      const n = typeCount.get(`${side}${part.type}`) ?? 0;
+      typeCount.set(`${side}${part.type}`, n + 1);
+      const cell = { key: `${side}-${part.type}-${n}`, rank: 5e6 + after++, kind: "static", char: part.value };
+      if (afterNumber) cells.push(cell);
+      else before.push(cell);
+    }
+  }
+  before.forEach((cell, i) => {
+    cell.rank = 2e6 - 1e5 - (before.length - i);
+  });
+  if (suffix) cells.push({ key: "suffix", rank: 6e6, kind: "static", char: suffix });
+  return [...before, ...cells].sort((a, b) => a.rank - b.rank);
+}
+var GLYPH = "before:content-[attr(data-char)]";
+var CELL = "relative inline-block whitespace-pre";
+function StaticCell({ char }) {
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("span", { "data-char": char, className: cn("invisible", GLYPH) }),
+    /* @__PURE__ */ jsx("span", { "data-char": char, className: cn("absolute inset-0 overflow-x-clip", GLYPH) })
+  ] });
+}
+var translateFor = (pos) => `0 ${-pos / CELLS * 100}%`;
+function DigitCell({ digit, glyphs, direction, delay, animate }) {
+  const stack = useRef(null);
+  const [initial] = useState(() => MIDDLE + digit);
+  const pos = useRef(initial);
+  const snap = (el, to) => {
+    const transition = el.style.transition;
+    el.style.transition = "none";
+    el.style.translate = translateFor(to);
+    void el.offsetHeight;
+    el.style.transition = transition;
+    pos.current = to;
+  };
+  useIsomorphicLayoutEffect(() => {
+    const el = stack.current;
+    if (!el || pos.current % 10 === digit) return;
+    if (!animate) {
+      snap(el, MIDDLE + digit);
+      return;
+    }
+    const target = (from) => {
+      let to2 = from - from % 10 + digit;
+      if (direction === "up" && to2 < from) to2 += 10;
+      if (direction === "down" && to2 > from) to2 -= 10;
+      return to2;
+    };
+    let to = target(pos.current);
+    if (to < 0 || to >= CELLS) {
+      snap(el, MIDDLE + pos.current % 10);
+      to = target(pos.current);
+    }
+    el.style.translate = translateFor(to);
+    pos.current = to;
+  }, [digit, direction, animate]);
+  const settle = (event) => {
+    if (event.target !== event.currentTarget || event.propertyName !== "translate") return;
+    const at = pos.current;
+    if (at < MIDDLE || at >= MIDDLE + 10) snap(event.currentTarget, MIDDLE + at % 10);
+  };
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("span", { "data-char": glyphs[digit], className: cn("invisible", GLYPH) }),
+    /* @__PURE__ */ jsx("span", { className: "absolute inset-0 overflow-clip", children: /* @__PURE__ */ jsx(
+      "span",
+      {
+        ref: stack,
+        onTransitionEnd: settle,
+        className: "absolute inset-x-0 top-0 flex flex-col",
+        style: { translate: translateFor(initial), transition: `translate ${ROLL} ${delay}` },
+        children: Array.from({ length: CELLS }, (_, i) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: a column's positions are fixed
+          /* @__PURE__ */ jsx("span", { "data-char": glyphs[i % 10], className: GLYPH }, i)
+        ))
+      }
+    ) })
+  ] });
+}
+function NumberTicker({
+  value,
+  format,
+  locales,
+  prefix,
+  suffix,
+  trend = "auto",
+  motion,
+  className,
+  ...props
+}) {
+  const { expressive } = useMotionLevel(motion);
+  const formatKey = JSON.stringify(format ?? {});
+  const localeKey = Array.isArray(locales) ? locales.join(",") : locales ?? "";
+  const { formatter, glyphs } = useMemo(() => {
+    const f = new Intl.NumberFormat(locales, format);
+    const digits = new Intl.NumberFormat(locales, { numberingSystem: f.resolvedOptions().numberingSystem, useGrouping: false });
+    return { formatter: f, glyphs: Array.from({ length: 10 }, (_, d) => digits.format(d)) };
+  }, [formatKey, localeKey]);
+  const prefixText = typeof prefix === "string" || typeof prefix === "number" ? String(prefix) : "";
+  const suffixText = typeof suffix === "string" || typeof suffix === "number" ? String(suffix) : "";
+  const parts = formatter.formatToParts(value);
+  const text = `${prefixText}${parts.map((p) => p.value).join("")}${suffixText}`;
+  const [track, setTrack] = useState(() => ({
+    text,
+    value,
+    cells: cellsFor(parts, glyphs, prefixText, suffixText),
+    leaving: [],
+    direction: "up",
+    changed: false
+  }));
+  let current = track;
+  if (track.text !== text) {
+    const cells = cellsFor(parts, glyphs, prefixText, suffixText);
+    const keys = new Set(cells.map((c) => c.key));
+    current = {
+      text,
+      value,
+      cells,
+      leaving: expressive ? [...track.leaving, ...track.cells].filter((c) => !keys.has(c.key)) : [],
+      direction: trend === "auto" ? value < track.value ? "down" : "up" : trend,
+      changed: true
+    };
+    setTrack(current);
+  }
+  useEffect(() => {
+    if (!current.leaving.length) return;
+    const id = setTimeout(() => setTrack((t) => t.leaving.length ? { ...t, leaving: [] } : t), 1200);
+    return () => clearTimeout(id);
+  }, [current.leaving]);
+  const drop = (key) => (event) => {
+    if (event.target !== event.currentTarget || event.propertyName !== "width") return;
+    setTrack((t) => ({ ...t, leaving: t.leaving.filter((c) => c.key !== key) }));
+  };
+  const leavingKeys = new Set(current.leaving.map((c) => c.key));
+  const shown = [...current.cells, ...current.leaving].sort((a, b) => a.rank - b.rank);
+  const animate = expressive && current.changed;
+  const placeFromRight = /* @__PURE__ */ new Map();
+  let place = 0;
+  for (let i = shown.length - 1; i >= 0; i--) if (shown[i].kind === "digit") placeFromRight.set(shown[i].key, place++);
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      "data-slot": "number-ticker",
+      "data-motion": motionAttribute(motion),
+      className: cn("inline-block whitespace-nowrap tabular-nums [interpolate-size:allow-keywords]", className),
+      ...props,
+      children: [
+        prefixText ? null : prefix,
+        /* @__PURE__ */ jsx("span", { className: "sr-only", children: text }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", dir: "ltr", children: shown.map((cell) => {
+          const leaving = leavingKeys.has(cell.key);
+          return /* @__PURE__ */ jsx(
+            "span",
+            {
+              onTransitionEnd: leaving ? drop(cell.key) : void 0,
+              className: cn(
+                CELL,
+                // A cell that arrives after the first paint grows in from nothing.
+                // @starting-style only applies to a newly inserted element, so the
+                // cells already on screen ignore it.
+                animate && !leaving && "starting:w-0 starting:opacity-0",
+                leaving && "w-0 opacity-0"
+              ),
+              style: animate ? { transition: RESIZE } : void 0,
+              children: cell.kind === "digit" ? /* @__PURE__ */ jsx(
+                DigitCell,
+                {
+                  digit: cell.digit,
+                  glyphs,
+                  direction: current.direction,
+                  delay: rollDelay(placeFromRight.get(cell.key) ?? 0),
+                  animate
+                }
+              ) : /* @__PURE__ */ jsx(StaticCell, { char: cell.char })
+            },
+            cell.key
+          );
+        }) }),
+        suffixText ? null : suffix
+      ]
+    }
+  );
+}
+NumberTicker.displayName = "NumberTicker";
+export {
+  NumberTicker
+};

package/dist/components/number-ticker/number-ticker.meta.js

@@ -0,0 +1,159 @@
+// src/components/number-ticker/number-ticker.meta.ts
+var numberTickerMeta = {
+  name: "NumberTicker",
+  summary: "A number that rolls to its new value digit by digit, like an odometer. Formatted with Intl.NumberFormat (currency, percent, compact, any locale); separators, signs and units hold still while each digit column turns, and a digit that appears or goes away eases its width so nothing around it jumps. At rest on first paint; under subtle or reduced motion the value simply updates.",
+  status: "stable",
+  keywords: [
+    "number",
+    "counter",
+    "odometer",
+    "rolling number",
+    "animated number",
+    "ticker",
+    "count up",
+    "stat",
+    "kpi",
+    "metric",
+    "price"
+  ],
+  usage: {
+    description: `Use NumberTicker for a figure that changes in place while someone is looking at it \u2014 a dashboard total after a filter changes, a live count, a price as a plan's options change, a score. The roll says "this number moved, and by roughly this much"; the reader sees the change happen instead of noticing, later, that a number is different.`,
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Use it for the headline figure that a control on the same screen changes \u2014 the total above a chart, the price beside a quantity stepper \u2014 so cause and effect are seen together."
+      },
+      {
+        guidance: "do",
+        description: "Format through `format` (currency, percent, compact) rather than pre-formatting a string, so separators and units stay put while only the digits roll."
+      },
+      {
+        guidance: "do",
+        description: 'Pass `aria-live="polite"` only when the change itself is news the reader would otherwise miss; most tickers sit beside the control that changed them and need no announcement.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for values that change many times a second (a stopwatch, a stock tick, a progress percentage) \u2014 the rolls never land and read as a blur. Render the number as plain tabular text."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for numbers that are names rather than amounts \u2014 an order ID, a phone number, a year, a version. Rolling implies a quantity going up or down."
+      },
+      {
+        guidance: "dont",
+        description: "Do not animate a number on page load to make it feel alive. The first paint is at rest on purpose; for an entrance, reveal the card it sits in (the Reveal motion primitive)."
+      },
+      {
+        guidance: "dont",
+        description: "Do not use it for a value inside a known range that needs a picture of how full it is \u2014 show a Meter, with the number beside it.",
+        instead: ["Meter"]
+      }
+    ]
+  },
+  related: {
+    components: ["Meter", "NotificationBadge", "PieChart", "RadialChart", "Sparkline"]
+  },
+  props: [
+    {
+      name: "value",
+      type: "number",
+      description: "The number to show. When it changes, the digits roll to it."
+    },
+    {
+      name: "format",
+      type: "Intl.NumberFormatOptions",
+      description: 'How to write the number \u2014 `{ style: "currency", currency: "USD" }`, `{ style: "percent" }`, `{ notation: "compact" }`, fraction digits. Passed to Intl.NumberFormat; an inline object is fine (it is compared by value).'
+    },
+    {
+      name: "locales",
+      type: "string | string[]",
+      default: "runtime locale",
+      description: "BCP 47 locale(s) for the formatting. Digits roll through the locale's own numbering system."
+    },
+    {
+      name: "prefix",
+      type: "ReactNode",
+      description: "Before the number. A string becomes part of the number's text (and rolls in or out with it); an element is rendered as given."
+    },
+    {
+      name: "suffix",
+      type: "ReactNode",
+      description: `After the number ("+", " pts"). A string becomes part of the number's text; an element is rendered as given.`
+    },
+    {
+      name: "trend",
+      type: '"auto" | "up" | "down"',
+      default: '"auto"',
+      description: "Which way the digits roll. `auto` rolls up as the value grows and down as it shrinks; `up` / `down` fix it (a countdown, a score that only climbs)."
+    },
+    {
+      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 roll is expressive, so `subtle` updates the value in place."
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Merged onto the root span. Set the type tier here (`text-heading-2`, `text-display-lg`); the ticker adds tabular figures so widths hold still."
+    },
+    {
+      name: "...span props",
+      type: 'Omit<ComponentPropsWithRef<"span">, "children" | "prefix">',
+      description: "Remaining span attributes pass through to the root \u2014 `aria-live` to announce changes, `id`, data attributes."
+    }
+  ],
+  tokensUsed: [],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "The first paint is at rest. A number counting up on page load is decoration that delays the reading; the roll is kept for the moment the value actually changes."
+    },
+    {
+      slot: "response",
+      recipe: "none",
+      part: "Root",
+      why: "It is a reading, not a control; the control that changes it gives the feedback."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Digit",
+      why: "Each digit column turns to its new place on the expressive roll (the slower token, emphasized easing, staggered from the ones column), and arriving or departing columns ease their width. The roll is what shows a change happened and how big it was \u2014 the hundreds turning reads as a bigger move than the ones. No recipe can translate per-digit columns, so it is custom; it is multiplied by --motion-expressive, so `subtle` and reduced motion land the value at once."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "A number has no working state; show a Skeleton while it loads."
+    }
+  ],
+  a11y: [
+    'The whole written number (with any string prefix or suffix) is real text in a visually hidden span; the rolling columns are aria-hidden and draw their glyphs as generated content, so screen readers, find-in-page and copy all get "$1,234.50", never a stack of digits.',
+    'It is not a live region by default \u2014 a figure that changes because the reader moved a control is already where their attention is. Pass `aria-live="polite"` when a change elsewhere should be announced.',
+    "Tabular figures keep every digit the same width, so a roll never shifts the text around it."
+  ],
+  examples: [
+    {
+      label: "Basic",
+      code: '<NumberTicker value={1284} className="text-heading-2" />'
+    },
+    {
+      label: "Currency",
+      code: '<NumberTicker value={4280.5} format={{ style: "currency", currency: "USD" }} className="text-display-lg" />'
+    },
+    {
+      label: "Percent, announced",
+      code: '<NumberTicker value={0.428} format={{ style: "percent", maximumFractionDigits: 1 }} aria-live="polite" />'
+    },
+    {
+      label: "Subtle",
+      code: '<NumberTicker value={92} suffix=" pts" motion="subtle" />'
+    }
+  ]
+};
+export {
+  numberTickerMeta
+};

package/dist/components/otp-field/otp-field.js

@@ -1,8 +1,10 @@
 // src/components/otp-field/otp-field.tsx
 import * as OtpParts from "@base-ui/react/otp-field";
-import { Fragment } from "react";
+import { Fragment, useEffect, useRef } from "react";
 import { cn } from "../../lib/cn.js";
 import { FIELD_INVALID, FIELD_SHELL } from "../../lib/field-shell.js";
+import { motionAttribute } from "../../motion/MotionProvider.js";
+import { useShake } from "../../motion/useShake.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 var resolvedBase;
 function otpBase() {
@@ -19,17 +21,31 @@ function OtpField({
   groupSize,
   getSlotLabel = defaultSlotLabel,
   "aria-invalid": ariaInvalid,
+  motion,
+  onAnimationEnd,
   ...root
 }) {
   const invalid = ariaInvalid === true || ariaInvalid === "true";
   const Base = otpBase();
+  const { shake, shakeProps } = useShake();
+  const wasInvalid = useRef(invalid);
+  useEffect(() => {
+    if (invalid && !wasInvalid.current) shake();
+    wasInvalid.current = invalid;
+  }, [invalid, shake]);
   return /* @__PURE__ */ jsx(
     Base.Root,
     {
       length,
       "data-invalid": invalid ? "" : void 0,
-      className: cn("inline-flex max-w-full items-center gap-2", className),
+      "data-motion": motionAttribute(motion),
+      className: cn("inline-flex max-w-full items-center gap-2 motion-shake", className),
       ...root,
+      "data-shake": shakeProps["data-shake"],
+      onAnimationEnd: (event) => {
+        shakeProps.onAnimationEnd(event);
+        onAnimationEnd?.(event);
+      },
       children: Array.from({ length }, (_, index) => (
         // Slots are positional and never reorder, so the index is the identity.
         // biome-ignore lint/suspicious/noArrayIndexKey: positional slots
@@ -55,7 +71,11 @@ function OtpField({
                 // Focus is FIELD_SHELL's ring alone, like every other field — a ring-
                 // coloured border under it made a 3px edge only here.
                 "data-[filled]:border-border-strong",
-                FIELD_INVALID
+                FIELD_INVALID,
+                // The digits turn too, not just the box: on a six-slot code the
+                // border alone is a thin line, and the characters are what the
+                // user is reading to find the mistake.
+                "aria-[invalid=true]:text-destructive"
               )
             }
           )

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

@@ -34,6 +34,10 @@ var otpFieldMeta = {
         guidance: "dont",
         description: 'Do not use OtpField for a password, an arbitrary-length PIN, or anything the user types from memory. Slots promise a fixed length; use Input with `type="password"` and `autocomplete="current-password"` instead.'
       },
+      {
+        guidance: "do",
+        description: "Clear the error as soon as the user edits the code (`onValueChange` \u2192 reset the error), and set it again when the next code is refused. Each refusal is then a fresh change to invalid, so the field shakes for every wrong code, not only the first."
+      },
       {
         guidance: "dont",
         description: "Do not intercept paste or clear the field on a wrong code before the user has seen the error. Blocking paste breaks SMS autofill and password managers, and wiping the slots erases the evidence of which digit was wrong."
@@ -123,7 +127,13 @@ var otpFieldMeta = {
     {
       name: "aria-invalid",
       type: "boolean",
-      description: "Marks every slot invalid (destructive border). `<Field error>` sets it for you."
+      description: "Marks every slot invalid (destructive border and digits). Turning it on after mount shakes the field once. `<Field error>` sets it for you."
+    },
+    {
+      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 shake is the flourish; the destructive colour stays at every level."
     },
     {
       name: "disabled / readOnly / required / name / id / form",
@@ -160,6 +170,12 @@ var otpFieldMeta = {
       part: "Slot",
       why: "A filled slot strengthens its border, so a pasted code visibly lands in every slot at once. Easing it reads as the code arriving rather than the field flickering."
     },
+    {
+      slot: "transition",
+      recipe: "motion-shake",
+      part: "Root",
+      why: "A refused code shakes the field once as it turns invalid \u2014 the short horizontal no that makes a second wrong code feel noticed rather than ignored. It never carries the refusal alone: the digits and borders turn destructive and the Field says why. It plays on the change to invalid, not on mount, and is expressive, so `subtle` keeps only the colour."
+    },
     {
       slot: "activity",
       recipe: "none",
@@ -171,7 +187,8 @@ var otpFieldMeta = {
     'The root is a role=group named by the field label; the first slot shares the label through `id`/`htmlFor`, and later slots are announced by position ("Character 2 of 6").',
     "Only one slot is in the tab order. Arrow keys, Home/End and Backspace move between slots; Tab leaves the whole field.",
     'The first slot carries autocomplete="one-time-code" and the numeric virtual keyboard, so iOS and Android offer the SMS code above the keyboard.',
-    "Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus."
+    "Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus.",
+    "An invalid code is never signalled by motion alone: every slot carries aria-invalid, the digits and borders turn destructive, and the Field's error message is wired through aria-describedby. The shake resolves instantly under reduced motion and `subtle`."
   ],
   examples: [
     {
@@ -186,6 +203,10 @@ var otpFieldMeta = {
       label: "With an error",
       code: '<Field label="Verification code" error="That code has expired. Request a new code and try again."><OtpField length={6} groupSize={3} defaultValue="482913" /></Field>'
     },
+    {
+      label: "Verify on completion, shake on a wrong code",
+      code: 'const [code, setCode] = useState("")\nconst [wrong, setWrong] = useState(false)\n<Field label="Verification code" error={wrong ? "That code does not match. Check the message and try again." : undefined}><OtpField length={6} groupSize={3} value={code} onValueChange={(next) => { setCode(next); setWrong(false) }} onValueComplete={(value) => setWrong(value !== expected)} /></Field>'
+    },
     {
       label: "Alphanumeric",
       code: '<Field label="Pairing code"><OtpField length={8} groupSize={4} validationType="alphanumeric" /></Field>'

package/dist/components/page-loader/page-loader.meta.js

@@ -22,7 +22,8 @@ var pageLoaderMeta = {
       },
       {
         guidance: "dont",
-        description: "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton."
+        description: "Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton.",
+        instead: ["Spinner", "Progress", "Skeleton"]
       },
       {
         guidance: "dont",

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

@@ -83,6 +83,32 @@ var panelGroupMeta = {
       description: "Controlled width for a Panel, clamped and optionally persisted to localStorage (only when `storageKey` is passed). Read through useSyncExternalStore, so there is no server/client hydration mismatch and no setState in an effect; do not hand-roll a localStorage read during render or a write from an effect. Without `storageKey` the width is kept in memory per hook instance. The third element is the `{ min, max }` it clamps to: spread it onto the paired PanelResizer so the separator's aria-valuemin/max and Home/End match the real clamp."
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Panels are the app's frame, present from first paint. A dock that slid in on load would make the workspace look like it is still assembling."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "PanelResizer",
+      why: "The hairline widens into a visible bar on hover and turns primary on keyboard focus, eased, so a 1px edge says it can be grabbed before the pointer commits."
+    },
+    {
+      slot: "transition",
+      recipe: "none",
+      part: "Panel",
+      why: "Width tracks the pointer one-to-one while dragging, and keyboard steps land at once. An eased width would trail the cursor, and resizing is a layout change: easing it would reflow the canvas beside the panel on every frame."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Layout chrome has no working state."
+    }
+  ],
   a11y: [
     "PanelResizer is a role=separator with aria-orientation, aria-valuenow/min/max, and is focusable \u2014 a pointer-only resizer is a keyboard trap.",
     "Arrow keys resize by `step`; Home and End jump to the minimum and maximum.",

package/dist/components/panel-section/panel-section.js

@@ -1,6 +1,7 @@
 "use client";
 
 // src/components/panel-section/panel-section.tsx
+import { useState } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { beginScrub } from "../../lib/scrub-gesture.js";
@@ -110,16 +111,42 @@ function PropertyPair({ labels, className, children, ...props }) {
   ] });
 }
 PropertyPair.displayName = "PropertyPair";
-function PropertyGroup({ label, summary, className, children, ...props }) {
-  return /* @__PURE__ */ jsxs(Collapsible, { className: cn("border-t border-hairline", className), ...props, children: [
-    /* @__PURE__ */ jsxs(CollapsibleTrigger, { className: "group/property-group flex h-(--control-sm) w-full items-center gap-2 rounded-xs text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [
-      /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-ui-md text-foreground", children: label }),
-      summary != null ? /* @__PURE__ */ jsx("span", { className: "flex min-w-0 shrink items-center gap-2 truncate text-ui-md text-muted-foreground", children: summary }) : null,
-      /* @__PURE__ */ jsx(Icon, { name: "plus", className: "shrink-0 text-xs text-muted-foreground group-data-[panel-open]/property-group:hidden" }),
-      /* @__PURE__ */ jsx(Icon, { name: "minus", className: "hidden shrink-0 text-xs text-muted-foreground group-data-[panel-open]/property-group:block" })
-    ] }),
-    /* @__PURE__ */ jsx(CollapsiblePanel, { children: /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-1.5 pt-0.5 pb-2", children }) })
-  ] });
+function PropertyGroup({
+  label,
+  summary,
+  className,
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  ...props
+}) {
+  const [openState, setOpenState] = useState(defaultOpen);
+  const open = openProp ?? openState;
+  return /* @__PURE__ */ jsxs(
+    Collapsible,
+    {
+      className: cn("border-t border-hairline", className),
+      open: openProp,
+      defaultOpen,
+      onOpenChange: (next, details) => {
+        setOpenState(next);
+        onOpenChange?.(next, details);
+      },
+      ...props,
+      children: [
+        /* @__PURE__ */ jsxs(CollapsibleTrigger, { className: "flex h-(--control-sm) w-full items-center gap-2 rounded-xs text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [
+          /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-ui-md text-foreground", children: label }),
+          summary != null ? /* @__PURE__ */ jsx("span", { className: "flex min-w-0 shrink items-center gap-2 truncate text-ui-md text-muted-foreground", children: summary }) : null,
+          /* @__PURE__ */ jsxs("span", { "aria-hidden": "true", className: "motion-icon-swap shrink-0 text-xs text-muted-foreground", children: [
+            /* @__PURE__ */ jsx("span", { "data-active": !open, className: "inline-flex", children: /* @__PURE__ */ jsx(Icon, { name: "plus" }) }),
+            /* @__PURE__ */ jsx("span", { "data-active": open, className: "inline-flex", children: /* @__PURE__ */ jsx(Icon, { name: "minus" }) })
+          ] })
+        ] }),
+        /* @__PURE__ */ jsx(CollapsiblePanel, { children: /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-1.5 pt-0.5 pb-2", children }) })
+      ]
+    }
+  );
 }
 PropertyGroup.displayName = "PropertyGroup";
 export {

package/dist/components/panel-section/panel-section.meta.js

@@ -101,6 +101,38 @@ var panelSectionMeta = {
       description: "A collapsible set of properties inside a section, at the panel's scale (an Accordion is page furniture). The row shows the label, then the summary (the group's value, readable while closed: a word, a few swatches, or both), then a + that turns to \u2212 when open. Groups open independently and stack with a hairline between them. Built on Collapsible."
     }
   ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Sections are part of the inspector they sit in and arrive with it. Animating each in would make a panel switch look like a page load."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "PropertyGroup trigger",
+      why: "The fold row eases its focus ring, so arrowing down a dense inspector shows where the keyboard is without the ring flickering from row to row."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-disclosure",
+      part: "PropertyGroup panel",
+      why: "The group opens by easing its height, so the rows below slide down to make room instead of jumping. In an inspector, the next section moving is otherwise how you lose your place."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-icon-swap",
+      part: "PropertyGroup indicator",
+      why: "The + collapses into \u2212 as the group opens, both glyphs stacked as one mark, so the indicator reads as this row changing state rather than a different icon landing."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "The inspector edits values in place; nothing in it loads."
+    }
+  ],
   a11y: [
     "PropertyGroup's row is a real button with aria-expanded (Collapsible); its summary is part of the button's name, so a closed group still announces its value.",
     "PropertyRow renders a real <label>; pass htmlFor with the control's id so clicking the label focuses it.",