@hackcove/ui-react 0.10.2 → 0.10.4

package/dist/Image.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useState } from "react";
 import { cx } from "./cx.js";
 import { Icon } from "./Icon.js";
+import { useImageFailed } from "./useImageFailed.js";
 const ASPECT = {
     square: "aspect-square",
     "4:3": "aspect-[4/3]",
@@ -48,11 +48,10 @@ function pictureLook(fit, framed) {
  * thumbnail with a label is a `MediaTile`.
  */
 export function Image({ src, alt, aspect = "4:3", fit = "cover", width = "full", framed = false, ...rest }) {
-    // The `src` that failed to load: a new `src` gets its own try, so a broken one never sticks.
-    const [failedSrc, setFailedSrc] = useState();
+    const { ref, failed, markFailed } = useImageFailed(src);
     const box = cx(FRAME, IMAGE_WIDTH[width]);
-    if (src && src !== failedSrc) {
-        return (_jsx("img", { ...rest, src: src, alt: alt, className: cx(box, ASPECT[aspect], pictureLook(fit, framed)), onError: () => setFailedSrc(src) }));
+    if (src && !failed) {
+        return (_jsx("img", { ...rest, ref: ref, src: src, alt: alt, className: cx(box, ASPECT[aspect], pictureLook(fit, framed)), onError: markFailed }));
     }
     return (_jsx("span", { ...rest, ...(alt ? { role: "img", "aria-label": alt } : { "aria-hidden": true }), className: cx(box, aspect === "natural" ? PLACEHOLDER_ASPECT : ASPECT[aspect], INSET, "grid place-items-center text-slate-400"), children: _jsx(Icon, { size: "lg", children: _jsx("svg", { viewBox: "0 0 20 20", fill: "currentColor", children: _jsx("path", { d: PICTURE }) }) }) }));
 }

package/dist/NavigationProgress.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import type { Passthrough } from "./props.js";
+/**
+ * A thin indeterminate bar along the top edge of the viewport, in the accent tone, for a route
+ * change that is under way and has no known length. Pass `active` from the router's pending state
+ * and render it once per app, beside the page frame. It draws exactly what `active` says: the bar
+ * while it is true and nothing while it is false. The stylesheet holds it invisible for the first
+ * 150ms, so a fast navigation shows nothing. It is fixed to the viewport and overlays the top of
+ * the header, so nothing on the page moves. Under `prefers-reduced-motion: reduce` it is a still
+ * bar.
+ */
+export declare function NavigationProgress({ active, label, ...rest }: {
+    /** True while a navigation is pending, e.g. from the router's state. */
+    active: boolean;
+    /**
+     * The bar's accessible name.
+     * @default Loading page
+     */
+    label?: string;
+} & Passthrough): ReactElement | null;

package/dist/NavigationProgress.js

@@ -0,0 +1,26 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BAR_FILL } from "./ProgressBar.js";
+// The one place the bar's motion lives: a stylesheet, as Tailwind classes cannot declare
+// `@keyframes`. Nothing here is a timer in script: the 150ms wait is the opacity animation's own
+// delay (backwards fill, so the bar is invisible until it ends), and a navigation that finishes
+// first removes the bar before it ever showed. A segment slides across the bar; under reduced
+// motion it is a still, full-width bar. No colour in it, which the bar's own class carries.
+const css = `@keyframes hc-navigation-progress-in{from{opacity:0}to{opacity:1}}
+@keyframes hc-navigation-progress{from{transform:translateX(-100%)}to{transform:translateX(250%)}}
+[data-navigation-progress]{animation:hc-navigation-progress-in .01s linear 150ms backwards}
+[data-navigation-progress-bar]{width:40%;animation:hc-navigation-progress 1.4s ease-in-out infinite}
+@media (prefers-reduced-motion:reduce){[data-navigation-progress-bar]{width:100%;animation:none}}`;
+/**
+ * A thin indeterminate bar along the top edge of the viewport, in the accent tone, for a route
+ * change that is under way and has no known length. Pass `active` from the router's pending state
+ * and render it once per app, beside the page frame. It draws exactly what `active` says: the bar
+ * while it is true and nothing while it is false. The stylesheet holds it invisible for the first
+ * 150ms, so a fast navigation shows nothing. It is fixed to the viewport and overlays the top of
+ * the header, so nothing on the page moves. Under `prefers-reduced-motion: reduce` it is a still
+ * bar.
+ */
+export function NavigationProgress({ active, label = "Loading page", ...rest }) {
+    if (!active)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: css }), _jsx("div", { ...rest, role: "progressbar", "aria-label": label, "data-navigation-progress": "", className: "pointer-events-none fixed inset-x-0 top-0 z-50 h-[3px] overflow-hidden", children: _jsx("div", { "data-navigation-progress-bar": "", className: `h-full ${BAR_FILL.accent}` }) })] }));
+}

