@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/toast.js

@@ -36,6 +36,27 @@ const toastVariants = cva(
     },
     defaultVariants: { variant: 'default' },
 });
+/**
+ * The opacity transitions currently running on one element, or `null` when the
+ * browser cannot be asked.
+ *
+ * `null` and an empty array are different answers and the difference is the whole
+ * point of the function. An empty array says the browser has nothing running,
+ * which is what `transition: none` looks like from inside; `null` says the
+ * browser cannot report, and a caller that treated that as "nothing is running"
+ * would hand over on every leave in a browser without the Web Animations API and
+ * take the fade with it.
+ *
+ * Read on the element and never on its subtree, because the dismiss control runs
+ * an opacity transition of its own and a subtree read would report the button's
+ * fade as the toast's.
+ */
+function opacityTransitions(element) {
+    if (typeof element.getAnimations !== 'function')
+        return null;
+    const isOpacity = (animation) => animation.transitionProperty === 'opacity';
+    return element.getAnimations().filter(isOpacity);
+}
 /**
  * A transient notification for something the reader did not have to be told.
  *
@@ -85,16 +106,32 @@ const toastVariants = cva(
  * have.
  *
  * **It never removes its own transition, and the reason is the caller's
- * unmount.** The exit hands over on the end of the root's own opacity
- * transition, so under reduced motion the fade is *shortened* rather than
- * removed and the handoff still happens. Removing the fade there would have
- * needed this Component to read the media query and hand over at once instead,
- * which would be the same rule written twice: once in the stylesheet and once in
- * TypeScript, free to disagree the day the motion policy is retuned. Leaving
- * the fade in and shortening it keeps the decision in one place, and it is the
- * same choice `DESIGN.md` states for the package: motion is state feedback,
- * shortened rather than removed under reduced motion. The travel is the part
- * that is movement, so that is the part `motion-safe:` guards.
+ * unmount.** The enter and the leave are shortened rather than removed under
+ * reduced motion, and shortening them there would have needed this Component to
+ * read the media query and hand over at once instead, which would be the same
+ * rule written twice: once in the stylesheet and once in TypeScript, free to
+ * disagree the day the motion policy is retuned. It does not read it. It also
+ * does not guard the travel at the call site any more, because
+ * `packages/ui/src/styles.css` stops every transition and every animation under
+ * `prefers-reduced-motion` in one unlayered rule, and a `motion-safe:` beside an
+ * unguarded `transition-[opacity,transform]` was the shape `RangeField` shipped:
+ * a guard that adds a rule and therefore cannot remove one. The rise is movement
+ * and it is stopped, the fade is stopped with everything else, and the exit is
+ * asked about rather than assumed, which is what the paragraph below is for.
+ *
+ * **The leave is handed over whether or not the fade runs, and that is the
+ * contract `styles.css` states for the whole package.** `packages/ui/src/styles.css`
+ * says there is no state anywhere in this system whose exit depends on an animation
+ * running to completion, and this Component is where that was not true: the exit
+ * waited on `transitionend` and nothing else. A consumer's global
+ * `transition: none` broke it first, and the reduced-motion block at the foot of
+ * that stylesheet breaks it now that it names transitions as well as animations, so
+ * a toast stranded in `leaving` was and would be visible, undismissable and still
+ * inside a live region. So the exit asks the browser what is actually running on
+ * the root rather than waiting for an event that a killed transition never sends:
+ * it waits for the fade when there is a fade, it hands over on the same commit when
+ * there is not, and `onDismiss` is called exactly once either way. This Component is
+ * the reason the one unlayered rule above it is safe to ship.
  *
  * **It is a client Component** because it holds a clock, runs effects, and
  * attaches three handlers. The clock is a single `setTimeout` whose
@@ -180,47 +217,111 @@ function Toast({ className, variant, title, description, action, onDismiss, dura
         // is one call rather than one per reason the toast was dismissed.
         setPhase((current) => (current === 'leaving' ? current : 'leaving'));
     }, []);
+    /**
+     * Whether the caller has already been told, and a guard on the Component
+     * rather than on the effect below.
+     *
+     * A local flag in that effect would be a fresh `false` every time the effect
+     * re-runs, and it re-runs whenever `onDismiss` changes identity, which a caller
+     * writing an inline arrow does on every render. The thing this protects is the
+     * caller's unmount, and an unmount that runs twice is a state update against a
+     * Component that is already gone.
+     */
+    const handedOver = useRef(false);
     useEffect(() => {
         if (phase !== 'leaving')
             return;
         const root = rootRef.current;
         if (root === null)
             return;
-        // The leave ends when the transition the CSS declared has run, and not on a
-        // second clock of this Component's own: the length of the leave is a CSS
-        // decision, and a number in TypeScript would be a second source of truth
-        // for it that would stop agreeing with the stylesheet the day the token
-        // moved.
-        //
-        // It is the root's own opacity rather than "the first transition to end",
-        // and that holds under reduced motion too. The fade is shortened there and
-        // not removed, so an opacity transition always runs and always ends, and the
-        // caller is always told to unmount. Reading the media query in JavaScript
-        // would put the same decision in two places: the stylesheet would shorten
-        // the fade and this code would have to guess the same rule to know whether
-        // to expect the event.
-        //
-        // A `const` arrow and not a hoisted declaration, for one reason that is not
-        // taste: a function declaration could be called before the null check above
-        // ran, so TypeScript drops the narrowing on `root` inside it, while an arrow
-        // assigned to a `const` cannot exist until the check has passed.
+        /**
+         * The one call, whichever of the two signals asked for it.
+         */
+        const settle = () => {
+            if (handedOver.current)
+                return;
+            handedOver.current = true;
+            onDismiss?.();
+        };
+        /**
+         * The event, for a browser that runs the fade.
+         *
+         * Filtered to this element's own opacity, because a child control's colour
+         * transition would otherwise end the toast's exit early and the caller would
+         * unmount it half way through the fade. Removed on the way through, because
+         * the phase does not change on the way out and so this effect is not re-run
+         * to clean up; a listener left attached would call the caller's unmount again
+         * on the next opacity transition on this element.
+         *
+         * A `const` arrow and not a hoisted declaration, for one reason that is not
+         * taste: a function declaration could be called before the null check above
+         * ran, so TypeScript drops the narrowing on `root` inside it, while an arrow
+         * assigned to a `const` cannot exist until the check has passed.
+         */
         const finish = (event) => {
-            // Filtered to this element's own opacity, because a child control's
-            // colour transition would otherwise end the toast's exit early and the
-            // caller would unmount it half way through the fade.
             if (event.target !== root)
                 return;
             if (event.propertyName !== 'opacity')
                 return;
-            // Removed on the way through, because the phase does not change on the
-            // way out and so this effect is not re-run to clean up. A listener left
-            // attached would call the caller's unmount again on the next opacity
-            // transition on this element, and an unmount that runs twice is a state
-            // update on a component that is no longer there.
             root.removeEventListener('transitionend', finish);
-            onDismiss?.();
+            settle();
         };
         root.addEventListener('transitionend', finish);
+        /**
+         * The animation, for the case where the event never arrives.
+         *
+         * **This is the one that makes the handoff independent of the fade rather than
+         * merely early, and the reason it exists is a transition that is stopped rather
+         * than shortened.** A reduced-motion kill is written two ways: as a duration of
+         * `0.01ms`, which still starts a transition and still ends it, or as
+         * `transition: none`, which starts nothing at all. Under the second form
+         * `transitionend` never fires, and an exit that waits only for that event
+         * leaves the toast in `data-phase="leaving"` for good: still on the page,
+         * still taking the pointer, and still inside a live region that has not
+         * stopped announcing. `styles.css` states the invariant this broke, that no
+         * state in this system has an exit that depends on an animation running to
+         * completion, and this Component was the one place it was not true. That block
+         * now writes `transition: none` itself, under `prefers-reduced-motion`, which
+         * is why this was repaired before it was needed rather than after.
+         *
+         * **The browser is asked, not guessed at.** `getAnimations()` returns what is
+         * actually running on this element, so it answers the question the stylesheet
+         * already answered: with the transition stopped there is nothing in it and the
+         * handoff happens at once, and with the fade running there is one transition
+         * and the handoff waits for it. Reading the media query in JavaScript instead
+         * would put one decision in two places, free to disagree the day the motion
+         * policy is retuned, and a reader who asked for less motion is not a reader
+         * whose toast should hang.
+         *
+         * **It settles on the animation and not on a clock, for the reason the exit
+         * has no number in it.** The length of the leave is a CSS decision taken by
+         * `duration-slow` above, and a timer here would be a second source of truth
+         * for it that would stop agreeing with the stylesheet the day the token moved.
+         * The animation carries the same length the CSS declared, so waiting on it
+         * keeps one answer to "how long does this leave run for".
+         *
+         * A rejected `finished` is a settled leave rather than an error: a cancelled
+         * or replaced animation is one that will not finish, and waiting on it is the
+         * way a toast gets stranded.
+         *
+         * Only this element's own animations are read, because `getAnimations()` is
+         * not asked for the subtree. The dismiss control runs its own opacity
+         * transition, and a subtree read would hand the toast's exit to a button.
+         *
+         * A `null` answer is left to do nothing: a browser that cannot be asked keeps
+         * the event as the only signal there is, which is the behaviour this Component
+         * had before and the only one it can have there.
+         */
+        const fade = opacityTransitions(root);
+        if (fade !== null && fade.length === 0) {
+            // Nothing is running, so nothing will end: no transition was ever created.
+            // This is the strand the whole block exists to prevent, and it settles on
+            // the same commit rather than waiting for an event that is not coming.
+            settle();
+        }
+        else if (fade !== null) {
+            Promise.all(fade.map((animation) => animation.finished)).then(settle, settle);
+        }
         return () => root.removeEventListener('transitionend', finish);
     }, [phase, onDismiss]);
     const onKeyDown = (event) => {
@@ -251,16 +352,18 @@ function Toast({ className, variant, title, description, action, onDismiss, dura
         // the page and a fast one is over before a reader has registered that
         // anything arrived; `ease-out` because both directions are decelerating
         // into a resting state rather than accelerating out of one.
-        'transition-[opacity,transform] duration-slow ease-out', 
-        // Reduced motion shortens the fade and removes the travel, rather than
-        // removing the transition. The fade is what tells a reader the toast is
-        // there and then that it is gone, and a reader who asked for less motion
-        // has not asked to be told nothing; the rise is movement, and movement is
-        // what they asked not to have. It is also why the handoff below waits on
-        // an opacity transition rather than reading the media query in JavaScript:
-        // an opacity that always transitions always ends, so there is no case in
-        // which the caller is never told to unmount.
-        'motion-reduce:duration-fast', 'motion-safe:data-[phase=entering]:translate-y-1 motion-safe:data-[phase=leaving]:translate-y-1', 'data-[phase=entering]:opacity-0 data-[phase=leaving]:opacity-0', className), ...props, children: [_jsxs("div", { "data-slot": "toast-body", className: "flex min-w-0 flex-1 flex-col gap-1", children: [title === undefined ? null : (_jsx("p", { "data-slot": "toast-title", className: "text-sm font-medium", children: title })), description === undefined ? null : (_jsx("p", { "data-slot": "toast-description", className: "text-pretty text-sm opacity-90", children: description })), action === undefined ? null : (_jsx("div", { "data-slot": "toast-action", className: "mt-1.5 flex items-center", children: action }))] }), showCloseButton && canLeave ? (_jsx("button", { type: "button", "data-slot": "toast-close", "aria-label": closeLabel, onClick: dismiss, 
+        'transition-[opacity,transform] duration-slow ease-out', 'data-[phase=entering]:opacity-0 data-[phase=leaving]:opacity-0', 
+        /*
+         * No `motion-safe:` here and no `motion-reduce:`. `styles.css` ends with one
+         * unlayered `prefers-reduced-motion` rule that stops every transition in the
+         * package, so a guard here would either be inert (beside an unguarded
+         * `transition-*`, which is what this Component used to carry) or a second
+         * place to retune the policy. A toast under reduced motion appears at its
+         * final opacity with no rise and leaves with no fade, and the arrival is
+         * still announced by the live region, which is the part the reader cannot
+         * do without and the part no transition was carrying.
+         */
+        className), ...props, children: [_jsxs("div", { "data-slot": "toast-body", className: "flex min-w-0 flex-1 flex-col gap-1", children: [title === undefined ? null : (_jsx("p", { "data-slot": "toast-title", className: "text-sm font-medium", children: title })), description === undefined ? null : (_jsx("p", { "data-slot": "toast-description", className: "text-pretty text-sm opacity-90", children: description })), action === undefined ? null : (_jsx("div", { "data-slot": "toast-action", className: "mt-1.5 flex items-center", children: action }))] }), showCloseButton && canLeave ? (_jsx("button", { type: "button", "data-slot": "toast-close", "aria-label": closeLabel, onClick: dismiss, 
                 // The ring is at full strength for the reason `Button`'s is: half alpha
                 // composites to under 3:1 against every surface in every pack, and this
                 // is the one indicator on a control a reader reaches for without

package/dist/components/ui/toggle-group.d.ts

@@ -25,12 +25,21 @@ export interface ToggleGroupProps extends Omit<ComponentProps<'div'>, 'onChange'
     /**
      * The group's accessible name.
      *
-     * Required rather than defaulted. A group of toggles with no name is announced
-     * as an unnamed group, and a toolbar with two of them is a toolbar where a
-     * reader cannot tell which set of controls they are in. The name is the
-     * caller's word, for the reason every region's name in this package is.
+     * Required, and required by the type rather than only by this paragraph, which is
+     * the whole of the change: it was declared optional while the sentence beneath it
+     * said "Required rather than defaulted", so TypeScript enforced nothing and the
+     * group shipped unnamed. Both roles this Component draws are ones ARIA names a
+     * MUST for, and both announce as their bare role name when unnamed: a reader
+     * tabbing onto a toolbar with two of them is told "toolbar" and has no way to ask
+     * which set of controls they have reached, and a radiogroup with no name says
+     * nothing about which question its radios are answering. `TextFormatToolbar` draws
+     * the same role with a required `label`, which is the shape this now matches.
+     *
+     * The name is the caller's word, for the reason every region's name in this package
+     * is. `aria-labelledby` also arrives through `...props`, so a caller whose name is
+     * already drawn somewhere can point at it rather than repeat it.
      */
-    'aria-label'?: string;
+    'aria-label': string;
     /** The direction the arrow keys move in. @defaultValue 'horizontal' */
     orientation?: 'horizontal' | 'vertical';
     /** Layout only. */

package/dist/components/ui/toggle-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toggle-group.d.ts","sourceRoot":"","sources":["../../../src/components/ui/toggle-group.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId,gEAAgE;AAChE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,UAAU,CAAA;AAE5D,yCAAyC;AACzC,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAC5F,kDAAkD;IAClD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,wBAAwB,CAAA;IACxC,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAClD,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAChG;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iBAAS,WAAW,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,aAAwB,EACxB,KAAK,EACL,YAAY,EACZ,aAAa,EACb,QAAgB,EAChB,WAA0B,EAC1B,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoHlB;AAED;;;;;;;;;;GAUG;AACH,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,oBAAoB,+BAiDtB;AAED,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"toggle-group.d.ts","sourceRoot":"","sources":["../../../src/components/ui/toggle-group.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId,gEAAgE;AAChE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,UAAU,CAAA;AAE5D,yCAAyC;AACzC,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAC5F,kDAAkD;IAClD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,wBAAwB,CAAA;IACxC,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,mEAAmE;IACnE,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,2EAA2E;IAC3E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAClD,qDAAqD;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;IACvC,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAChG;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iBAAS,WAAW,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,aAAwB,EACxB,KAAK,EACL,YAAY,EACZ,aAAa,EACb,QAAgB,EAChB,WAA0B,EAC1B,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAwHlB;AAED;;;;;;;;;;GAUG;AACH,iBAAS,eAAe,CAAC,EACvB,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,oBAAoB,+BA2DtB;AAED,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,CAAA"}

package/dist/components/ui/toggle-group.js

@@ -130,6 +130,10 @@ function ToggleGroup({ children, className, selectionMode = 'single', value, def
         // reasons the multiple mode is a toolbar: a toolbar is the role that says
         // "a set of controls operated with the arrow keys", and it is the role that
         // carries an orientation.
+        //
+        // Both of those roles are announced by their bare name when nothing names
+        // them, which is why `aria-label` is a required prop rather than an optional
+        // one; see the prop.
         role: selectionMode === 'multiple' ? 'toolbar' : 'radiogroup', "aria-orientation": orientation, onKeyDown: (event) => {
             const back = BACKWARD[orientation].includes(event.key);
             if (!back && !FORWARD[orientation].includes(event.key))
@@ -189,6 +193,16 @@ function ToggleGroupItem({ className, value, disabled, children, ...props }) {
         // Both state surfaces set their own ink, for the reason `Toggle` states: an
         // inherited ink is the same control on the page ground and a different one
         // inside a Block.
-        'data-[pressed]:bg-accent data-[pressed]:text-accent-foreground', inert ? 'cursor-not-allowed opacity-50' : '', className), ...props, children: children }));
+        'data-[pressed]:bg-accent data-[pressed]:text-accent-foreground', 
+        // The coarse-pointer floor, as a step with `min-w-11` on the other axis, and
+        // a band is the worst of the three answers here. These are the members of one
+        // segmented set, so they sit directly beside each other: a 44px band on one
+        // member is a press aimed at its neighbour, which is condition 1 of the three
+        // in `DESIGN.md` failing outright. `min-w-11` is the width half for the reason
+        // `Button` gives, since an icon-only member is `size-4` plus `px-2.5` and would
+        // otherwise stay under the floor across. The cost is that the group is 44 tall
+        // on touch rather than 32, and it is paid uniformly because the class is on the
+        // member and every member carries it. See DESIGN.md, The coarse-pointer floor.
+        'pointer-coarse:h-11 pointer-coarse:min-w-11', inert ? 'cursor-not-allowed opacity-50' : '', className), ...props, children: children }));
 }
 export { ToggleGroup, ToggleGroupItem };

package/dist/components/ui/toggle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toggle.d.ts","sourceRoot":"","sources":["../../../src/components/ui/toggle.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C,mCAAmC;AACnC,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA;AAEzC;;;;;GAKG;AACH;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACvF,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC5C,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,IAAgB,EAChB,OAAO,EACP,cAAc,EACd,eAAe,EACf,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,WAAW,+BA4Bb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"toggle.d.ts","sourceRoot":"","sources":["../../../src/components/ui/toggle.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAI3C,mCAAmC;AACnC,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,CAAA;AAEzC;;;;;GAKG;AACH;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IACvF,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC5C,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iBAAS,MAAM,CAAC,EACd,SAAS,EACT,IAAgB,EAChB,OAAO,EACP,cAAc,EACd,eAAe,EACf,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,WAAW,+BAoCb;AAED,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/ui/toggle.js

@@ -37,7 +37,15 @@ function Toggle({ className, size = 'default', pressed, defaultPressed, onPresse
         // Both state surfaces set their own ink, which is the rule a variant that
         // sets a fill must follow. A pressed surface with an inherited ink is the
         // same control on the page ground and a different one inside a Block.
-        'hover:bg-accent hover:text-accent-foreground', 'data-[pressed]:bg-accent data-[pressed]:text-accent-foreground', size === 'sm' ? 'h-8 min-w-8 px-2.5' : 'h-9 min-w-9 px-3', className), ...(pressed === undefined ? null : { pressed }), ...(defaultPressed === undefined ? null : { defaultPressed }), ...(onPressedChange === undefined
+        'hover:bg-accent hover:text-accent-foreground', 'data-[pressed]:bg-accent data-[pressed]:text-accent-foreground', 
+        // The coarse-pointer floor, as a step with `min-w-11` on the other axis, and a
+        // band is rejected on condition 1 for the reason `toggle-group.tsx` rejects one:
+        // a `Toggle` is most often one member of a row or a set, and a 44px band on it is
+        // a press aimed at whatever sits beside it. `min-w-11` is the width half for the
+        // reason `Button` gives, since an icon-only toggle is `size-4` plus `px-2.5` and
+        // would otherwise stay under the floor across. See DESIGN.md, The coarse-pointer
+        // floor.
+        'pointer-coarse:h-11 pointer-coarse:min-w-11', size === 'sm' ? 'h-8 min-w-8 px-2.5' : 'h-9 min-w-9 px-3', className), ...(pressed === undefined ? null : { pressed }), ...(defaultPressed === undefined ? null : { defaultPressed }), ...(onPressedChange === undefined
             ? null
             : { onPressedChange: (next) => onPressedChange(next) }), ...(disabled === undefined ? null : { disabled }), ...props }));
 }

package/dist/components/ui/tree.d.ts

@@ -109,6 +109,14 @@ export interface TreeProps {
  * are specific to a documentation rail and are reasoned at length in the design
  * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
  * Page composes this Component later is a decision this ticket does not make.
+ *
+ * **Nothing collapses, so nothing claims to.** There is no `open` set, no
+ * `aria-expanded` on a node and no arrow that folds a subtree away. The attribute
+ * was on every group with children, hard-coded to `true`, and it promised a second
+ * press that did nothing: a reader who hears "expanded" and presses to collapse
+ * has been told about a control this Component does not have. ARIA's own wording
+ * covers the case, that a node which cannot expand omits the attribute, and `aria-level`
+ * is what places a node in the tree for a reader who wants that instead.
  */
 declare function Tree({ nodes, currentHref, label, className, empty }: TreeProps): import("react").JSX.Element;
 export { Tree };

package/dist/components/ui/tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tree.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;AAErE,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;CAChD;AAqKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,iBAAS,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,SAAS,+BAkEvE;AAED,OAAO,EAAE,IAAI,EAAE,CAAA"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/components/ui/tree.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIzF;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,OAAO,CAAA;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;CAC3B,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,eAAe,CAAA;AAErE,kCAAkC;AAClC,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,CAAA;CAChD;AAkOD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iBAAS,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,SAAS,+BAqGvE;AAED,OAAO,EAAE,IAAI,EAAE,CAAA"}

package/dist/components/ui/tree.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef } from 'react';
+import { useCallback, useRef, useState } from 'react';
 import { cn } from '../../lib/utils.js';
 /** Whether a group's subtree contains the current address, at any depth. */
 function containsHref(nodes, currentHref) {
@@ -24,19 +24,45 @@ function under(href, currentHref) {
         return false;
     return currentHref === href || currentHref.startsWith(`${href}/`);
 }
-function TreeLevel({ nodes, currentHref, depth, }) {
+function TreeLevel({ nodes, currentHref, depth, tabStopFor, onFocusNode, }) {
     return (_jsx("ul", { "data-slot": "tree-list", "data-depth": depth, 
         // `group` on the list, not `treeitem`: the items are the things a reader
         // navigates between, and a `ul` of them is a group. `role="none"` on each
-        // item below removes the listitem role so that only the anchors and labels
-        // are the navigable things, which is what lets a caller's own keyboard model
-        // move between them without a roving tabindex fighting the document's.
+        // item below removes the listitem role, and a `<div>` is a generic element,
+        // which is transparent in the accessibility tree. So both are passed through
+        // and each anchor is owned by the group rather than by the wrapper around it,
+        // which is why `aria-level` is redundant here and load-bearing for a reader
+        // who is placed by the level rather than by the nesting.
         role: "group", className: cn('border-border flex flex-col gap-1 border-l', 
         // One level of indent per nested group and none at the top, so the depth
         // reads from the rule rather than from the words.
-        depth > 0 && 'ps-3'), children: nodes.map((node, index) => (_jsx(TreeItem, { node: node, currentHref: currentHref, depth: depth }, `${node.type}:${index}`))) }));
+        depth > 0 && 'ps-3'), children: nodes.map((node, index) => (_jsx(TreeItem, { node: node, currentHref: currentHref, depth: depth, tabStopFor: tabStopFor, onFocusNode: onFocusNode }, `${node.type}:${index}`))) }));
 }
