@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/repo-stars.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The two steps a star readout is drawn at, as frame and figure together.
+ *
+ * The pair moves as one because a readout is a figure with a unit attached to it
+ * and the two are read as one sentence: a count at the `sm` step beside a noun
+ * at the `md` step is a count and a caption, and a reader scanning a page of them
+ * sees the numbers at one height and the nouns at another. `sm` is for a footer,
+ * a table row and a card description, and `md` is for a card header and a page
+ * header. There is no third step because a star count is never the headline
+ * figure of a page, and a Component that could be drawn at the title step would
+ * be a Component asking to be the thing it annotates.
+ */
+const REPO_STARS_SIZE = {
+    sm: 'items-center gap-1 text-xs',
+    md: 'items-center gap-1.5 text-sm',
+};
+/**
+ * The two halves of a readout, drawn once for the span and once for the anchor.
+ *
+ * A part rather than an Item, and it stays inside this module: DESIGN.md's
+ * authoring contract says compound parts ship from their parent module and do
+ * not form a second vocabulary, so this is a module-local function and not a
+ * fourth export. It exists because the mark has to sit inside the anchor when
+ * there is one, so that the whole readout is the hit area rather than the figure
+ * with a dead mark beside it, and writing the two spans twice is two places to
+ * change them.
+ */
+function StarBody({ mark, figure, className }) {
+    return (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "repo-stars-mark", className: "flex size-4 shrink-0 items-center justify-center", children: mark }), _jsx("span", { "data-slot": "repo-stars-figure", className: cn('min-w-0 truncate font-medium tabular-nums', className), children: figure })] }));
+}
+/**
+ * How many people starred a source repository, beside the host's own mark.
+ *
+ * **The mark is a slot and the reason is a licence, not a preference.** Prism's
+ * icon lane is Lucide, and Lucide draws interface glyphs rather than other
+ * companies' trademarks, and a repository host's mark is a licensed asset with
+ * rules about its clear space, its colour, its minimum size and where it may
+ * appear. A package that shipped one would be distributing an asset it does not
+ * own, and it would be wrong within a year as hosts redraw. So the consumer passes
+ * the mark and this Component draws the frame around it. The cost is stated
+ * rather than hidden: a consumer who wants the readout in an afternoon has to
+ * source the mark, and a consumer with no host to point at cannot use this
+ * Component at all.
+ *
+ * **The count is printed by a callback and the fallback is the bare number.**
+ * There is no `Intl` default and the omission is the decision, for the reason
+ * `format` states: a compact count is a locale and a judgement, and a figure
+ * formatted in the runtime's locale changes when the deployment region changes.
+ * The visible cost is that a consumer with a six figure count and no formatter
+ * draws all six digits, which is honest and wider than they wanted.
+ *
+ * **There is no navigation region and no landmark, and the reason is that a
+ * count is not a place.** A `<nav>` is a set of routes and this is one figure
+ * beside a mark, so the readout renders a span or an anchor and nothing else. A
+ * consumer who puts one inside their own `<nav>` has made a claim about their own
+ * page that Prism neither makes nor checks, and the `href` is the consumer's to
+ * resolve: this Component validates nothing about it, and the package is router
+ * free and transport free by design.
+ *
+ * **A link here is an anchor, so there is no `target` and no `rel`.** Both belong
+ * to the anchor and the anchor is inside the readout, and an anchor-shaped root
+ * that changed element with `href` would put `rel` and `target` onto a `span` on
+ * every readout that has no link, which is invalid markup for a control Prism
+ * did not draw. A consumer who needs a new tab or a referrer policy writes their
+ * own anchor around the readout, which is one element and keeps every class here.
+ *
+ * **The link's ink is `brand-ink` and the readout's is `foreground`, and that
+ * split is DESIGN.md's Brand Ink Rule rather than a preference.** A readout that
+ * is not a link is a figure and takes the page's ink. A readout that is a link
+ * has to read as something a reader may follow, and the token gate measures
+ * `brand-ink` at 4.5:1 against the page, a card and the accent surface in both
+ * modes of all six sources. The focus ring is drawn at full strength on the
+ * anchor rather than left to the browser, so the indicator this Component owns
+ * is the indicator the gate can check.
+ *
+ * **It is a server Component, and the reason is that everything it draws is
+ * decided from props.** No hook, no state, no effect, no handler and no directive,
+ * so a page with four star readouts ships no JavaScript for them at all. The
+ * consequence worth stating is the one a reader would otherwise have to work out:
+ * with no `href` there is no interaction, and with one the only behaviour is the
+ * browser's own navigation, so there is nothing this Component could need a client
+ * runtime to do. The cost is that a consumer who wants the count to refresh
+ * itself is reaching for a `live` surface and a subscription Prism does not own.
+ */
+function RepoStars({ count, label, mark, format, href, size = 'md', className, ...props }) {
+    const shown = format === undefined ? String(count) : format(count);
+    const figure = `${shown} ${label}`;
+    return (_jsx("span", { "data-slot": "repo-stars", className: cn('inline-flex max-w-full', className), ...props, children: href === undefined ? (_jsx(StarBody, { mark: mark, figure: figure, className: cn(REPO_STARS_SIZE[size], 'text-foreground') })) : (_jsx("a", { "data-slot": "repo-stars-link", href: href, className: cn(REPO_STARS_SIZE[size], 'hover:underline focus-visible:ring-ring inline-flex min-w-0 rounded-sm underline-offset-2 outline-none focus-visible:ring-[3px]'), children: _jsx(StarBody, { mark: mark, figure: figure, className: "text-brand-ink" }) })) }));
+}
+export { RepoStars };

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