package/dist/PageLayouts.js

@@ -4,8 +4,9 @@ import { Card } from "./Card.js";
 import { cx } from "./cx.js";
 import { PageHeader, PageHeaderContent } from "./PageHeader.js";
 import { STACK_WIDTH, Stack } from "./Stack.js";
+import { useScrollEdges } from "./scrollEdges.js";
 import { scrollStopProps, useScrollStop } from "./scrollStop.js";
-import { STICKY_ASIDE_LG, STICKY_SCROLL_LG } from "./stickyColumn.js";
+import { STICKY_ASIDE_LG, STICKY_FADE_LG, STICKY_SCROLL_LG } from "./stickyColumn.js";
 import { StickyBar } from "./StickyBar.js";
 // Compositions of the layout foundation. None sets a page width or outer padding of its own; the
 // ones that narrow their content do it inside the Container they are rendered in.
@@ -20,9 +21,10 @@ export function ListLayout({ filters, empty, isEmpty = false, children, breadcru
  * itself so its end stays reachable.
  */
 export function DetailLayout({ aside, asideLabel, stickyAside = false, children, breadcrumbs, title, subtitle, actions, tabs, ...rest }) {
-    const { attach, stop } = useScrollStop();
+    const { element, attach, stop } = useScrollStop();
+    useScrollEdges(element, "y");
     const { props, ring } = scrollStopProps(stickyAside && stop, { label: asideLabel });
-    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: cx("min-w-0", stickyAside && STICKY_ASIDE_LG), "aria-label": asideLabel, children: _jsx("div", { ref: stickyAside ? attach : undefined, ...props, className: stickyAside ? cx(STICKY_SCROLL_LG, ring) : undefined, children: _jsx(Stack, { children: aside }) }) })] })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(PageHeader, { breadcrumbs: breadcrumbs, title: title, subtitle: subtitle, actions: actions, tabs: tabs }), _jsxs("div", { ...rest, className: "grid gap-6 lg:grid-cols-3", children: [_jsx("div", { className: "min-w-0 lg:col-span-2", children: _jsx(Stack, { children: children }) }), _jsx("aside", { className: cx("min-w-0", stickyAside && STICKY_ASIDE_LG), "aria-label": asideLabel, children: _jsx("div", { ref: stickyAside ? attach : undefined, ...props, className: stickyAside ? cx(STICKY_SCROLL_LG, STICKY_FADE_LG, ring) : undefined, children: _jsx(Stack, { children: aside }) }) })] })] }));
 }
 /** A form page: header (no header `actions`), then a `max-w-3xl` column that starts at the Container's left edge (it is not re-centred), with an `actions` row at the end. Other props go on the `<form>`. */
 export function FormLayout({ actions, children, breadcrumbs, title, subtitle, tabs, ...form }) {

package/dist/SidebarLayout.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode } from "react";
+import { type ReactElement, type ReactNode } from "react";
 import type { Passthrough } from "./props.js";
 /**
  * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
@@ -10,7 +10,10 @@ import type { Passthrough } from "./props.js";
  * above the canvas and nothing sticks. A long rail sets `railLabel`:
  * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
  * phone, and from `md` it is the same rail; `railLabel` also names the rail's `<aside>` landmark. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ * border or a fixed height, and it no longer sits beside the canvas on a phone. Once the page has
+ * loaded, a rail that scrolls shows its current link (the one with `aria-current`) in view, and the
+ * folded disclosure reads `railLabel` and the current link's name ("All components: Button"); both
+ * need the layout to hydrate.
  */
 export declare function SidebarLayout({ rail, railLabel, children, ...rest }: {
     /** The links beside the canvas, usually a `Tabs variant="pill" orientation="vertical"`. */

package/dist/SidebarLayout.js

@@ -1,8 +1,28 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
 import { cx } from "./cx.js";
 import { FoldedColumn } from "./foldedColumn.js";
+import { useScrollEdges } from "./scrollEdges.js";
 import { scrollStopProps, useScrollStop } from "./scrollStop.js";
-import { STICKY_ASIDE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
+import { STICKY_ASIDE_MD, STICKY_BAR_MD, STICKY_FADE_MD, STICKY_INK_MD, STICKY_SCROLL_MD, } from "./stickyColumn.js";
+/** The rail's current link: the one `Tabs` marks with `aria-current`. */
+const CURRENT = '[aria-current]:not([aria-current="false"])';
+/** The room the scroller's fade takes at each edge (`STICKY_FADE_MD`'s 1.5rem), in px. */
+const FADE = 24;
+/**
+ * Scrolls `scroller` (only it, never the page, which `scrollIntoView` would also move) so `item`
+ * sits in the middle of its visible part. Left alone when it is already clear of the faded edges, or
+ * when the scroller does not scroll (below `md`, or a rail that fits).
+ */
+function scrollToCentre(scroller, item) {
+    if (scroller.scrollHeight <= scroller.clientHeight)
+        return;
+    const box = scroller.getBoundingClientRect();
+    const at = item.getBoundingClientRect();
+    if (at.top >= box.top + FADE && at.bottom <= box.bottom - FADE)
+        return;
+    scroller.scrollTop += at.top + at.height / 2 - (box.top + box.height / 2);
+}
 /**
  * A `rail` of links beside the `children` canvas, in the Container the shell already gives every
  * page (a plain `<AppShell>`, no `bleed`): the rail starts at the header logo's x and the canvas
@@ -13,10 +33,40 @@ import { STICKY_ASIDE_MD, STICKY_SCROLL_MD } from "./stickyColumn.js";
  * above the canvas and nothing sticks. A long rail sets `railLabel`:
  * below `md` it then folds behind a disclosure of that name, closed, so the page comes first on a
  * phone, and from `md` it is the same rail; `railLabel` also names the rail's `<aside>` landmark. Upgrading from 0.2: the rail no longer has a fill, a
- * border or a fixed height, and it no longer sits beside the canvas on a phone.
+ * border or a fixed height, and it no longer sits beside the canvas on a phone. Once the page has
+ * loaded, a rail that scrolls shows its current link (the one with `aria-current`) in view, and the
+ * folded disclosure reads `railLabel` and the current link's name ("All components: Button"); both
+ * need the layout to hydrate.
  */
 export function SidebarLayout({ rail, railLabel, children, ...rest }) {
-    const { attach, stop } = useScrollStop();
+    const { element, attach, stop } = useScrollStop();
+    useScrollEdges(element, "y");
+    const [current, setCurrent] = useState(undefined);
+    const scrolledTo = useRef(null);
+    // The current link is scrolled into view once, and its name goes on the folded disclosure. It is
+    // read when the layout mounts and again whenever the rail's links change (a consumer's router
+    // moving `aria-current` to another link).
+    useEffect(() => {
+        if (!element)
+            return undefined;
+        const sync = () => {
+            const item = element.querySelector(CURRENT);
+            setCurrent(item?.textContent?.trim() || undefined);
+            if (item && item !== scrolledTo.current)
+                scrollToCentre(element, item);
+            scrolledTo.current = item;
+        };
+        queueMicrotask(sync);
+        const change = new MutationObserver(sync);
+        change.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: ["aria-current"],
+        });
+        return () => change.disconnect();
+    }, [element]);
     const { props, ring } = scrollStopProps(stop, { label: railLabel });
-    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, ring), children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: railLabel, children: rail })) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
+    return (_jsxs("div", { ...rest, className: "flex flex-col gap-8 md:flex-row md:gap-10", children: [_jsx("aside", { className: cx("w-full shrink-0 md:w-56", STICKY_ASIDE_MD), "aria-label": railLabel, children: _jsx("div", { ref: attach, ...props, className: cx(STICKY_SCROLL_MD, STICKY_BAR_MD, STICKY_FADE_MD, ring), children: _jsx("div", { className: STICKY_INK_MD, children: railLabel === undefined ? (rail) : (_jsx(FoldedColumn, { from: "md", label: current === undefined ? railLabel : `${railLabel}: ${current}`, children: rail })) }) }) }), _jsx("div", { className: "min-w-0 flex-1", children: children })] }));
 }

