@nanisoft/prism-ui 0.10.1 → 0.13.0

package/dist/components/ui/scroll-area.d.ts

@@ -0,0 +1,97 @@
+import type { ComponentProps, ReactNode } from 'react';
+/** Which axis the region is expected to scroll on. */
+export type ScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
+/** The props the ScrollArea accepts. */
+export interface ScrollAreaProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * The content the region scrolls through.
+     *
+     * Ordinary children, not a render prop and not a measured height. A consumer
+     * sizes the region from the outside with `className` and puts whatever they like
+     * inside, which is the arrangement that lets a region hold a table, a list of
+     * anything, or a form.
+     */
+    children?: ReactNode;
+    /**
+     * Which scrollbars to draw.
+     *
+     * `both` is the default rather than `vertical` because a region that overflows
+     * on an axis nobody asked about is still a region a reader has to be able to
+     * scroll on that axis, and a scrollbar that is missing is a scrollbar that has
+     * to be found in the browser's own chrome, which is the thing this Component
+     * exists to replace. Pass `vertical` when the content is known never to scroll
+     * sideways, and the horizontal bar is not drawn at all.
+     */
+    orientation?: ScrollAreaOrientation;
+    /**
+     * Keeps the scrollbar in the DOM when the region has nothing to scroll.
+     *
+     * Off by default, and that default is the decision: a region with nothing to
+     * scroll has no scroll position, so a bar drawn beside it is a claim that there
+     * is something past the edge. Turn it on only where a region is expected to
+     * grow and the reader should see the affordance before the content arrives.
+     */
+    keepMounted?: boolean;
+    /**
+     * The accessible name of the region.
+     *
+     * Required rather than defaulted. A scroll region with no name is announced as
+     * a group of focusable nothing, and a page with three of them is a page where a
+     * keyboard reader tabs into a region and cannot tell what is in it or what is
+     * past the edge. The name is the caller's word.
+     */
+    label: string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A scrollable region whose scrollbar belongs to this design system.
+ *
+ * **The browser's scrollbar is the one piece of a page that belongs to no design
+ * system at all.** Every other surface a consumer draws is a token from here, and
+ * the scrollbar beside it is a rectangle the operating system drew, in a colour
+ * chosen for the OS's own background rather than for the card the content is on.
+ * It is also the only control on a page that is resized by dragging, and the only
+ * one that appears and disappears on a timer, so the browser's version is the one
+ * control a design system cannot restyle at all. This is where the package takes
+ * it over, and it is worth saying plainly that the native scrollbar is not
+ * available to restyle: `::-webkit-scrollbar` is one engine, `scrollbar-width` is
+ * two values, and neither can express a track and a thumb in tokens.
+ *
+ * **The scrolling is still the browser's.** This is the decision that matters most
+ * and the one worth arguing with, so here is the argument. The tempting version of
+ * this Component is a `div` with `overflow: hidden` whose content is moved by a
+ * transform on a wheel handler, with a `div` above it pretending to be a
+ * scrollbar. That version has no scroll position at all, so there is nothing for
+ * a keyboard to move, nothing for a screen reader to announce, no momentum, no
+ * scroll-into-view, and no way for a reader to know how far through they are. A
+ * custom scrollbar that is a `div` is worse than the browser's, because the browser
+ * gives a reader all of that for free and the `div` version takes it away.
+ *
+ * So the region here is a real scrollable element in the document: the browser
+ * scrolls it, the browser gives it keyboard focus when it overflows, the arrow
+ * keys, Page Up, Page Down, Home and End all work because it is a scroll
+ * container and not a picture of one. Only the appearance of the bar is taken
+ * over, and the bar is a real control layered over the native one rather than a
+ * replacement for the scrolling.
+ *
+ * **A native scrollbar cannot be styled, so this one is a sibling of the scroll
+ * container rather than a part of it.** That is the whole reason a consumer cannot
+ * assemble this from `overflow-auto` and a coloured box, and it is why the region
+ * is a named landmark: a scrollable region that a keyboard reader can tab into and
+ * that has no name is a tab stop that says nothing. The name is a prop.
+ *
+ * **A region with nothing to scroll draws no scrollbar.** Not a disabled one and
+ * not a faint one: a bar beside a region with no overflow is a claim that there is
+ * something past the edge, and a reader who is told that twice loses trust in the
+ * third bar they meet. The bar is absent, and a caller who wants it present before
+ * the content arrives says so with `keepMounted`.
+ *
+ * It is a client Component, because measuring overflow and positioning a thumb is
+ * a measurement and a measurement is not something a server can do. Everything it
+ * draws is a semantic utility, so a scoped pack boundary restyles the thumb and the
+ * track through the cascade exactly as it restyles the text beside them.
+ */
+declare function ScrollArea({ className, children, orientation, keepMounted, label, ...props }: ScrollAreaProps): import("react").JSX.Element;
+export { ScrollArea };
+//# sourceMappingURL=scroll-area.d.ts.map