-function TreeItem({ node, currentHref, depth, }) {
+/**
+ * The address of the first node a reader could focus, in the order they meet them.
+ *
+ * Depth first, because that is the order `TreeLevel` renders in and the order the
+ * arrow keys collect from the DOM, so this is the same walk the reader sees rather
+ * than a second list to fall behind it. It exists for one state: before the reader
+ * has been in the tree at all, the tab stop has to be resolved during the first
+ * render, because a ref is not attached yet and a stop read from the DOM has none on
+ * the first paint.
+ */
+function firstHref(nodes) {
+    for (const node of nodes) {
+        if (node.type === 'page')
+            return node.href;
+        if (node.type === 'group') {
+            if (node.href !== undefined)
+                return node.href;
+            const below = firstHref(node.items);
+            if (below !== undefined)
+                return below;
+        }
+    }
+    return undefined;
+}
+function TreeItem({ node, currentHref, depth, tabStopFor, onFocusNode, }) {
     if (node.type === 'divider') {
         // A rule between nodes. It is a label, so it is not focusable and a reader
         // does not meet it as a destination, and the empty title renders no words
@@ -44,7 +70,11 @@ function TreeItem({ node, currentHref, depth, }) {
         return (_jsx("li", { "data-slot": "tree-divider", role: "none", className: "border-border mt-2 border-t pt-2 first:mt-0 first:border-t-0 first:pt-0", children: node.title ? (_jsx("span", { className: "text-muted-foreground text-xs font-medium tracking-wide uppercase", children: node.title })) : null }));
     }
     if (node.type === 'group') {
-        return (_jsx("li", { "data-slot": "tree-group", role: "none", children: _jsxs("div", { className: "flex flex-col gap-1", children: [node.href === undefined ? (
+        // Read once into a `const` because TypeScript does not carry a narrowing of
+        // `node.href` into a callback, and the roving tab stop and the focus handler
+        // below are both callbacks that need the address as a `string`.
+        const href = node.href;
+        return (_jsx("li", { "data-slot": "tree-group", role: "none", children: _jsxs("div", { className: "flex flex-col gap-1", children: [href === undefined ? (
                     /*
                      * A group with no index is a tree item that is not a destination, so it
                      * carries `role="treeitem"` and its level and nothing else. It is not a
@@ -52,14 +82,28 @@ function TreeItem({ node, currentHref, depth, }) {
                      * rather than ignored, which the accessibility gate caught the first
                      * time this was rendered, and a reader needs the level to place a label
                      * that has no anchor to place it by.
+                     *
+                     * It carries no `aria-expanded`, and neither arm below does. The
+                     * attribute says whether a node's children are on the page, and there is
+                     * no collapse anywhere in this Component: every group renders its
+                     * subtree, so the honest value is always "expanded" and the useful one
+                     * is none at all. `aria-expanded="true"` on a node a reader presses and
+                     * nothing happens is worse than silence, because it promises a second
+                     * press. ARIA's own wording covers this case: a node that cannot expand
+                     * omits the attribute. The level is what places a label that has no
+                     * anchor to place it by.
                      */
-                    _jsx("span", { "data-slot": "tree-label", role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(node.items, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })) : (_jsx("a", { "data-slot": "tree-heading", href: node.href, role: "treeitem", "aria-level": depth + 1, "aria-expanded": node.items.length > 0 ? true : undefined, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(node.href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })), node.items.length > 0 ? (_jsx(TreeLevel, { nodes: node.items, currentHref: currentHref, depth: depth + 1 })) : null] }) }));
+                    _jsx("span", { "data-slot": "tree-label", role: "treeitem", "aria-level": depth + 1, className: cn('rounded-sm text-sm font-semibold tracking-tight', containsHref(node.items, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })) : (_jsx("a", { "data-slot": "tree-heading", href: href, role: "treeitem", "aria-level": depth + 1, "aria-current": currentHref === href ? 'page' : undefined, 
+                        // The roving tab stop, as `ToggleGroup` holds it. See the JSDoc on the
+                        // Component for why a tree of forty links is one Tab stop rather than
+                        // forty.
+                        tabIndex: tabStopFor(href) ? 0 : -1, onFocus: () => onFocusNode(href), className: cn('hover:text-foreground rounded-sm text-sm font-semibold tracking-tight transition-colors duration-fast ease-out', under(href, currentHref) ? 'text-foreground' : 'text-muted-foreground'), children: node.title })), node.items.length > 0 ? (_jsx(TreeLevel, { nodes: node.items, currentHref: currentHref, depth: depth + 1, tabStopFor: tabStopFor, onFocusNode: onFocusNode })) : null] }) }));
     }
     return (_jsx("li", { "data-slot": "tree-item", role: "none", children: _jsx("a", { "data-slot": "tree-link", href: node.href, 
             // A destination in a tree is a `treeitem`, not a link with a level hung
             // off it: the level belongs to the item, and a reader placing it in the
             // tree is reading the item rather than the anchor inside it.
-            role: "treeitem", "aria-level": depth + 1, "aria-current": currentHref === node.href ? 'page' : undefined, className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === node.href
+            role: "treeitem", "aria-level": depth + 1, "aria-current": currentHref === node.href ? 'page' : undefined, tabIndex: tabStopFor(node.href) ? 0 : -1, onFocus: () => onFocusNode(node.href), className: cn('-ms-px block border-l-2 py-1 ps-3 text-sm transition-colors duration-fast ease-out', currentHref === node.href
                 ? 'text-foreground border-primary font-medium'
                 : 'text-muted-foreground hover:text-foreground border-transparent'), children: node.title }) }));
 }
@@ -84,17 +128,52 @@ function TreeItem({ node, currentHref, depth, }) {
  * are specific to a documentation rail and are reasoned at length in the design
  * rules. A documentation rail is one shape a tree takes, not the shape. Whether the
  * Page composes this Component later is a decision this ticket does not make.
+ *
+ * **Nothing collapses, so nothing claims to.** There is no `open` set, no
+ * `aria-expanded` on a node and no arrow that folds a subtree away. The attribute
+ * was on every group with children, hard-coded to `true`, and it promised a second
+ * press that did nothing: a reader who hears "expanded" and presses to collapse
+ * has been told about a control this Component does not have. ARIA's own wording
+ * covers the case, that a node which cannot expand omits the attribute, and `aria-level`
+ * is what places a node in the tree for a reader who wants that instead.
  */
 function Tree({ nodes, currentHref, label, className, empty }) {
     const root = useRef(null);
+    // The roving tab stop, held as an address rather than as an index, for the reason
+    // `ToggleGroup` holds a value rather than a position: a caller who reorders or
+    // removes nodes must not strand the reader on a node that moved.
+    const [stop, setStop] = useState(null);
+    /**
+     * Which node holds the tree's one tab stop.
+     *
+     * `null` is the "the reader has not been here yet" case, and it resolves to the
+     * current address rather than to the first node, which is the same rule
+     * `ToggleGroup` applies to a pressed member and for the same reason: a rail that
+     * Tab lands on the top of while the page is forty nodes down is a rail that
+     * reports the wrong place through the tab order alone, and a keyboard reader
+     * arriving from the content has no other way to be placed.
+     *
+     * The first destination is the fallback rather than a second answer, so it applies
+     * only when the current address is not in this tree. A `currentHref` naming
+     * another page is ordinary: a consumer holding a route that is not one of its own
+     * nodes. Two tab stops is the failure that reading either rule alone would produce.
+     */
+    const tabStopFor = useCallback((href) => {
+        if (stop !== null)
+            return stop === href;
+        if (currentHref !== undefined && containsHref(nodes, currentHref))
+            return href === currentHref;
+        return firstHref(nodes) === href;
+    }, [currentHref, nodes, stop]);
     /**
      * The keyboard model, and the reason it lives here rather than in a caller's.
      *
      * A tree is one Tab stop, and the arrow keys move inside it. That is the ARIA
      * pattern, and a consumer who composes the markup themselves gets the Tab order
      * of the document instead, which is every node in the tree and none of the
-     * arrows. A roving tabindex is the mechanism: one node is tabbable at a time and
-     * the arrows move which one.
+     * arrows. The roving tabindex above is the mechanism: one node is tabbable at a
+     * time, and the arrows move which one, because the arrow handler moves focus and
+     * `onFocus` on each node moves the stop with it.
      *
      * The flat order is collected from the DOM rather than computed from the node
      * data, because the DOM is what a reader actually moves through and computing a
@@ -132,6 +211,6 @@ function Tree({ nodes, currentHref, label, className, empty }) {
         // case is authored rather than left for a caller to notice.
         return (_jsxs("div", { "data-slot": "tree-empty", className: cn('text-muted-foreground text-sm', className), children: [empty?.message ?? null, empty?.action] }));
     }
-    return (_jsx("div", { "data-slot": "tree", ref: root, role: "tree", "aria-label": label, onKeyDown: onKeyDown, className: cn('flex flex-col', className), children: _jsx(TreeLevel, { nodes: nodes, currentHref: currentHref, depth: 0 }) }));
+    return (_jsx("div", { "data-slot": "tree", ref: root, role: "tree", "aria-label": label, onKeyDown: onKeyDown, className: cn('flex flex-col', className), children: _jsx(TreeLevel, { nodes: nodes, currentHref: currentHref, depth: 0, tabStopFor: tabStopFor, onFocusNode: setStop }) }));
 }
 export { Tree };