package/dist/SiteSearch.d.ts

@@ -0,0 +1,32 @@
+import { type ReactElement } from "react";
+import type { Passthrough } from "./props.js";
+/** One page the search can find. */
+export type SiteSearchItem = {
+    /** The page's name: the row's label and the first thing matched. */
+    label: string;
+    /** A muted line under the label, matched last. */
+    description?: string | undefined;
+    /** Where the row goes. */
+    href: string;
+    /** Other names the page answers to (the exports it documents), matched like the label but not shown. */
+    keywords?: string[] | undefined;
+};
+/**
+ * The items that match `text`, best first: the label starts with it, then the label contains it,
+ * then a keyword contains it, then the description does. Case is ignored, and items of the same
+ * rank keep their order in `items`. Empty text matches nothing.
+ */
+export declare function rankSiteSearch(items: readonly SiteSearchItem[], text: string): SiteSearchItem[];
+/**
+ * The site's search: a header button that opens a dialog with a search field over a list of links
+ * to the pages that match. Put it in `AppShell`'s `controls` and pass every page as `items`. Ctrl+K
+ * (⌘ K on a Mac) opens it from anywhere on the page, and the button shows that key. Typing filters
+ * by name, then by `keywords`, then by description; Enter opens the first result, the arrow keys
+ * move through them, and Esc closes it and puts focus back where it was. Render it once per page.
+ */
+export declare function SiteSearch({ items, label, ...rest }: {
+    /** Every page to search, in the order ties are listed (the rail's order). */
+    items: readonly SiteSearchItem[];
+    /** The dialog's title and the button's accessible name: "Search components". */
+    label: string;
+} & Passthrough): ReactElement;