@@ -76,10 +76,34 @@ export interface ResizablePanelProps extends ComponentProps<'div'> {
  * same class of defect as a control that forgets a setting the reader chose and
  * nobody can explain.
  *
+ * **A drag reads the group's box once, at the press, and is arithmetic after
+ * that.** Every frame of a drag needs the group's travel, and reading it on each
+ * frame means reading it immediately after the frame before wrote the new position
+ * and therefore wrote new styles: one forced synchronous layout per frame, on the
+ * main thread, in the middle of the interaction the reader is holding. The box
+ * cannot change under a drag this Component started, because the panes are given a
+ * percentage of the group rather than the other way round, so the box is read where
+ * the press happened and reused. **A group resized by something else part way through
+ * a drag finishes that drag against the travel it started with**, which is the answer
+ * a reader mid-gesture can use; a caller who needs a drag that follows a changing
+ * group ends that drag and starts it again. The keyboard reads no box at all: an
+ * arrow key moves the divider by a share of its position, so current layout is never
+ * stale for a move that does not consult it.
+ *
  * **A divider has a name and it is the caller's word.** There is no default,
  * because a default would be the same word on every divider on every page and
  * would be true of none of them.
  *
+ * **The coarse-pointer floor is paid with a band, and the drag does not move.** A
+ * one pixel divider cannot be grown: the two panes are given percentages of the
+ * group and already fill it, so a 44 pixel divider would push a pane off the screen
+ * on a phone. A transparent 44 by 44 band centred on the line gives the target and
+ * leaves the drawing, the arithmetic and the layout exactly as they were, because the
+ * drag reads the group's box rather than this element's. The cost is that a press
+ * within 21 pixels of the line grabs the divider rather than the pane; it is stated
+ * at the class, which is where a reader changing that class will look. See
+ * `DESIGN.md`, The coarse-pointer floor.
+ *
  * This is the one Component here that is not composed on a Base UI primitive,
  * because Base UI 1.8.0 ships none: the package has no `Resizable` in it, so the
  * separator role, the focusable-divider keyboard model and the drag are authored

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

@@ -1 +1 @@
-{"version":3,"file":"resizable.d.ts","sourceRoot":"","sources":["../../../src/components/ui/resizable.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId;;;;;;;;;GASG;AACH,KAAK,QAAQ,GAAG,MAAM,CAAA;AAEtB,sFAAsF;AACtF,KAAK,oBAAoB,GAAG,YAAY,GAAG,UAAU,CAAA;AAgDrD,6CAA6C;AAC7C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7E;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC;;;OAGG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAA;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,KAAK,EACL,WAA0B,EAC1B,eAAoB,EACpB,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAChB,QAAgB,EAChB,GAAG,KAAK,EACT,EAAE,cAAc,+BA0FhB;AAED;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,IAAS,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BAoBrF;AAED;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BA8FvF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnF;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAED,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"resizable.d.ts","sourceRoot":"","sources":["../../../src/components/ui/resizable.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAId;;;;;;;;;GASG;AACH,KAAK,QAAQ,GAAG,MAAM,CAAA;AAEtB,sFAAsF;AACtF,KAAK,oBAAoB,GAAG,YAAY,GAAG,UAAU,CAAA;AAgDrD,6CAA6C;AAC7C,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7E;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,oBAAoB,CAAA;IAClC;;;OAGG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAA;IAC1B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAA;IAC/C,wEAAwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAoB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,iBAAS,SAAS,CAAC,EACjB,SAAS,EACT,KAAK,EACL,WAA0B,EAC1B,eAAoB,EACpB,QAAQ,EAAE,YAAY,EACtB,gBAAgB,EAChB,QAAgB,EAChB,GAAG,KAAK,EACT,EAAE,cAAc,+BA0FhB;AAED;;;;;;;GAOG;AACH,iBAAS,cAAc,CAAC,EAAE,SAAS,EAAE,IAAS,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BAoBrF;AAED;;;;;;;GAOG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,oBAAoB,+BAiKvF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnF;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;CACd;AAED,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,CAAA"}

package/dist/components/ui/resizable.js

@@ -44,10 +44,34 @@ function useResizableContext(part) {
  * same class of defect as a control that forgets a setting the reader chose and
  * nobody can explain.
  *
+ * **A drag reads the group's box once, at the press, and is arithmetic after
+ * that.** Every frame of a drag needs the group's travel, and reading it on each
+ * frame means reading it immediately after the frame before wrote the new position
+ * and therefore wrote new styles: one forced synchronous layout per frame, on the
+ * main thread, in the middle of the interaction the reader is holding. The box
+ * cannot change under a drag this Component started, because the panes are given a
+ * percentage of the group rather than the other way round, so the box is read where
+ * the press happened and reused. **A group resized by something else part way through
+ * a drag finishes that drag against the travel it started with**, which is the answer
+ * a reader mid-gesture can use; a caller who needs a drag that follows a changing
+ * group ends that drag and starts it again. The keyboard reads no box at all: an
+ * arrow key moves the divider by a share of its position, so current layout is never
+ * stale for a move that does not consult it.
+ *
  * **A divider has a name and it is the caller's word.** There is no default,
  * because a default would be the same word on every divider on every page and
  * would be true of none of them.
  *
+ * **The coarse-pointer floor is paid with a band, and the drag does not move.** A
+ * one pixel divider cannot be grown: the two panes are given percentages of the
+ * group and already fill it, so a 44 pixel divider would push a pane off the screen
+ * on a phone. A transparent 44 by 44 band centred on the line gives the target and
+ * leaves the drawing, the arithmetic and the layout exactly as they were, because the
+ * drag reads the group's box rather than this element's. The cost is that a press
+ * within 21 pixels of the line grabs the divider rather than the pane; it is stated
+ * at the class, which is where a reader changing that class will look. See
+ * `DESIGN.md`, The coarse-pointer floor.
+ *
  * This is the one Component here that is not composed on a Base UI primitive,
  * because Base UI 1.8.0 ships none: the package has no `Resizable` in it, so the
  * separator role, the focusable-divider keyboard model and the drag are authored
@@ -144,9 +168,41 @@ function ResizablePanel({ className, size = 50, style, ...props }) {
 function ResizableHandle({ className, label, onKeyDown, ...props }) {
     const { orientation, position, moveTo, moveBy, min, max, disabled, dragging, setDragging, groupElement, } = useResizableContext('divider');
     const last = useRef(null);
+    // The group's box, read once at the press and held for the drag.
+    //
+    // A pointer drag moves the divider by a share of the group's travel, so every frame
+    // of the drag needs that box, and reading it inside `onPointerMove` means reading
+    // it immediately after the frame before wrote the new position and therefore
+    // wrote new styles. That is one forced synchronous layout per frame of every drag,
+    // on the main thread, in the middle of the interaction a reader is holding, and it
+    // is the whole cost of the divider for a number that cannot change while the drag
+    // runs: the panes are given a percentage of the group and the group is not given a
+    // percentage of the panes, so moving the divider does not move the box it is
+    // measured against. So the box is read where the press happened, which is the last
+    // moment before the drag with no pending write in front of it, and every frame
+    // after that is arithmetic. `ReorderableList` measures its rows the same way, once
+    // at `pointerdown`, for the same reason.
+    //
+    // **The keyboard never reads it.** A key press moves the divider by a fixed share
+    // of the position rather than by a distance through the group, so the keyboard
+    // model needs no box, and current layout is never stale for a move that does not
+    // consult it.
+    //
+    // What this does not see is a group resized by something else part way through a
+    // drag, which a read per frame would have picked up on the next frame. The ordinary
+    // case of that is a window resized mid-drag, and there the drag finishes against
+    // the travel it started with, which is the answer a reader who is mid-gesture can
+    // use; a caller who changes the group's size while a pointer is down on it is a
+    // caller whose drag has to end and start again, and nothing here pretends to hold
+    // that case rather than holding it badly.
+    const box = useRef(null);
     const onPointerDown = (event) => {
         if (disabled || event.button !== 0)
             return;
+        const group = groupElement();
+        if (group === null)
+            return;
+        box.current = group.getBoundingClientRect();
         event.currentTarget.setPointerCapture(event.pointerId);
         // The pointer's own coordinate, and not the divider's, because a drag is a
         // distance travelled and the first event is a press rather than a move.
@@ -156,15 +212,15 @@ function ResizableHandle({ className, label, onKeyDown, ...props }) {
     const onPointerMove = (event) => {
         if (last.current === null)
             return;
-        const box = groupElement()?.getBoundingClientRect();
-        if (box === undefined)
+        const measured = box.current;
+        if (measured === null)
             return;
         // Measured along the group's own axis, so a horizontal split follows the x
         // and a vertical one follows the y, and a caller that passes the wrong
         // `orientation` cannot get a divider that tracks the wrong coordinate.
         const here = orientation === 'horizontal' ? event.clientX : event.clientY;
         const delta = here - last.current;
-        const travel = orientation === 'horizontal' ? box.width : box.height;
+        const travel = orientation === 'horizontal' ? measured.width : measured.height;
         if (travel === 0)
             return;
         moveBy((delta / travel) * 100);
@@ -175,6 +231,10 @@ function ResizableHandle({ className, label, onKeyDown, ...props }) {
             return;
         event.currentTarget.releasePointerCapture(event.pointerId);
         last.current = null;
+        // The box belonged to the press that is ending here. A pointer move that arrives
+        // after the release is refused by `last` already, and holding a box a drag has
+        // given up is a number nothing could explain.
+        box.current = null;
         setDragging(false);
     };
     const onKey = (event) => {
@@ -200,6 +260,38 @@ function ResizableHandle({ className, label, onKeyDown, ...props }) {
     return (_jsx("div", { "data-slot": "resizable-handle", role: "separator", "aria-label": label, "aria-orientation": orientation, "aria-valuenow": Math.round(position), "aria-valuemin": min, "aria-valuemax": max, "aria-disabled": disabled ? 'true' : undefined, tabIndex: disabled ? -1 : 0, "data-orientation": orientation, "data-dragging": dragging ? 'true' : undefined, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: endDrag, onPointerCancel: endDrag, onKeyDown: (event) => {
             onKey(event);
             onKeyDown?.(event);
-        }, className: cn('bg-border relative shrink-0 touch-none outline-none', orientation === 'vertical' ? 'h-px w-full cursor-row-resize' : 'h-full w-px cursor-col-resize', 'transition-colors duration-fast ease-out', 'hover:bg-ring focus-visible:bg-ring data-[dragging]:bg-ring', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', className), ...props }));
+        }, className: cn('bg-border relative shrink-0 touch-none outline-none', orientation === 'vertical' ? 'h-px w-full cursor-row-resize' : 'h-full w-px cursor-col-resize', 'transition-colors duration-fast ease-out', 'hover:bg-ring focus-visible:bg-ring data-[dragging]:bg-ring', 'focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', 
+        // The coarse-pointer floor, as a band, and this is the least mechanical control
+        // in the package, so the reasoning is the whole of the note.
+        //
+        // **A step is impossible here, and the reason is arithmetic rather than
+        // taste.** The panes are given `flexBasis: <size>%` with `flexShrink: 0`, so the
+        // two of them already sum to the group's whole width and the divider is what
+        // overflows it, by exactly its own one pixel. A `w-11` divider would overflow the
+        // group by 44, which on a phone pushes the right pane's right edge off the screen.
+        // Making room would mean changing what `size` means, or giving the panes a
+        // coarse-pointer-only basis calculation, and either one re-derives the meaning of
+        // the number a caller passed. A one pixel divider cannot take a step.
+        //
+        // **A band works because three facts hold that the three conditions ask about.**
+        // It is a pseudo-element, so the box the drag measures stays the drawn box and the
+        // arithmetic above is untouched: `onPointerDown` reads the *group's* rect and
+        // `onPointerMove` divides by the group's travel, so nothing reads this element's
+        // own size at all. It paints above both panes without a `z-index`, because the
+        // handle is `relative` with `z-index: auto` and the panes are static, and a
+        // positioned descendant paints after non-positioned siblings. And the band is
+        // 44 by 44 rather than 44 by the handle's length, which is what keeps the overlap
+        // local: along the split the handle already spans the group, so 44 there is free,
+        // and across the split it reaches 21 pixels into each pane over a 44 pixel stretch
+        // of the line rather than the whole height of the group.
+        //
+        // **The cost is stated rather than hidden.** A press within 21 pixels of the line,
+        // over a 44 pixel stretch of it, grabs the divider rather than the pane, and
+        // `touch-none` travels with the band because the pseudo-element resolves its
+        // `touch-action` from this element. So text selection near the divider is
+        // unavailable inside that patch. That is the trade a resize gutter makes on every
+        // platform, and it is bounded to a patch rather than run the length of the panes.
+        // See DESIGN.md, The coarse-pointer floor.
+        'pointer-coarse:before:absolute pointer-coarse:before:left-1/2 pointer-coarse:before:top-1/2 pointer-coarse:before:h-11 pointer-coarse:before:w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-[""]', className), ...props }));
 }
 export { Resizable, ResizablePanel, ResizableHandle };

package/dist/components/ui/search-dialog.d.ts

@@ -86,7 +86,17 @@ export type SearchDialogProps = {
     messages: SearchDialogMessages;
     /** The text shown before the reader has typed anything. */
     hint?: string;
-    /** Called when the reader dismisses the dialog, by Escape or by the backdrop. */
+    /**
+     * Called when the reader has finished with the dialog: by Escape, by the
+     * backdrop, by the close control, or by choosing a result.
+     *
+     * **The caller unmounts, and it is called once the dialog has actually left
+     * rather than at the moment it was asked to.** Those are different moments and
+     * the later one is the one the caller wants, because the dialog owns the
+     * reader's focus while it is closing and removing it out from under its own
+     * exit is what strands a keyboard reader on `<body>`. Render this Component
+     * only when the reader is searching, and unmount it from here.
+     */
     onClose: () => void;
     /** The most results to draw. Further matches are dropped rather than paged. */
     limit?: number;
@@ -104,6 +114,32 @@ export type SearchDialogProps = {
  * that wants a different ranking can render this directly or pass its own control
  * through the navbar's `actions` slot.
  *
+ * **It is `Dialog`, and the composition is the point rather than an
+ * implementation detail.** A modal claims four things at once: that the page
+ * behind it is inert, that the keyboard cannot leave, that the page under it does
+ * not scroll, and that focus comes back to the control that opened it. Hand-rolled,
+ * those four are four pieces of code, and the version this Component used to carry
+ * declared the first with `aria-modal` while implementing none of the others: the
+ * page behind was reachable by Tab, focus fell to `<body>` when the dialog
+ * unmounted, and the panel scrolled with the document and could be clipped by an
+ * ancestor. `Dialog` already had all four, and this Component now takes the trap,
+ * the portal, the scroll lock, the outside-press dismissal and the overlay from it,
+ * so the package holds one modal rather than one and a claim. What is left here is
+ * the part that is specific to search: the fetch, the scorer, the field, the list
+ * and the count.
+ *
+ * **The field is focused on open, and it says why it asks rather than taking the
+ * default.** `Dialog` focuses the panel's first tabbable element, which is the
+ * field here, so the default would be right by accident; it is named anyway because
+ * the reason it is right is a fact about search and not about dialogs: a reader who
+ * opened a search box opened it to type into it, and the field is the only control
+ * in the panel that needs a keyboard.
+ *
+ * **Escape is answered by the modal rather than by a document-level listener.**
+ * A listener on `document` answers the key whether or not the dialog is the thing
+ * the reader is looking at, which is the same failure `Toast` records about
+ * floating surfaces that listen globally.
+ *
  * **The ranking is a scorer, not a search engine, and the difference is the
  * trade.** There is no stemming, no fuzzy matching and no typo tolerance: a query
  * token matches a document when the token is a substring of one of its fields.
@@ -129,10 +165,9 @@ export type SearchDialogProps = {
  * the ranking and is a named constant so a reader can see the numbers rather than
  * infer them.
  *
- * The field is focused on mount and Escape closes, and the backdrop closes, so
- * every exit is a control rather than a gesture. The list is marked as a list of
- * results and the count is announced through a live region, so a screen reader
- * user learns that a search ran rather than hearing the list change under them.
+ * The list is marked as a list of results and the count is announced through a
+ * live region, so a screen reader user learns that a search ran rather than
+ * hearing the list change under them.
  */
 export declare function SearchDialog({ indexUrl, label, messages, hint, onClose, limit, className, }: SearchDialogProps): import("react").JSX.Element;
 export default SearchDialog;

package/dist/components/ui/search-dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-dialog.d.ts","sourceRoot":"","sources":["../../../src/components/ui/search-dialog.tsx"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,KAAU,EACV,SAAS,GACV,EAAE,iBAAiB,+BA6JnB;AA+ED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"search-dialog.d.ts","sourceRoot":"","sources":["../../../src/components/ui/search-dialog.tsx"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAA;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,YAAY,CAAC,EAC3B,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,KAAU,EACV,SAAS,GACV,EAAE,iBAAiB,+BA6MnB;AA+ED,eAAe,YAAY,CAAA"}

package/dist/components/ui/search-dialog.js

@@ -1,7 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Search, X } from 'lucide-react';
+import { Dialog, DialogContent } from './dialog.js';
 /**
  * A search dialog over a static index, computed in the browser.
  *
@@ -13,6 +14,32 @@ import { Search, X } from 'lucide-react';
  * that wants a different ranking can render this directly or pass its own control
  * through the navbar's `actions` slot.
  *
+ * **It is `Dialog`, and the composition is the point rather than an
+ * implementation detail.** A modal claims four things at once: that the page
+ * behind it is inert, that the keyboard cannot leave, that the page under it does
+ * not scroll, and that focus comes back to the control that opened it. Hand-rolled,
+ * those four are four pieces of code, and the version this Component used to carry
+ * declared the first with `aria-modal` while implementing none of the others: the
+ * page behind was reachable by Tab, focus fell to `<body>` when the dialog
+ * unmounted, and the panel scrolled with the document and could be clipped by an
+ * ancestor. `Dialog` already had all four, and this Component now takes the trap,
+ * the portal, the scroll lock, the outside-press dismissal and the overlay from it,
+ * so the package holds one modal rather than one and a claim. What is left here is
+ * the part that is specific to search: the fetch, the scorer, the field, the list
+ * and the count.
+ *
+ * **The field is focused on open, and it says why it asks rather than taking the
+ * default.** `Dialog` focuses the panel's first tabbable element, which is the
+ * field here, so the default would be right by accident; it is named anyway because
+ * the reason it is right is a fact about search and not about dialogs: a reader who
+ * opened a search box opened it to type into it, and the field is the only control
+ * in the panel that needs a keyboard.
+ *
+ * **Escape is answered by the modal rather than by a document-level listener.**
+ * A listener on `document` answers the key whether or not the dialog is the thing
+ * the reader is looking at, which is the same failure `Toast` records about
+ * floating surfaces that listen globally.
+ *
  * **The ranking is a scorer, not a search engine, and the difference is the
  * trade.** There is no stemming, no fuzzy matching and no typo tolerance: a query
  * token matches a document when the token is a substring of one of its fields.
@@ -38,25 +65,30 @@ import { Search, X } from 'lucide-react';
  * the ranking and is a named constant so a reader can see the numbers rather than
  * infer them.
  *
- * The field is focused on mount and Escape closes, and the backdrop closes, so
- * every exit is a control rather than a gesture. The list is marked as a list of
- * results and the count is announced through a live region, so a screen reader
- * user learns that a search ran rather than hearing the list change under them.
+ * The list is marked as a list of results and the count is announced through a
+ * live region, so a screen reader user learns that a search ran rather than
+ * hearing the list change under them.
  */
 export function SearchDialog({ indexUrl, label, messages, hint, onClose, limit = 12, className, }) {
     const inputRef = useRef(null);
+    // The dialog is mounted only once a reader has asked for search, so it opens on
+    // its first render and this is what the modal is controlled by. It is local
+    // rather than derived from `onClose` because the caller unmounts and never
+    // renders a closed SearchDialog: the state here is what lets the modal run one
+    // exit, for every reason the reader left, before the handoff.
+    const [open, setOpen] = useState(true);
     const [query, setQuery] = useState('');
     const [entries, setEntries] = useState(null);
     const [failed, setFailed] = useState(false);
-    useEffect(() => {
-        inputRef.current?.focus();
-        const onKeyDown = (event) => {
-            if (event.key === 'Escape')
-                onClose();
-        };
-        document.addEventListener('keydown', onKeyDown);
-        return () => document.removeEventListener('keydown', onKeyDown);
-    }, [onClose]);
+    /**
+     * The one exit, for every reason the reader leaves.
+     *
+     * Escape and the backdrop arrive through `Dialog`'s own `onOpenChange`; the
+     * close control and a chosen result arrive here. Both write the same state, so
+     * there is one leave rather than one per reason, and the caller's unmount is
+     * one call at the end of it.
+     */
+    const dismiss = useCallback(() => setOpen(false), []);
     /**
      * The index, fetched once per dialog.
      *
@@ -106,8 +138,54 @@ export function SearchDialog({ indexUrl, label, messages, hint, onClose, limit =
             return messages.empty;
         return null;
     })();
-    return (_jsx("div", { role: "presentation", onClick: onClose, className: "bg-foreground/40 fixed inset-0 z-50 flex items-start justify-center p-4 pt-[15vh]", children: _jsxs("div", { role: "dialog", "aria-modal": "true", "aria-label": label, onClick: (event) => event.stopPropagation(), className: 'border-border bg-popover text-popover-foreground flex max-h-[70vh] w-full max-w-xl flex-col overflow-hidden rounded-xl border shadow-lg ' +
-                (className ?? ''), children: [_jsxs("div", { className: "border-border flex items-center gap-2 border-b px-3", children: [_jsx(Search, { "aria-hidden": true, className: "text-muted-foreground size-4 shrink-0" }), _jsx("input", { ref: inputRef, value: query, onChange: (event) => setQuery(event.target.value), placeholder: label, "aria-label": label, className: "text-foreground h-12 flex-1 bg-transparent text-sm outline-none" }), _jsx("button", { type: "button", onClick: onClose, "aria-label": messages.close, className: "text-muted-foreground hover:text-foreground focus-visible:border-ring focus-visible:ring-ring rounded-md p-1 transition-colors focus-visible:ring-[3px] focus-visible:outline-none", children: _jsx(X, { "aria-hidden": true, className: "size-4" }) })] }), _jsxs("div", { className: "overflow-y-auto p-2", children: [_jsx("p", { "aria-live": "polite", className: "sr-only", children: typed ? (_jsxs(_Fragment, { children: [_jsx("span", { children: results.length }), ' ', _jsx("span", { children: results.length === 1 ? messages.one : messages.other })] })) : null }), status ? _jsx("p", { className: "text-muted-foreground px-3 py-6 text-sm", children: status }) : null, _jsx("ul", { className: "flex flex-col", children: results.map((result) => (_jsx("li", { children: _jsxs("a", { href: result.url, onClick: onClose, className: "hover:bg-accent focus-visible:border-ring focus-visible:ring-ring flex flex-col gap-0.5 rounded-lg px-3 py-2 transition-colors focus-visible:ring-[3px] focus-visible:outline-none", children: [_jsx("span", { className: "text-foreground text-sm font-medium", children: result.title }), result.description ? (_jsx("span", { className: "text-muted-foreground line-clamp-2 text-xs", children: result.description })) : null, result.breadcrumbs?.length ? (_jsx("span", { className: "text-muted-foreground text-xs", children: result.breadcrumbs.join(' / ') })) : null] }) }, result.id))) })] })] }) }));
+    return (_jsx(Dialog, { open: open, onOpenChange: setOpen, 
+        // The handoff is on the way out rather than on the way in, for two reasons
+        // that are the same reason. The modal restores focus as it closes, and a
+        // caller that unmounted the dialog one frame earlier would take that focus
+        // return with it and drop the reader on `<body>`. And the exit is the
+        // caller's cue that the dialog is finished, so handing over at the end of
+        // it is what makes `onClose` mean "it is gone" rather than "it is going".
+        onOpenChangeComplete: (isOpen) => {
+            if (!isOpen)
+                onClose();
+        }, children: _jsxs(DialogContent, { initialFocus: inputRef, 
+            // The panel draws its own close control, in its own field row, named with
+            // `messages.close`. `Dialog`'s is a fixed word in a fixed corner, and two
+            // close controls in one modal is one more control than the reader needs.
+            showCloseButton: false, "aria-label": label, 
+            // No elevation here, and the absence is the point. This Component used to
+            // carry `shadow-lg` over the top of `DialogContent`'s own `shadow-md`, and
+            // the override was invisible as an improvement and permanent as a second
+            // answer: `shadow-lg` is not an authored step, so it resolved against
+            // Tailwind's stock theme rather than against the token source, and a
+            // retune of the elevation scale would have moved every other lifted
+            // surface in this package and left this panel exactly where it was. The
+            // panel is the one lifted element over a modal scrim, which is what
+            // `--shadow-md` is for, and `DialogContent` already draws it.
+            className: 'border-border bg-popover text-popover-foreground flex max-h-[70vh] w-full max-w-overlay-palette flex-col overflow-hidden rounded-xl p-0 gap-0 ' +
+                (className ?? ''), children: [_jsxs("div", { className: "border-border flex items-center gap-2 border-b px-3", children: [_jsx(Search, { "aria-hidden": true, className: "text-muted-foreground size-4 shrink-0" }), _jsx("input", { ref: inputRef, value: query, onChange: (event) => setQuery(event.target.value), placeholder: label, "aria-label": label, 
+                            // The ring is at full strength, and it is drawn at all because this is
+                            // the control focus lands in and `outline-none` is what removed the
+                            // browser's indicator from it. A search field with no visible focus is
+                            // a search field a keyboard reader cannot say they are inside.
+                            //
+                            // `text-base` then `md:text-sm`, which is the pair every other field in
+                            // this package carries and the reason is a platform one rather than a
+                            // visual one: iOS Safari zooms the viewport on a focused input whose
+                            // computed font size is under 16 pixels, and it does not zoom back out,
+                            // so a reader who opened the palette on a phone was left looking at a
+                            // magnified page they could not leave. A rem step also tracks a reader
+                            // who has raised their browser's default size, which a pixel value does
+                            // not.
+                            className: "text-foreground h-12 flex-1 bg-transparent text-base outline-none focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px] md:text-sm" }), _jsx("button", { type: "button", onClick: dismiss, "aria-label": messages.close, className: 
+                            // 24px for a mouse and a trackpad, `p-1` around a 16px icon, and the
+                            // 44px coarse-pointer floor as a step rather than a band. A band here
+                            // would hang off the top and bottom of the field row and over the result
+                            // list under it, where a step does not: the row is 48px tall and the
+                            // button grows to 44 inside it, so nothing moves and no list row is
+                            // stolen. See `DialogContent`'s own close control, which is in a corner
+                            // and says the other half of why the two are not the same shape.
+                            'text-muted-foreground hover:text-foreground focus-visible:border-ring focus-visible:ring-ring pointer-coarse:size-11 rounded-md p-1 transition-colors focus-visible:ring-[3px] focus-visible:outline-none', children: _jsx(X, { "aria-hidden": true, className: "size-4" }) })] }), _jsxs("div", { className: "overflow-y-auto p-2", children: [_jsx("p", { "aria-live": "polite", className: "sr-only", children: typed ? (_jsxs(_Fragment, { children: [_jsx("span", { children: results.length }), ' ', _jsx("span", { children: results.length === 1 ? messages.one : messages.other })] })) : null }), status ? _jsx("p", { className: "text-muted-foreground px-3 py-6 text-sm", children: status }) : null, _jsx("ul", { className: "flex flex-col", children: results.map((result) => (_jsx("li", { children: _jsxs("a", { href: result.url, onClick: dismiss, className: "hover:bg-accent focus-visible:border-ring focus-visible:ring-ring flex flex-col gap-0.5 rounded-lg px-3 py-2 transition-colors focus-visible:ring-[3px] focus-visible:outline-none", children: [_jsx("span", { className: "text-foreground text-sm font-medium", children: result.title }), result.description ? (_jsx("span", { className: "text-muted-foreground line-clamp-2 text-xs", children: result.description })) : null, result.breadcrumbs?.length ? (_jsx("span", { className: "text-muted-foreground text-xs", children: result.breadcrumbs.join(' / ') })) : null] }) }, result.id))) })] })] }) }));
 }
 /**
  * What a match in each field is worth, and the whole of the ranking.