package/dist/components/ui/scroll-area.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../../src/components/ui/scroll-area.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD,sDAAsD;AACtD,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,YAAY,GAAG,MAAM,CAAA;AAEtE,wCAAwC;AACxC,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC9E;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,qBAAqB,CAAA;IACnC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,QAAQ,EACR,WAAoB,EACpB,WAAmB,EACnB,KAAK,EACL,GAAG,KAAK,EACT,EAAE,eAAe,+BAiEjB;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/ui/scroll-area.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ScrollArea as ScrollAreaPrimitive } from '@base-ui/react/scroll-area';
+import { cn } from '../../lib/utils.js';
+/**
+ * A scrollable region whose scrollbar belongs to this design system.
+ *
+ * **The browser's scrollbar is the one piece of a page that belongs to no design
+ * system at all.** Every other surface a consumer draws is a token from here, and
+ * the scrollbar beside it is a rectangle the operating system drew, in a colour
+ * chosen for the OS's own background rather than for the card the content is on.
+ * It is also the only control on a page that is resized by dragging, and the only
+ * one that appears and disappears on a timer, so the browser's version is the one
+ * control a design system cannot restyle at all. This is where the package takes
+ * it over, and it is worth saying plainly that the native scrollbar is not
+ * available to restyle: `::-webkit-scrollbar` is one engine, `scrollbar-width` is
+ * two values, and neither can express a track and a thumb in tokens.
+ *
+ * **The scrolling is still the browser's.** This is the decision that matters most
+ * and the one worth arguing with, so here is the argument. The tempting version of
+ * this Component is a `div` with `overflow: hidden` whose content is moved by a
+ * transform on a wheel handler, with a `div` above it pretending to be a
+ * scrollbar. That version has no scroll position at all, so there is nothing for
+ * a keyboard to move, nothing for a screen reader to announce, no momentum, no
+ * scroll-into-view, and no way for a reader to know how far through they are. A
+ * custom scrollbar that is a `div` is worse than the browser's, because the browser
+ * gives a reader all of that for free and the `div` version takes it away.
+ *
+ * So the region here is a real scrollable element in the document: the browser
+ * scrolls it, the browser gives it keyboard focus when it overflows, the arrow
+ * keys, Page Up, Page Down, Home and End all work because it is a scroll
+ * container and not a picture of one. Only the appearance of the bar is taken
+ * over, and the bar is a real control layered over the native one rather than a
+ * replacement for the scrolling.
+ *
+ * **A native scrollbar cannot be styled, so this one is a sibling of the scroll
+ * container rather than a part of it.** That is the whole reason a consumer cannot
+ * assemble this from `overflow-auto` and a coloured box, and it is why the region
+ * is a named landmark: a scrollable region that a keyboard reader can tab into and
+ * that has no name is a tab stop that says nothing. The name is a prop.
+ *
+ * **A region with nothing to scroll draws no scrollbar.** Not a disabled one and
+ * not a faint one: a bar beside a region with no overflow is a claim that there is
+ * something past the edge, and a reader who is told that twice loses trust in the
+ * third bar they meet. The bar is absent, and a caller who wants it present before
+ * the content arrives says so with `keepMounted`.
+ *
+ * It is a client Component, because measuring overflow and positioning a thumb is
+ * a measurement and a measurement is not something a server can do. Everything it
+ * draws is a semantic utility, so a scoped pack boundary restyles the thumb and the
+ * track through the cascade exactly as it restyles the text beside them.
+ */
+function ScrollArea({ className, children, orientation = 'both', keepMounted = false, label, ...props }) {
+    return (_jsxs(ScrollAreaPrimitive.Root, { "data-slot": "scroll-area", className: cn('relative', className), ...props, children: [_jsx(ScrollAreaPrimitive.Viewport, { "data-slot": "scroll-area-viewport", role: "group", "aria-label": label, className: cn('size-full overscroll-contain rounded-[inherit] focus-visible:ring-ring outline-none focus-visible:ring-[3px]'), children: children }), orientation === 'horizontal' ? null : (_jsx(ScrollAreaPrimitive.Scrollbar, { "data-slot": "scroll-area-scrollbar", orientation: "vertical", keepMounted: keepMounted, 
+                /*
+                 * Transparent until there is something to scroll, then visible on its
+                 * own, while the pointer is over the region, and while it is being
+                 * scrolled. The `bg-transparent` is a declared absence rather than a
+                 * missing class: the track is the surface the content is already on, so
+                 * drawing one would put a second surface between the reader and the
+                 * content for no information. The thumb is the only part that carries
+                 * ink, and it is `bg-border` at rest and the full muted ink on hover and
+                 * during a scroll, so it is visible against a light card and a dark one
+                 * without a value that belongs to neither.
+                 */
+                className: "flex w-2 touch-none select-none p-px opacity-0 transition-opacity duration-fast ease-out data-[has-overflow-y]:opacity-100 data-[hovering]:opacity-100 data-[scrolling]:opacity-100", children: _jsx(ScrollAreaPrimitive.Thumb, { "data-slot": "scroll-area-thumb", className: "bg-border relative flex-1 rounded-full transition-colors duration-fast ease-out data-[hovering]:bg-muted-foreground data-[scrolling]:bg-muted-foreground" }) })), orientation === 'vertical' ? null : (_jsx(ScrollAreaPrimitive.Scrollbar, { "data-slot": "scroll-area-scrollbar", orientation: "horizontal", keepMounted: keepMounted, className: "flex h-2 touch-none select-none flex-col p-px opacity-0 transition-opacity duration-fast ease-out data-[has-overflow-x]:opacity-100 data-[hovering]:opacity-100 data-[scrolling]:opacity-100", children: _jsx(ScrollAreaPrimitive.Thumb, { "data-slot": "scroll-area-thumb", className: "bg-border relative flex-1 rounded-full transition-colors duration-fast ease-out data-[hovering]:bg-muted-foreground data-[scrolling]:bg-muted-foreground" }) }))] }));
+}
+export { ScrollArea };

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