package/dist/SiteSearch.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState, useSyncExternalStore, } from "react";
+import { Button } from "./Button.js";
+import { Dialog } from "./Dialog.js";
+import { Icon } from "./Icon.js";
+import { IconButton } from "./IconButton.js";
+import { Input } from "./Input.js";
+import { Kbd } from "./Kbd.js";
+import { ListRow } from "./ListRow.js";
+import { Text } from "./typography.js";
+/**
+ * The items that match `text`, best first: the label starts with it, then the label contains it,
+ * then a keyword contains it, then the description does. Case is ignored, and items of the same
+ * rank keep their order in `items`. Empty text matches nothing.
+ */
+export function rankSiteSearch(items, text) {
+    const query = text.trim().toLowerCase();
+    if (query === "")
+        return [];
+    const rankOf = (item) => {
+        const label = item.label.toLowerCase();
+        if (label.startsWith(query))
+            return 0;
+        if (label.includes(query))
+            return 1;
+        if (item.keywords?.some((keyword) => keyword.toLowerCase().includes(query)))
+            return 2;
+        if (item.description?.toLowerCase().includes(query))
+            return 3;
+        return -1;
+    };
+    return items
+        .map((item, index) => ({ item, index, rank: rankOf(item) }))
+        .filter((entry) => entry.rank >= 0)
+        .toSorted((a, b) => a.rank - b.rank || a.index - b.index)
+        .map((entry) => entry.item);
+}
+/** What the live region says for a result count. */
+function countText(query, count) {
+    if (query.trim() === "")
+        return "";
+    if (count === 0)
+        return "No results";
+    return count === 1 ? "1 result" : `${count} results`;
+}
+// The shortcut's key reads ⌘ K on Apple platforms. The server cannot know, so it renders Ctrl K and
+// the client swaps after hydration.
+const noSubscribe = () => () => { };
+const isApple = () => /mac|iphone|ipad|ipod/i.test(typeof navigator === "undefined" ? "" : navigator.userAgent);
+/** Ctrl+K or Cmd+K with no other modifier, the one shortcut that opens the search. */
+function isShortcut(event) {
+    return ((event.ctrlKey || event.metaKey) &&
+        !event.altKey &&
+        !event.shiftKey &&
+        event.key.toLowerCase() === "k");
+}
+// A link that stays on the page (a hash, an app's router) still closes the search; one opened in a
+// new tab or window leaves it open.
+function onListClick(event) {
+    if (event.ctrlKey || event.metaKey || event.shiftKey)
+        return;
+    if (event.target instanceof Element && event.target.closest("a[href]")) {
+        event.currentTarget.closest("dialog")?.close();
+    }
+}
+/** The result links in the list, in order. */
+function linksIn(list) {
+    return list ? [...list.querySelectorAll("a[href]")] : [];
+}
+function SearchBody({ items, label }) {
+    const [query, setQuery] = useState("");
+    const box = useRef(null);
+    const list = useRef(null);
+    const results = rankSiteSearch(items, query);
+    const typed = query.trim() !== "";
+    const onFieldKey = (event) => {
+        if (event.key === "Escape") {
+            // Close here, so no engine spends the first Esc clearing the search field.
+            event.preventDefault();
+            event.currentTarget.closest("dialog")?.close();
+        }
+        else if (event.key === "Enter") {
+            event.preventDefault();
+            linksIn(list.current)[0]?.click();
+        }
+        else if (event.key === "ArrowDown") {
+            const first = linksIn(list.current)[0];
+            if (first) {
+                event.preventDefault();
+                first.focus();
+            }
+        }
+    };
+    const onListKey = (event) => {
+        if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
+            return;
+        const links = linksIn(list.current);
+        const at = links.findIndex((link) => link === document.activeElement);
+        if (at < 0)
+            return;
+        event.preventDefault();
+        const next = at + (event.key === "ArrowDown" ? 1 : -1);
+        if (next < 0)
+            box.current?.querySelector("input")?.focus();
+        else
+            links[Math.min(next, links.length - 1)]?.focus();
+    };
+    return (_jsxs("div", { ref: box, className: "flex flex-col gap-3", children: [_jsx(Input, { type: "search", icon: _jsx(Icon, { name: "search" }), "aria-label": label, placeholder: "Search", autoComplete: "off", spellCheck: false, value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: onFieldKey }), _jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: countText(query, results.length) }), !typed && (_jsx(Text, { as: "p", tone: "muted", children: "Type a name" })), typed && results.length === 0 && (_jsxs(Text, { as: "p", tone: "muted", children: ["No results for ", query.trim()] })), results.length > 0 && (_jsx("ul", { ref: list, "aria-label": "Results", onKeyDown: onListKey, onClick: onListClick, children: results.map((item, index) => (_jsx("li", { children: _jsx(ListRow, { href: item.href, size: "sm", divided: index > 0, secondary: item.description, children: item.label }) }, item.href))) }))] }));
+}
+/**
+ * The site's search: a header button that opens a dialog with a search field over a list of links
+ * to the pages that match. Put it in `AppShell`'s `controls` and pass every page as `items`. Ctrl+K
+ * (⌘ K on a Mac) opens it from anywhere on the page, and the button shows that key. Typing filters
+ * by name, then by `keywords`, then by description; Enter opens the first result, the arrow keys
+ * move through them, and Esc closes it and puts focus back where it was. Render it once per page.
+ */
+export function SiteSearch({ items, label, ...rest }) {
+    const [open, setOpen] = useState(false);
+    const opener = useRef(null);
+    const apple = useSyncExternalStore(noSubscribe, isApple, () => false);
+    const keys = apple ? "⌘ K" : "Ctrl K";
+    // Before paint, so a client-rendered trigger that is on screen already answers the shortcut.
+    useLayoutEffect(() => {
+        const onKey = (event) => {
+            if (event.defaultPrevented || event.repeat || !isShortcut(event))
+                return;
+            event.preventDefault();
+            // Only the press that opens it records the opener; `close` clears it.
+            if (!opener.current && document.activeElement instanceof HTMLElement) {
+                opener.current = document.activeElement;
+            }
+            setOpen(true);
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, []);
+    // A pointer click does not focus a button in every engine, so the trigger is remembered by hand.
+    const openFrom = (event) => {
+        opener.current = event.currentTarget;
+        setOpen(true);
+    };
+    const close = () => {
+        setOpen(false);
+        const back = opener.current;
+        opener.current = null;
+        if (back?.isConnected && back !== document.body)
+            back.focus();
+    };
+    return (_jsxs("span", { ...rest, className: "inline-flex", children: [_jsx("span", { className: "hidden sm:inline-flex", children: _jsxs(Button, { variant: "outline", size: "sm", "aria-label": label, "aria-haspopup": "dialog", "aria-keyshortcuts": "Control+K Meta+K", onClick: openFrom, children: [_jsx(Icon, { name: "search", size: "sm" }), "Search", _jsx(Kbd, { children: keys })] }) }), _jsx("span", { className: "inline-flex sm:hidden", children: _jsx(IconButton, { label: label, size: "sm", "aria-haspopup": "dialog", "aria-keyshortcuts": "Control+K Meta+K", onClick: openFrom, children: _jsx(Icon, { name: "search", size: "sm" }) }) }), open && (_jsx(Dialog, { title: label, size: "md", onClose: close, children: _jsx(SearchBody, { items: items, label: label }) }))] }));
+}

package/dist/Stack.d.ts

@@ -66,7 +66,12 @@ type StackProps = StackBase & (({
  * title row, `actions` included, as `SectionHeading`'s `rule` does for a bare heading. A line
  * between two sections is a `Divider` in the `Stack` that holds them.
  */
-export declare function Section({ title, actions, rule, gap, width, children, ...rest }: {
+export declare function Section({ id, title, actions, rule, gap, width, children, ...rest }: {
+    /**
+     * Makes the section a link target: `#<id>` scrolls to its heading, which stops below the sticky
+     * AppShell header. Needs a `title`: with no title the heading that carries it is not rendered.
+     */
+    id?: string | undefined;
     /** A `SectionHeading` at the top, which names the section. */
     title?: ReactNode;
     /** Buttons or links at the end of the title row. */

package/dist/Stack.js

@@ -47,13 +47,18 @@ export function Stack({ gap = "md", width = "default", rowFrom, as = "div", chil
 function Box({ tag: Tag, ...props }) {
     return _jsx(Tag, { ...props });
 }
+/** The id a `Section`'s heading takes: the caller's, or one of React's. */
+function useHeadingId(id) {
+    const generated = useId();
+    return id ?? generated;
+}
 /**
  * A `<section>` Stack with an optional `SectionHeading` title (which names it) and `actions` beside
  * it. Its blocks are `gap` apart, `md` by default as in a `Stack`. `rule` draws a hairline under the
  * title row, `actions` included, as `SectionHeading`'s `rule` does for a bare heading. A line
  * between two sections is a `Divider` in the `Stack` that holds them.
  */
-export function Section({ title, actions, rule = false, gap = "md", width = "default", children, ...rest }) {
-    const titleId = useId();
+export function Section({ id, title, actions, rule = false, gap = "md", width = "default", children, ...rest }) {
+    const titleId = useHeadingId(id);
     return (_jsxs(Stack, { as: "section", ...rest, gap: gap, width: width, "aria-labelledby": title ? titleId : rest["aria-labelledby"], children: [(title || actions) && (_jsxs("div", { className: cx("flex items-center justify-between gap-4", rule && "border-b border-slate-200/70 pb-2"), children: [title && _jsx(SectionHeading, { id: titleId, children: title }), actions && _jsx("div", { className: "ml-auto flex items-center gap-2", children: actions })] })), children] }));
 }

package/dist/copyScript.d.ts

@@ -0,0 +1,13 @@
+/**
+ * JavaScript to inline once on a page that is rendered to static HTML and never hydrated, so every
+ * `CopyButton` (and the `CopyLine`, `CodeBlock` and `CodeExample` copy buttons) works there too.
+ * One click listener on `document` reads what to copy from the button's data attributes, writes the
+ * clipboard, then does what `CopyButton` does: sets `data-copied` again after a reflow, so the CSS
+ * that shows the copied label for two seconds starts over, and puts a new node holding the copied
+ * label in the status region beside the button, so a screen reader hears each copy. No timer: the
+ * label goes back when the animation ends, and its end clears `data-copied` (a second listener), so a
+ * button hidden and shown again does not replay it. A refused or missing clipboard leaves it alone.
+ * Whichever of the script and a hydrated button's own handler hears a click first copies and flags
+ * the event (`copyHandled`), and the other skips it: one copy per click.
+ */
+export declare const copyScript: string;

package/dist/copyScript.js

@@ -0,0 +1,13 @@
+/**
+ * JavaScript to inline once on a page that is rendered to static HTML and never hydrated, so every
+ * `CopyButton` (and the `CopyLine`, `CodeBlock` and `CodeExample` copy buttons) works there too.
+ * One click listener on `document` reads what to copy from the button's data attributes, writes the
+ * clipboard, then does what `CopyButton` does: sets `data-copied` again after a reflow, so the CSS
+ * that shows the copied label for two seconds starts over, and puts a new node holding the copied
+ * label in the status region beside the button, so a screen reader hears each copy. No timer: the
+ * label goes back when the animation ends, and its end clears `data-copied` (a second listener), so a
+ * button hidden and shown again does not replay it. A refused or missing clipboard leaves it alone.
+ * Whichever of the script and a hydrated button's own handler hears a click first copies and flags
+ * the event (`copyHandled`), and the other skips it: one copy per click.
+ */
+export const copyScript = `document.addEventListener("click",function(e){var b=e.target.closest&&e.target.closest("[data-copy-text]"),c=navigator.clipboard;if(!b||!c||e.copyHandled||b.disabled)return;e.copyHandled=1;c.writeText(b.dataset.copyText).then(function(){var r=b.nextElementSibling;b.removeAttribute("data-copied");void b.offsetWidth;b.setAttribute("data-copied","");if(r&&r.matches("[data-copy-status]"))r.replaceChildren(b.dataset.copyCopied)},function(){})});document.addEventListener("animationend",function(e){var b=e.target.closest&&e.target.closest("[data-copied]");if(b)b.removeAttribute("data-copied")})`;

package/dist/icons.d.ts

@@ -6,8 +6,8 @@ import type { ReactElement } from "react";
  * icon's own shapes carry no `fill`, `stroke` or `stroke-width` (`Icon.test.tsx` holds them to
  * that). A name is the idea or action the icon stands for, not a product.
  */
-declare const NAMES: readonly ["diff", "baseline", "review", "ci", "self-host", "privacy", "capture", "branch", "theme", "speed", "search", "chevron-right", "chevron-down", "close", "external-link", "settings", "bell", "check", "plus"];
-/** The names of the icon set: feature ideas, then UI glyphs. */
+declare const NAMES: readonly ["diff", "baseline", "review", "ci", "self-host", "privacy", "capture", "branch", "theme", "speed", "search", "chevron-right", "chevron-down", "close", "external-link", "settings", "bell", "check", "plus", "grid", "window", "type", "card", "pointer", "field", "table", "compass", "page", "briefcase"];
+/** The names of the icon set: feature ideas, then UI glyphs, then the ideas the docs sections stand for. */
 export type IconName = (typeof NAMES)[number];
 /** The icon `name` as an `<svg>`: the set's one grid, stroke, caps and joins, drawn in `currentColor`. */
 export declare function iconGlyph(name: IconName): ReactElement;

package/dist/icons.js

@@ -26,6 +26,16 @@ const NAMES = [
     "bell",
     "check",
     "plus",
+    "grid",
+    "window",
+    "type",
+    "card",
+    "pointer",
+    "field",
+    "table",
+    "compass",
+    "page",
+    "briefcase",
 ];
 const GLYPHS = {
     /** Before and after, side by side: a minus on the left, a plus on the right. */
@@ -66,6 +76,26 @@ const GLYPHS = {
     check: _jsx("path", { d: "m4.5 12.5 5 5L19.5 7" }),
     /** Add or create: two strokes crossing, upright. */
     plus: _jsx("path", { d: "M12 5v14M5 12h14" }),
+    /** Things laid out in a grid: four tiles. */
+    grid: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3.5", y: "3.5", width: "7", height: "7", rx: "1.5" }), _jsx("rect", { x: "13.5", y: "3.5", width: "7", height: "7", rx: "1.5" }), _jsx("rect", { x: "3.5", y: "13.5", width: "7", height: "7", rx: "1.5" }), _jsx("rect", { x: "13.5", y: "13.5", width: "7", height: "7", rx: "1.5" })] })),
+    /** A whole page's frame: a window with a title bar and a panel down the side. */
+    window: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4.5", width: "18", height: "15", rx: "2.5" }), _jsx("path", { d: "M3 9h18M9.5 9v10.5M6.5 6.75h.01M9 6.75h.01" })] })),
+    /** Text and its styles: a capital T. */
+    type: _jsx("path", { d: "M5.5 7V5h13v2M12 5v14M9 19h6" }),
+    /** A unit of content: a card with a title line and lines of body. */
+    card: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4.5", width: "18", height: "15", rx: "2.5" }), _jsx("path", { d: "M7 9h5M7 12.5h10M7 15.75h7" })] })),
+    /** Something to press: a pointer arrow. */
+    pointer: _jsx("path", { d: "M7 4.5v13.2l3.3-3.1 2.4 5 2.2-1-2.3-4.9h4.6Z" }),
+    /** Something to type in: a text field with its text and caret. */
+    field: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "7.5", width: "18", height: "9", rx: "2.5" }), _jsx("path", { d: "M7 12h4M13.5 9.5v5" })] })),
+    /** Rows and columns of data: a table with a header row and a first column. */
+    table: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "4.5", width: "18", height: "15", rx: "2.5" }), _jsx("path", { d: "M3 9.5h18M3 14.5h18M9.5 9.5v10" })] })),
+    /** Finding your way around: a compass with its needle. */
+    compass: (_jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "9" }), _jsx("path", { d: "m15.5 8.5-2 5-5 2 2-5Z" })] })),
+    /** A whole page of its own: a sheet with a folded corner and lines of text. */
+    page: (_jsxs(_Fragment, { children: [_jsx("path", { d: "M7.5 3H14l5 5v10.5a2.5 2.5 0 0 1-2.5 2.5h-9A2.5 2.5 0 0 1 5 18.5v-13A2.5 2.5 0 0 1 7.5 3Z" }), _jsx("path", { d: "M14 3v3.5A1.5 1.5 0 0 0 15.5 8H19M9 13h6M9 16.5h6" })] })),
+    /** Work for hire: a briefcase with its handle and clasp. */
+    briefcase: (_jsxs(_Fragment, { children: [_jsx("rect", { x: "3", y: "7.5", width: "18", height: "12", rx: "2.5" }), _jsx("path", { d: "M8.5 7.5V6a2 2 0 0 1 2-2h3a2 2 0 0 1 2 2v1.5M3 13h18M12 12v2.5" })] })),
 };
 /** The icon `name` as an `<svg>`: the set's one grid, stroke, caps and joins, drawn in `currentColor`. */
 export function iconGlyph(name) {

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, type AppShellBreakpoint, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader, type PageHeaderProps } from "./PageHeader.js";
+export { Hero, type HeroProps } from "./Hero.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, } from "./PageLayouts.js";
 export { SidebarLayout } from "./SidebarLayout.js";
 export { SideColumn, type SideColumnWidth } from "./SideColumn.js";
@@ -43,7 +44,9 @@ export { CodeExample } from "./CodeExample.js";
 export { Disclosure } from "./Disclosure.js";
 export { Divider } from "./Divider.js";
 export { PageFade, startPageTransition } from "./PageFade.js";
+export { NavigationProgress } from "./NavigationProgress.js";
 export { Dialog, type DialogProps } from "./Dialog.js";
+export { SiteSearch, type SiteSearchItem } from "./SiteSearch.js";
 export { Drawer, type DrawerProps } from "./Drawer.js";
 export { Lightbox, type LightboxProps } from "./Lightbox.js";
 export { Icon } from "./Icon.js";
@@ -59,6 +62,7 @@ export { Switch } from "./Switch.js";
 export { Radio, RadioGroup } from "./RadioGroup.js";
 export { FileDrop } from "./FileDrop.js";
 export { CopyButton } from "./CopyButton.js";
+export { copyScript } from "./copyScript.js";
 export { CopyLine } from "./CopyLine.js";
 export { Field } from "./Field.js";
 export { FormGrid, FormRow, FormRowField, type FormRowSpan } from "./FormRow.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";
 export { PageHeader } from "./PageHeader.js";
+export { Hero } from "./Hero.js";
 export { CardGrid, CenteredLayout, DetailLayout, FormLayout, FullBleedLayout, ListLayout, ProseLayout, } from "./PageLayouts.js";
 export { SidebarLayout } from "./SidebarLayout.js";
 export { SideColumn } from "./SideColumn.js";