@@ -0,0 +1,139 @@
+/**
+ * One page in a search index.
+ *
+ * The four fields a result is drawn from, and nothing else. A consumer's index is
+ * a JSON array of these served from a static route, so the shape is a contract
+ * between a build step Prism does not own and a dialog it does, and it is
+ * declared here rather than inferred: an index that grew a field this Component
+ * ignored would be a field no reader could be shown and no build would report.
+ *
+ * `description` and `content` are both optional because the two halves of a site
+ * differ. A landing page has a standfirst and a body; a section index has a title
+ * and a route and nothing else, and an index entry that had to invent an empty
+ * string to satisfy a required field would be an index carrying a fact nobody
+ * wrote.
+ */
+export type SearchIndexEntry = {
+    /** A stable key for the entry. The route is the usual choice and needs no coordination. */
+    id: string;
+    /** The result's own name, which is what the dialog puts on the first line. */
+    title: string;
+    /** Where the result goes. */
+    url: string;
+    /** One line of context, shown under the title when the index carries it. */
+    description?: string;
+    /** The body text the query is matched against. */
+    content?: string;
+    /** Where the result sits in the site's own hierarchy, shown as a trail. */
+    breadcrumbs?: string[];
+};
+/**
+ * Every sentence the dialog can say, as props.
+ *
+ * A Component ships no copy and no accessible name it did not receive, because a
+ * hardcoded string here is a claim every consumer of the package inherits and the
+ * corpus publishes as the design system's own voice. It is a prop per string
+ * rather than one `messages` object with defaults, so that overriding any of them
+ * is a decision a consumer makes visibly rather than a partial merge of a shipped
+ * object.
+ *
+ * The two result labels are a pair rather than one label with a number appended,
+ * and the reason is that this is the only place a count is spoken. English puts
+ * the number first and inflects the noun; most other written languages inflect the
+ * noun and put the number where their own grammar puts it. A Component that chose
+ * between "1 result" and "3 results" for a consumer would be choosing a language's
+ * word order on their behalf, and the two strings are the seam where that choice
+ * belongs to the site.
+ */
+export type SearchDialogMessages = {
+    /** The accessible name of the control that dismisses the dialog. */
+    close: string;
+    /** What is shown while the index is being fetched. */
+    loading: string;
+    /** What is shown when the index could not be fetched. */
+    failed: string;
+    /** What is shown when the query matched nothing. */
+    empty: string;
+    /** The count announced when exactly one result matched. */
+    one: string;
+    /** The count announced when any other number of results matched. */
+    other: string;
+};
+/**
+ * The props SearchDialog takes.
+ *
+ * `indexUrl` is where the index is fetched from and it is required, because a
+ * dialog with nothing to search is a text field. It is a URL rather than an
+ * index object for the reason the whole search design turns on: the index is
+ * large, it is the same bytes on every page of a site, and a prop would serialize
+ * it into the document of every route. Fetched on the first keystroke instead, it
+ * is on the wire once and only for the reader who searched.
+ */
+export type SearchDialogProps = {
+    /**
+     * Where the JSON index is served from. Fetched once, when the dialog opens.
+     *
+     * Opening rather than the first keystroke, because a reader who has opened a
+     * search box is already searching and the round trip is the difference between
+     * results on the first character and results a moment after it. The dialog is
+     * itself only mounted after a deliberate act, so "when the dialog opens" is
+     * still well after the page has painted and never on a page nobody searched.
+     */
+    indexUrl: string;
+    /** The accessible name of the dialog, and the placeholder in its field. */
+    label: string;
+    /** Every sentence the dialog can say. */
+    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. */
+    onClose: () => void;
+    /** The most results to draw. Further matches are dropped rather than paged. */
+    limit?: number;
+    /** Layout only. Changing a Prism-owned visual property from here is prohibited. */
+    className?: string;
+};
+/**
+ * A search dialog over a static index, computed in the browser.
+ *
+ * It is a Component and not a Block because it is a control that appears in a
+ * region rather than a region of a page, and because it is the one place in the
+ * search design that touches the network: the index is fetched here rather than
+ * passed in, so a site ships one index file and every page of that site reads it
+ * from the same bytes. `SiteNavbar` composes it behind a trigger, and a consumer
+ * that wants a different ranking can render this directly or pass its own control
+ * through the navbar's `actions` slot.
+ *
+ * **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.
+ * That is a real downgrade against the inverted index a documentation site would
+ * otherwise use, and it is deliberate, because the alternative is a Component in
+ * a package whose entire value is that it depends on a design system and a token
+ * pipeline and nothing else. A fuzzy engine is a large dependency whose ranking a
+ * consumer cannot restyle, cannot audit against this package's gates and cannot
+ * replace without forking the dialog. The scorer is thirty lines, its behaviour
+ * is stated above, and a consumer whose content needs typo tolerance passes its
+ * own control instead.
+ *
+ * **Every query token has to match somewhere.** That is AND rather than OR, and
+ * it is why a two-word query narrows instead of widening: with OR, a reader
+ * searching for "docs search" is shown every page that mentions either word,
+ * which on a documentation site is most of them, and the list stops being a
+ * ranking and becomes a filter they have to work through themselves.
+ *
+ * The weights are per field and stated rather than tuned: a match in a title is
+ * worth more than one in a body, and a match at the start of a title is worth more
+ * than one at its end, because a reader who types the first word of a page's name
+ * is usually right about which page they meant. `FIELD_WEIGHTS` is the whole of
+ * 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.
+ */
+export declare function SearchDialog({ indexUrl, label, messages, hint, onClose, limit, className, }: SearchDialogProps): import("react").JSX.Element;
+export default SearchDialog;
+//# sourceMappingURL=search-dialog.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,178 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Search, X } from 'lucide-react';
+/**
+ * A search dialog over a static index, computed in the browser.
+ *
+ * It is a Component and not a Block because it is a control that appears in a
+ * region rather than a region of a page, and because it is the one place in the
+ * search design that touches the network: the index is fetched here rather than
+ * passed in, so a site ships one index file and every page of that site reads it
+ * from the same bytes. `SiteNavbar` composes it behind a trigger, and a consumer
+ * that wants a different ranking can render this directly or pass its own control
+ * through the navbar's `actions` slot.
+ *
+ * **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.
+ * That is a real downgrade against the inverted index a documentation site would
+ * otherwise use, and it is deliberate, because the alternative is a Component in
+ * a package whose entire value is that it depends on a design system and a token
+ * pipeline and nothing else. A fuzzy engine is a large dependency whose ranking a
+ * consumer cannot restyle, cannot audit against this package's gates and cannot
+ * replace without forking the dialog. The scorer is thirty lines, its behaviour
+ * is stated above, and a consumer whose content needs typo tolerance passes its
+ * own control instead.
+ *
+ * **Every query token has to match somewhere.** That is AND rather than OR, and
+ * it is why a two-word query narrows instead of widening: with OR, a reader
+ * searching for "docs search" is shown every page that mentions either word,
+ * which on a documentation site is most of them, and the list stops being a
+ * ranking and becomes a filter they have to work through themselves.
+ *
+ * The weights are per field and stated rather than tuned: a match in a title is
+ * worth more than one in a body, and a match at the start of a title is worth more
+ * than one at its end, because a reader who types the first word of a page's name
+ * is usually right about which page they meant. `FIELD_WEIGHTS` is the whole of
+ * 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.
+ */
+export function SearchDialog({ indexUrl, label, messages, hint, onClose, limit = 12, className, }) {
+    const inputRef = useRef(null);
+    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 index, fetched once per dialog.
+     *
+     * The dialog is mounted only after a reader asks for search, so this runs after
+     * a deliberate act rather than on every page load, and the result is held for
+     * the life of the mount. A second fetch would be a second download of the same
+     * bytes for a reader who reopened the dialog, so `entries` is the cache and the
+     * `null` is what "not fetched yet" means.
+     *
+     * A failed fetch is a state rather than a throw. A reader whose network dropped
+     * is told the search is unavailable and still has the close control, which is
+     * the whole of what can be done here; an unhandled rejection would take the
+     * dialog's event handlers with it and leave a panel with no way out.
+     */
+    useEffect(() => {
+        if (entries !== null || failed)
+            return;
+        let live = true;
+        fetch(indexUrl)
+            .then((response) => {
+            if (!response.ok)
+                throw new Error(`search index responded ${response.status}`);
+            return response.json();
+        })
+            .then((value) => {
+            if (live)
+                setEntries(Array.isArray(value) ? value : []);
+        })
+            .catch(() => {
+            if (live)
+                setFailed(true);
+        });
+        return () => {
+            live = false;
+        };
+    }, [indexUrl, entries, failed]);
+    const results = useMemo(() => rank(entries, query, limit), [entries, query, limit]);
+    const typed = query.trim().length > 0;
+    const status = (() => {
+        if (!typed)
+            return hint ?? null;
+        if (failed)
+            return messages.failed;
+        if (entries === null)
+            return messages.loading;
+        if (results.length === 0)
+            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))) })] })] }) }));
+}
+/**
+ * What a match in each field is worth, and the whole of the ranking.
+ *
+ * A title match outranks a description match, which outranks a body match, because
+ * a page's name is the claim it makes about itself and its body is the evidence.
+ * The route carries a small weight of its own because a site whose routes are
+ * words, which is most of them, is searchable by them.
+ */
+const FIELD_WEIGHTS = { title: 40, url: 15, description: 10, content: 4 };
+/** What a match at the very start of a field adds on top of its weight. */
+const PREFIX_BONUS = 20;
+function fold(value) {
+    return (value ?? '').toLowerCase();
+}
+/**
+ * One entry's score for one query, or `null` when a token matched nothing.
+ *
+ * `null` rather than zero is what makes the conjunction work: a caller summing
+ * per-token scores cannot tell "matched with a low score" from "did not match",
+ * so the miss is returned as its own value and the entry is dropped there.
+ */
+function scoreEntry(entry, tokens) {
+    const fields = {
+        title: fold(entry.title),
+        url: fold(entry.url),
+        description: fold(entry.description),
+        content: fold(entry.content),
+    };
+    let total = 0;
+    for (const token of tokens) {
+        let best = 0;
+        for (const [field, value] of Object.entries(fields)) {
+            const at = value.indexOf(token);
+            if (at === -1)
+                continue;
+            const weight = FIELD_WEIGHTS[field];
+            best = Math.max(best, at === 0 ? weight + PREFIX_BONUS : weight);
+        }
+        if (best === 0)
+            return null;
+        total += best;
+    }
+    return total;
+}
+/**
+ * The index, narrowed by the query and cut to `limit`.
+ *
+ * The sort is by score and then by title, so two entries that match equally are
+ * in a stable order rather than in the order the index happened to be written.
+ * Without the second key a reordering of the build's page list would silently
+ * reorder equal-scoring results, which is the kind of change no test catches and
+ * every reader notices.
+ */
+function rank(entries, query, limit) {
+    const tokens = fold(query).split(/\s+/).filter(Boolean);
+    if (entries === null || tokens.length === 0)
+        return [];
+    const scored = [];
+    for (const entry of entries) {
+        const score = scoreEntry(entry, tokens);
+        if (score !== null)
+            scored.push({ entry, score });
+    }
+    scored.sort((a, b) => b.score - a.score || a.entry.title.localeCompare(b.entry.title));
+    return scored.slice(0, limit).map((row) => row.entry);
+}
+export default SearchDialog;

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