@@ -42,7 +43,9 @@ export { CodeExample } from "./CodeExample.js";
 export { Disclosure } from "./Disclosure.js";
 export { Divider } from "./Divider.js";
 export { PageFade, startPageTransition } from "./PageFade.js";
+export { NavigationProgress } from "./NavigationProgress.js";
 export { Dialog } from "./Dialog.js";
+export { SiteSearch } from "./SiteSearch.js";
 export { Drawer } from "./Drawer.js";
 export { Lightbox } from "./Lightbox.js";
 export { Icon } from "./Icon.js";
@@ -57,6 +60,7 @@ export { Switch } from "./Switch.js";
 export { Radio, RadioGroup } from "./RadioGroup.js";
 export { FileDrop } from "./FileDrop.js";
 export { CopyButton } from "./CopyButton.js";
+export { copyScript } from "./copyScript.js";
 export { CopyLine } from "./CopyLine.js";
 export { Field } from "./Field.js";
 export { FormGrid, FormRow, FormRowField } from "./FormRow.js";

package/dist/scrollEdges.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export declare function useScrollEdges(element: HTMLElement | null, axis: "x" | "y"): void;

package/dist/scrollEdges.js

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+/**
+ * Marks a box that scrolls with which of its edges still has content past it, so the layout can fade
+ * them: `data-more-start` (scrolled away from the start), `data-more-end` (more to scroll to) and
+ * `data-more` for either. `axis` is the way it scrolls: `x` (a row) or `y` (a column). A box that
+ * fits carries none. The attributes only carry state; a class turns them into a `mask-image`, so the
+ * fade follows any theme. `element` is the box once it is mounted (null before, and then nothing
+ * happens).
+ *
+ * The effect runs after every render on purpose: the box's children may have changed, and each one
+ * needs observing so a change in its size is noticed.
+ */
+export function useScrollEdges(element, axis) {
+    useEffect(() => {
+        if (!element)
+            return undefined;
+        const el = element;
+        const update = () => {
+            const [position, scrollSize, clientSize] = axis === "x"
+                ? [el.scrollLeft, el.scrollWidth, el.clientWidth]
+                : [el.scrollTop, el.scrollHeight, el.clientHeight];
+            const start = position > 1;
+            const end = scrollSize - clientSize - position > 1;
+            el.toggleAttribute("data-more-start", start);
+            el.toggleAttribute("data-more-end", end);
+            el.toggleAttribute("data-more", start || end);
+        };
+        update();
+        el.addEventListener("scroll", update, { passive: true });
+        // jsdom (a consumer's own tests) has no ResizeObserver.
+        const resize = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(update);
+        resize?.observe(el);
+        for (const child of el.children)
+            resize?.observe(child);
+        return () => {
+            el.removeEventListener("scroll", update);
+            resize?.disconnect();
+        };
+    });
+}