@@ -20,6 +20,32 @@ export declare function Section({ className, children, ...props }: React.Compone
  * placed, not about the block, which is why it is a prop and not a default.
  */
 export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+/**
+ * The level one step below a section's own heading, which is the level a title
+ * *inside* that section is composed at.
+ *
+ * **Why a function and not a second prop.** A block that draws a set of titled
+ * cards has two headings in it: the section's own, and one per card. Asking the
+ * caller for both is asking them to keep two levels in step by hand, and the two
+ * drift the moment a block is embedded one level deeper than it was written for.
+ * Deriving the child from the parent means a block moved from an `h2` section to an
+ * `h3` one carries its card titles with it, which is the whole reason
+ * `headingLevel` is a prop.
+ *
+ * This is what answers the question for every block that draws a titled card, so
+ * the answer is one function rather than six independent guesses. A block that
+ * hardcodes `h3` is right exactly once, at the nesting depth it was written for.
+ *
+ * **The clamp at `h6`, and why it is a clamp rather than a wrap.** A section
+ * already at `h6` has no child level, so a card title inside it is asked to be
+ * something it cannot be. Wrapping to `h1` would put a card's title above the
+ * section that introduces it, which is worse than a sibling of it: a reader
+ * navigating by heading would meet the card before the section it belongs to.
+ * Holding at `h6` costs a repeated level, which a screen reader announces as the
+ * same depth rather than as a break in the outline, and a `h6` section holding
+ * cards is already a document that has run out of levels.
+ */
+export declare function childLevel(level: HeadingLevel): HeadingLevel;
 /**
  * The heading a section opens with: an optional eyebrow, the title, an optional
  * supporting line, and the level of the one heading it renders.

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

@@ -1 +1 @@
-{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/components/ui/section.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC;;;GAGG;AACH,wBAAgB,OAAO,CAAC,EACtB,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,+BAWjC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAElE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,OAAO,EACP,KAAK,EACL,EAAE,EAAE,OAAc,EAClB,WAAW,EACX,KAAgB,EAChB,SAAS,GACV,EAAE;IACD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;IACzB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,YAAY,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,+BA6BA"}
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/components/ui/section.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC;;;GAGG;AACH,wBAAgB,OAAO,CAAC,EACtB,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,+BAWjC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAKlE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAG5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAC7B,KAAK,EACL,OAAO,EACP,KAAK,EACL,EAAE,EAAE,OAAc,EAClB,WAAW,EACX,KAAgB,EAChB,SAAS,GACV,EAAE;IACD;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;IACzB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,YAAY,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,+BA6BA"}

package/dist/components/ui/section.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * Container primitive. Every block composes its own section from this so vertical
  * rhythm stays consistent across the catalog instead of being re-invented per block.
@@ -7,6 +7,37 @@ import { cn } from '../../lib/utils';
 export function Section({ className, children, ...props }) {
     return (_jsx("section", { className: cn('py-16 sm:py-24', className), ...props, children: _jsx("div", { className: "mx-auto w-full max-w-6xl px-6 lg:px-8", children: children }) }));
 }
+/** The six levels in outline order, so a level can be stepped rather than compared. */
+const LEVELS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+/**
+ * The level one step below a section's own heading, which is the level a title
+ * *inside* that section is composed at.
+ *
+ * **Why a function and not a second prop.** A block that draws a set of titled
+ * cards has two headings in it: the section's own, and one per card. Asking the
+ * caller for both is asking them to keep two levels in step by hand, and the two
+ * drift the moment a block is embedded one level deeper than it was written for.
+ * Deriving the child from the parent means a block moved from an `h2` section to an
+ * `h3` one carries its card titles with it, which is the whole reason
+ * `headingLevel` is a prop.
+ *
+ * This is what answers the question for every block that draws a titled card, so
+ * the answer is one function rather than six independent guesses. A block that
+ * hardcodes `h3` is right exactly once, at the nesting depth it was written for.
+ *
+ * **The clamp at `h6`, and why it is a clamp rather than a wrap.** A section
+ * already at `h6` has no child level, so a card title inside it is asked to be
+ * something it cannot be. Wrapping to `h1` would put a card's title above the
+ * section that introduces it, which is worse than a sibling of it: a reader
+ * navigating by heading would meet the card before the section it belongs to.
+ * Holding at `h6` costs a repeated level, which a screen reader announces as the
+ * same depth rather than as a break in the outline, and a `h6` section holding
+ * cards is already a document that has run out of levels.
+ */
+export function childLevel(level) {
+    const at = LEVELS.indexOf(level);
+    return LEVELS[Math.min(at + 1, LEVELS.length - 1)];
+}
 /**
  * The heading a section opens with: an optional eyebrow, the title, an optional
  * supporting line, and the level of the one heading it renders.

package/dist/components/ui/select.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Select as SelectPrimitive } from '@base-ui/react/select';
 import { CheckIcon, ChevronDownIcon } from 'lucide-react';
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A control for choosing one option from a list that opens on demand.
  *

package/dist/components/ui/separator.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { cn } from '../../lib/utils';
+import { cn } from '../../lib/utils.js';
 /**
  * A hairline rule that divides content.
  *