@nibapp/ui 0.0.0-stage → 0.1.0

package/dist/lib/text.js

@@ -0,0 +1,149 @@
+/**
+ * Text measured and shaped the way people read it: in graphemes (`Intl.Segmenter`), so a cut never
+ * splits an emoji, a flag or a letter with its accents, in any script; cased, sorted and listed in the
+ * reader's locale. Each `Intl` object is built once per locale and options and kept, keyed by them, so
+ * one process can serve several locales.
+ */
+const segmenters = new Map();
+const collators = new Map();
+const listFormats = new Map();
+function once(cache, key, make) {
+    let value = cache.get(key);
+    if (value === undefined) {
+        value = make();
+        cache.set(key, value);
+    }
+    return value;
+}
+/** Grapheme boundaries don't vary by locale today; the locale only keys the segmenter. */
+function graphemes(locale) {
+    return once(segmenters, locale ?? "", () => new Intl.Segmenter(locale, { granularity: "grapheme" }));
+}
+/**
+ * How many words the text has, as its language divides them (`Intl.Segmenter`, granularity
+ * `word`): Chinese or Japanese, written without spaces, count word by word too.
+ */
+export function wordCount(text, locale) {
+    const words = once(segmenters, `${locale ?? ""} word`, () => new Intl.Segmenter(locale, { granularity: "word" }));
+    let count = 0;
+    for (const segment of words.segment(text))
+        if (segment.isWordLike === true)
+            count += 1;
+    return count;
+}
+/** The first grapheme of `text` ("é" of "élan", "👩‍💻" of "👩‍💻 dev"); empty for empty text. */
+function firstGrapheme(text, locale) {
+    return graphemes(locale).segment(text).containing(0)?.segment ?? "";
+}
+/** The text's graphemes, the characters a reader sees ("é" and "👍🏽" are one each). */
+export function graphemesOf(text, locale) {
+    return Array.from(graphemes(locale).segment(text), ({ segment }) => segment);
+}
+/**
+ * The text cut to at most `max` graphemes, an ellipsis standing in for the rest. It reads at most
+ * `max + 1` graphemes, however long the text.
+ */
+export function truncateText(text, max, locale) {
+    // Every grapheme is at least one UTF-16 unit: text this short can't be over.
+    if (text.length <= max)
+        return text;
+    let count = 0;
+    let keep = 0;
+    for (const { index } of graphemes(locale).segment(text)) {
+        count += 1;
+        if (count === max)
+            keep = index;
+        else if (count > max)
+            return `${text.slice(0, keep).trimEnd()}…`;
+    }
+    return text;
+}
+/** The text's first `count` graphemes ("Éla" of "Élan" for 3); it reads no further than that. */
+export function graphemePrefix(text, count, locale) {
+    let taken = 0;
+    for (const { index } of graphemes(locale).segment(text)) {
+        if (taken === count)
+            return text.slice(0, index);
+        taken += 1;
+    }
+    return text;
+}
+/**
+ * The longest start of the text within `max` UTF-16 units that ends between graphemes: typed text
+ * kept to a cap a schema counts in `.length`, never splitting an emoji or a letter from its accents.
+ * No ellipsis: it is what the person typed, shortened.
+ */
+export function clipToLength(text, max, locale) {
+    if (text.length <= max)
+        return text;
+    let end = 0;
+    for (const { index, segment } of graphemes(locale).segment(text)) {
+        if (index + segment.length > max)
+            break;
+        end = index + segment.length;
+    }
+    return text.slice(0, end);
+}
+/** A collator for `locale`: lists people read sort in their own language's order. */
+export function collatorFor(locale, options = {}) {
+    return once(collators, `${locale} ${JSON.stringify(options)}`, () => new Intl.Collator(locale, options));
+}
+/** Items as one phrase in a locale's list pattern ("a, b and c", "a, b or c"), as the catalogues join them. */
+export function formatList(items, locale, type = "conjunction") {
+    return once(listFormats, `${locale} ${type}`, () => new Intl.ListFormat(locale, { type })).format(items);
+}
+/**
+ * The parts of one status as a screen reader says them ("Running, rate limited, 1 minute"): the
+ * language's own list separator and no "and" ("a、b、c" in Japanese). It's the narrow conjunction
+ * pattern, which every ICU build separates; the `unit` pattern lost its Russian commas in newer CLDR.
+ */
+export function spokenParts(items, locale) {
+    return once(listFormats, `${locale} spoken`, () => new Intl.ListFormat(locale, { type: "conjunction", style: "narrow" })).format(items);
+}
+/** Upper-cases the first grapheme for `locale` ("élan" → "Élan"); the rest stays as it is. */
+export function capitalize(text, locale) {
+    const first = firstGrapheme(text, locale);
+    return `${first.toLocaleUpperCase(locale)}${text.slice(first.length)}`;
+}
+/**
+ * An identifier's words, lower-cased for `locale`: camelCase, kebab-case, snake_case and dotted ids
+ * split ("repoName", "repo-name", "repo_name" → "repo name"; "parseHTMLFile" → "parse html file").
+ */
+export function idWords(id, locale) {
+    return id
+        .replaceAll(/([\p{Ll}\p{N}])(\p{Lu})/gu, "$1 $2")
+        .replaceAll(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1 $2")
+        .replaceAll(/[\s_.-]+/gu, " ")
+        .trim()
+        .toLocaleLowerCase(locale);
+}
+/**
+ * An identifier as words in sentence case, for a label it doesn't have: "spendByDay" → "Spend by
+ * day", "team_invite" → "Team invite". The id itself when it has no words.
+ */
+export function humanizeId(id, locale) {
+    const words = idWords(id, locale);
+    return words === "" ? id : capitalize(words, locale);
+}
+/** A word for initials: it starts with a letter or digit, and apostrophes stay inside ("O’Brien"). */
+const INITIAL_WORD = /[\p{L}\p{N}][\p{L}\p{M}\p{N}'’]*/gu;
+/**
+ * Up to `max` initials of a name, upper-cased for `locale`: the first grapheme of its first word and
+ * of its last ones ("Ava Chen" and "Ava Maria Chen" → "AC", "kai-rivera" → "KR", "Milo" → "M",
+ * "émile zola" → "ÉZ"). Spaces and punctuation separate words. Empty when the name has none.
+ */
+export function initialsOf(name, locale, max = 2) {
+    const words = name.match(INITIAL_WORD) ?? [];
+    if (max <= 0 || words.length === 0)
+        return "";
+    const picked = words.length <= max ? words : [words[0] ?? "", ...words.slice(words.length - max + 1)];
+    return picked
+        .map((word) => firstGrapheme(word, locale))
+        .join("")
+        .toLocaleUpperCase(locale);
+}
+/** A file name's extension, lower case ("tsx"), or undefined for none (`Makefile`, `.env`, `notes.`). */
+export function extensionOf(name) {
+    const dot = name.lastIndexOf(".");
+    return dot <= 0 || dot === name.length - 1 ? undefined : name.slice(dot + 1).toLowerCase();
+}

package/dist/lib/theme-scope.d.ts

@@ -0,0 +1,18 @@
+import { type ComponentProps } from "react";
+import type { ResolvedTheme } from "./theme.js";
+/** Where the kit's popups mount, for a Base UI `Portal`'s `container`. */
+export declare function usePortalContainer(): HTMLElement | null | undefined;
+export interface ThemeScopeProps extends Omit<ComponentProps<"div">, "children"> {
+    /** The theme everything inside takes, popups included. */
+    readonly theme: ResolvedTheme;
+    readonly children?: ComponentProps<"div">["children"];
+}
+/**
+ * A part of the page in one theme, whatever the page's: its `data-theme` reaches what it renders, and
+ * the popovers, menus, selects, tooltips, dialogs, sheets and toasts opened inside it mount in a host
+ * inside the scope, so they take its theme too. Two scopes side by side show the same thing in both
+ * themes. The host is the scope's last child, after its content. Popups position `fixed`, so keep a
+ * scope out from under an element with `transform`, `filter` or `contain` (they'd re-anchor or clip
+ * them). It makes no stacking context: the layers (`--z-*`) stack as they do anywhere else.
+ */
+export declare function ThemeScope({ theme, children, ...props }: ThemeScopeProps): import("react").JSX.Element;

package/dist/lib/theme-scope.js

@@ -0,0 +1,24 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, use, useState } from "react";
+/**
+ * The host popups mount in: inside a `ThemeScope`, its host (`null` until it's in the document, which
+ * makes Base UI wait for it); outside one, `undefined`, which Base UI reads as the document's body.
+ */
+const PortalContainerContext = createContext(undefined);
+/** Where the kit's popups mount, for a Base UI `Portal`'s `container`. */
+export function usePortalContainer() {
+    return use(PortalContainerContext);
+}
+/**
+ * A part of the page in one theme, whatever the page's: its `data-theme` reaches what it renders, and
+ * the popovers, menus, selects, tooltips, dialogs, sheets and toasts opened inside it mount in a host
+ * inside the scope, so they take its theme too. Two scopes side by side show the same thing in both
+ * themes. The host is the scope's last child, after its content. Popups position `fixed`, so keep a
+ * scope out from under an element with `transform`, `filter` or `contain` (they'd re-anchor or clip
+ * them). It makes no stacking context: the layers (`--z-*`) stack as they do anywhere else.
+ */
+export function ThemeScope({ theme, children, ...props }) {
+    const [host, setHost] = useState(null);
+    return (_jsxs("div", { "data-slot": "theme-scope", "data-theme": theme, ...props, children: [_jsx(PortalContainerContext, { value: host, children: children }), _jsx("div", { "data-slot": "theme-scope-portal", ref: setHost })] }));
+}

package/dist/lib/theme.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+export { useResolvedTheme } from "./use-resolved-theme.js";
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+/**
+ * The Web Storage key the reader's choice is kept under, unless the host names its own (`storageKey`):
+ * the kit's own, so it can't meet a key of the host's.
+ */
+export declare const THEME_STORAGE_KEY = "ui-theme";
+interface ThemeContextValue {
+    preference: ThemePreference;
+    resolved: ResolvedTheme;
+    setPreference: (next: ThemePreference) => void;
+}
+export interface ThemeProviderProps {
+    children: ReactNode;
+    defaultPreference?: ThemePreference;
+    /** The Web Storage key the choice is kept under, as given; `THEME_STORAGE_KEY` when left out. */
+    storageKey?: string;
+    /** Element receiving `data-theme`; defaults to <html>. */
+    target?: () => HTMLElement;
+    /**
+     * Also set `light` / `dark` as a class on the target, for libraries keyed on `.dark` (Fumadocs on
+     * the site). Pass the same flag to `themeInitScript`.
+     */
+    themeClass?: boolean;
+}
+/**
+ * Resolves light/dark/system and writes `data-theme` + `color-scheme` on <html>. Pair with
+ * `themeInitScript` in the document head to avoid a flash before hydration.
+ */
+export declare function ThemeProvider({ children, defaultPreference, storageKey, target, themeClass, }: ThemeProviderProps): import("react").JSX.Element;
+export declare function useTheme(): ThemeContextValue;
+/**
+ * Inline in <head> before styles load: applies the stored theme before first paint. `themeClass`
+ * matches the provider's option.
+ */
+export declare const themeInitScript: (storageKey?: string, { themeClass }?: {
+    themeClass?: boolean;
+}) => string;

package/dist/lib/theme.js

@@ -0,0 +1,96 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useEffect, useMemo, useState, useSyncExternalStore, } from "react";
+export { useResolvedTheme } from "./use-resolved-theme.js";
+/**
+ * The Web Storage key the reader's choice is kept under, unless the host names its own (`storageKey`):
+ * the kit's own, so it can't meet a key of the host's.
+ */
+export const THEME_STORAGE_KEY = "ui-theme";
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+function subscribeSystem(onChange) {
+    const mql = window.matchMedia(DARK_QUERY);
+    mql.addEventListener("change", onChange);
+    return () => mql.removeEventListener("change", onChange);
+}
+const getSystem = () => (window.matchMedia(DARK_QUERY).matches ? "dark" : "light");
+const getServerSystem = () => "light";
+/** The OS color scheme, live. */
+function useSystemTheme() {
+    return useSyncExternalStore(subscribeSystem, getSystem, getServerSystem);
+}
+function isPreference(value) {
+    return value === "light" || value === "dark" || value === "system";
+}
+function readStored(storageKey, fallback) {
+    try {
+        const raw = window.localStorage.getItem(storageKey);
+        return isPreference(raw) ? raw : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+const ThemeContext = createContext(null);
+/**
+ * Resolves light/dark/system and writes `data-theme` + `color-scheme` on <html>. Pair with
+ * `themeInitScript` in the document head to avoid a flash before hydration.
+ */
+export function ThemeProvider({ children, defaultPreference = "system", storageKey = THEME_STORAGE_KEY, target = () => document.documentElement, themeClass = false, }) {
+    const [preference, setPreferenceState] = useState(() => typeof window === "undefined" ? defaultPreference : readStored(storageKey, defaultPreference));
+    const system = useSystemTheme();
+    const resolved = preference === "system" ? system : preference;
+    useEffect(() => {
+        const el = target();
+        // Already painted in this theme (by `themeInitScript`, or an earlier run): touching the root
+        // would restyle the whole document for nothing.
+        const applied = el.getAttribute("data-theme") === resolved && (!themeClass || el.classList.contains(resolved));
+        if (applied)
+            return undefined;
+        // Suppress transitions during the swap so every surface flips in the same frame.
+        el.setAttribute("data-theme-switching", "");
+        el.setAttribute("data-theme", resolved);
+        el.style.colorScheme = resolved;
+        if (themeClass) {
+            el.classList.remove(resolved === "dark" ? "light" : "dark");
+            el.classList.add(resolved);
+        }
+        let inner = 0;
+        const outer = requestAnimationFrame(() => {
+            inner = requestAnimationFrame(() => el.removeAttribute("data-theme-switching"));
+        });
+        // A run cut short (Strict Mode's second run, a theme changing again within two frames) clears the flag too:
+        // the next run finds the theme already applied and sets nothing, so a flag left on would keep every
+        // transition off for good.
+        return () => {
+            cancelAnimationFrame(outer);
+            cancelAnimationFrame(inner);
+            el.removeAttribute("data-theme-switching");
+        };
+    }, [resolved, target, themeClass]);
+    const setPreference = useCallback((next) => {
+        setPreferenceState(next);
+        try {
+            window.localStorage.setItem(storageKey, next);
+        }
+        catch {
+            // Storage can be unavailable (private mode, sandboxed iframes); the choice still applies.
+        }
+    }, [storageKey]);
+    const value = useMemo(() => ({ preference, resolved, setPreference }), [preference, resolved, setPreference]);
+    return _jsx(ThemeContext, { value: value, children: children });
+}
+export function useTheme() {
+    const ctx = use(ThemeContext);
+    if (!ctx)
+        throw new Error("useTheme must be used inside <ThemeProvider>");
+    return ctx;
+}
+/**
+ * Inline in <head> before styles load: applies the stored theme before first paint. `themeClass`
+ * matches the provider's option.
+ */
+export const themeInitScript = (storageKey = THEME_STORAGE_KEY, { themeClass = false } = {}) => {
+    const classes = themeClass ? `e.classList.add(d?"dark":"light");` : "";
+    return `(()=>{try{var p=localStorage.getItem(${JSON.stringify(storageKey)});var d=p==="dark"||((p===null||p==="system")&&matchMedia("${DARK_QUERY}").matches);var e=document.documentElement;e.dataset.theme=d?"dark":"light";e.style.colorScheme=d?"dark":"light";${classes}}catch(_){}})()`;
+};

package/dist/lib/tree-keys.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The WAI-ARIA tree's keyboard, once for every tree: the run graph, the files pane and the browser's
+ * elements panel. ↑/↓ move, → opens a row or enters it, ← closes it or goes to its parent, Home and
+ * End go to the ends, Enter and Space activate, `*` opens every sibling, and typing a name jumps to
+ * it. The trees differ only in how they show focus (a roving tab stop, or `aria-activedescendant` on
+ * a windowed list) and in what activating a row does, so this hands each tree a move to apply.
+ */
+import { type KeyboardEvent } from "react";
+/**
+ * One row the tree shows, as the keyboard sees it. Rows are listed depth-first, and a collapsed row's
+ * descendants are left out.
+ */
+export interface TreeKeyRow {
+    readonly id: string;
+    /** The parent row's id; undefined at the top level. */
+    readonly parentId: string | undefined;
+    /** It has children, loaded or not. */
+    readonly expandable: boolean;
+    readonly expanded: boolean;
+}
+/** What a key does to the tree: the tree applies it. */
+export type TreeMove = {
+    readonly type: "focus";
+    readonly id: string;
+} | {
+    readonly type: "toggle";
+    readonly id: string;
+    readonly expanded: boolean;
+} | {
+    readonly type: "expand-siblings";
+    readonly ids: readonly string[];
+}
+/** Enter or Space: the row's own action (select a run, open a file, choose an element). */
+ | {
+    readonly type: "activate";
+    readonly id: string;
+} | {
+    readonly type: "none";
+};
+/**
+ * The move for a navigation key on the focused row. `key` is logical (`logicalArrow`): ArrowRight
+ * points to the end of the line. With nothing focused, ↓ and Home start at the top, ↑ and End at the
+ * bottom.
+ */
+export declare function treeKeyMove(rows: readonly TreeKeyRow[], focusedId: string | undefined, key: string): TreeMove;
+/**
+ * Type-ahead: the next row whose name starts with what was typed, after the focused one and wrapping
+ * around. Names compare as the reader's language compares letters, case and accents aside where it
+ * treats them as the same letter ("e" finds "Élan"; in Swedish "a" doesn't find "Äpple"), a
+ * character at a time ("👍🏽" is one). The same character typed again moves on to the next row it
+ * starts; a longer prefix stays on the focused row while that still matches.
+ */
+export declare function treeTypeAhead<Row extends TreeKeyRow>(rows: readonly Row[], focusedId: string | undefined, typed: string, labelOf: (row: Row) => string, locale: string): TreeMove;
+export interface TreeKeysOptions<Row extends TreeKeyRow> {
+    /** The rows the tree shows, in order. */
+    readonly rows: readonly Row[];
+    /** The row with the keyboard focus (or the active descendant); undefined before there is one. */
+    readonly focusedId: string | undefined;
+    /** The name type-ahead matches: what the row shows. */
+    readonly labelOf: (row: Row) => string;
+    /** Applies a move; the key's default action is already prevented. */
+    readonly onMove: (move: Exclude<TreeMove, {
+        readonly type: "none";
+    }>) => void;
+}
+/**
+ * The tree's key handler: put it on the focused element's `onKeyDown` (each row, or the tree when it
+ * uses `aria-activedescendant`). Arrows follow the reading direction (`useInlineSign()`), type-ahead
+ * the locale (`useUiLocale()`). Keys with ⌘, Ctrl or Alt, and keys an input method is composing, pass
+ * through.
+ */
+export declare function useTreeKeys<Row extends TreeKeyRow>({ rows, focusedId, labelOf, onMove, }: TreeKeysOptions<Row>): (event: KeyboardEvent) => void;

package/dist/lib/tree-keys.js

@@ -0,0 +1,126 @@
+"use client";
+/**
+ * The WAI-ARIA tree's keyboard, once for every tree: the run graph, the files pane and the browser's
+ * elements panel. ↑/↓ move, → opens a row or enters it, ← closes it or goes to its parent, Home and
+ * End go to the ends, Enter and Space activate, `*` opens every sibling, and typing a name jumps to
+ * it. The trees differ only in how they show focus (a roving tab stop, or `aria-activedescendant` on
+ * a windowed list) and in what activating a row does, so this hands each tree a move to apply.
+ */
+import { useRef } from "react";
+import { useUiLocale } from "../i18n/provider.js";
+import { logicalArrow, useInlineSign } from "./direction.js";
+import { isComposing } from "./keys.js";
+import { collatorFor, graphemePrefix, graphemesOf } from "./text.js";
+const NONE = { type: "none" };
+/**
+ * The move for a navigation key on the focused row. `key` is logical (`logicalArrow`): ArrowRight
+ * points to the end of the line. With nothing focused, ↓ and Home start at the top, ↑ and End at the
+ * bottom.
+ */
+export function treeKeyMove(rows, focusedId, key) {
+    const index = rows.findIndex((r) => r.id === focusedId);
+    const to = (i) => {
+        const target = rows[i];
+        return target === undefined || target.id === focusedId ? NONE : { type: "focus", id: target.id };
+    };
+    const row = rows[index];
+    if (row === undefined) {
+        if (key === "ArrowDown" || key === "Home")
+            return to(0);
+        if (key === "ArrowUp" || key === "End")
+            return to(rows.length - 1);
+        return NONE;
+    }
+    switch (key) {
+        case "ArrowDown":
+            return to(index + 1);
+        case "ArrowUp":
+            return to(index - 1);
+        case "Home":
+            return to(0);
+        case "End":
+            return to(rows.length - 1);
+        case "ArrowRight":
+            if (!row.expandable)
+                return NONE;
+            if (!row.expanded)
+                return { type: "toggle", id: row.id, expanded: true };
+            // Open, with its children shown (they may still be loading).
+            return rows[index + 1]?.parentId === row.id ? to(index + 1) : NONE;
+        case "ArrowLeft":
+            if (row.expandable && row.expanded)
+                return { type: "toggle", id: row.id, expanded: false };
+            return to(rows.findIndex((r) => r.id === row.parentId));
+        case "Enter":
+        case " ":
+            return { type: "activate", id: row.id };
+        case "*": {
+            const ids = rows
+                .filter((r) => r.parentId === row.parentId && r.expandable && !r.expanded)
+                .map((r) => r.id);
+            return ids.length === 0 ? NONE : { type: "expand-siblings", ids };
+        }
+        default:
+            return NONE;
+    }
+}
+/**
+ * Type-ahead: the next row whose name starts with what was typed, after the focused one and wrapping
+ * around. Names compare as the reader's language compares letters, case and accents aside where it
+ * treats them as the same letter ("e" finds "Élan"; in Swedish "a" doesn't find "Äpple"), a
+ * character at a time ("👍🏽" is one). The same character typed again moves on to the next row it
+ * starts; a longer prefix stays on the focused row while that still matches.
+ */
+export function treeTypeAhead(rows, focusedId, typed, labelOf, locale) {
+    const characters = graphemesOf(typed, locale);
+    const first = characters[0];
+    if (first === undefined || rows.length === 0)
+        return NONE;
+    const repeated = characters.every((c) => c === first);
+    const needle = repeated ? first : typed;
+    const length = repeated ? 1 : characters.length;
+    const collator = collatorFor(locale, { usage: "search", sensitivity: "base" });
+    const index = rows.findIndex((r) => r.id === focusedId);
+    const start = index === -1 ? 0 : index + (repeated ? 1 : 0);
+    for (let step = 0; step < rows.length; step++) {
+        const row = rows[(start + step) % rows.length];
+        if (row !== undefined && collator.compare(graphemePrefix(labelOf(row), length, locale), needle) === 0) {
+            return row.id === focusedId ? NONE : { type: "focus", id: row.id };
+        }
+    }
+    return NONE;
+}
+/** How long typed characters add up to one search: the kit's menus wait as long. */
+const TYPE_AHEAD_MS = 500;
+/**
+ * The tree's key handler: put it on the focused element's `onKeyDown` (each row, or the tree when it
+ * uses `aria-activedescendant`). Arrows follow the reading direction (`useInlineSign()`), type-ahead
+ * the locale (`useUiLocale()`). Keys with ⌘, Ctrl or Alt, and keys an input method is composing, pass
+ * through.
+ */
+export function useTreeKeys({ rows, focusedId, labelOf, onMove, }) {
+    const inline = useInlineSign();
+    const locale = useUiLocale();
+    const typed = useRef({ text: "", at: 0 });
+    return (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey || isComposing(event))
+            return;
+        const now = performance.now();
+        const buffer = now - typed.current.at < TYPE_AHEAD_MS ? typed.current.text : "";
+        // A character searches; a space only once a search has begun (names have spaces), `*` never.
+        const searching = graphemesOf(event.key).length === 1 && event.key !== "*" && (event.key !== " " || buffer !== "");
+        let move;
+        if (searching) {
+            typed.current = { text: buffer + event.key, at: now };
+            move = treeTypeAhead(rows, focusedId, typed.current.text, labelOf, locale);
+        }
+        else {
+            typed.current = { text: "", at: 0 };
+            move = treeKeyMove(rows, focusedId, logicalArrow(event.key, inline));
+        }
+        if (move.type === "none")
+            return;
+        event.preventDefault();
+        onMove(move);
+    };
+}

package/dist/lib/url.d.ts

@@ -0,0 +1,17 @@
+/** A URL's exact host, port and `www.` kept ("www.example.com:8443"); undefined when the text isn't a URL. */
+export declare function urlHost(url: string): string | undefined;
+/**
+ * The exact host a page came from (`www.` kept), for a notice about what a site may do; text that
+ * isn't a URL comes back as it was.
+ */
+export declare function exactHostOf(url: string): string;
+/**
+ * The site a link points at, as people say it: its host (a port stays) without a leading `www.`.
+ * Text that isn't a URL comes back as it was.
+ */
+export declare function hostOf(url: string): string;
+/**
+ * A link a remote party chose (a Hub listing's homepage, a search result) when it is a web address:
+ * http or https, else undefined, so a `file:`, `data:` or custom-scheme link is never rendered.
+ */
+export declare function webUrl(text: string | undefined): string | undefined;

package/dist/lib/url.js

@@ -0,0 +1,38 @@
+/** A URL's exact host, port and `www.` kept ("www.example.com:8443"); undefined when the text isn't a URL. */
+export function urlHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The exact host a page came from (`www.` kept), for a notice about what a site may do; text that
+ * isn't a URL comes back as it was.
+ */
+export function exactHostOf(url) {
+    return urlHost(url) ?? url;
+}
+/**
+ * The site a link points at, as people say it: its host (a port stays) without a leading `www.`.
+ * Text that isn't a URL comes back as it was.
+ */
+export function hostOf(url) {
+    return urlHost(url)?.replace(/^www\./u, "") ?? url;
+}
+/**
+ * A link a remote party chose (a Hub listing's homepage, a search result) when it is a web address:
+ * http or https, else undefined, so a `file:`, `data:` or custom-scheme link is never rendered.
+ */
+export function webUrl(text) {
+    if (text === undefined)
+        return undefined;
+    try {
+        const url = new URL(text);
+        return url.protocol === "https:" || url.protocol === "http:" ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/use-copy-to-clipboard.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+/** Writes text to the system clipboard. */
+export type ClipboardWrite = (text: string) => Promise<void>;
+/**
+ * The host's clipboard for every copy control below it (the desktop shell's writes without the
+ * browser's permission prompt); without one, the browser's.
+ */
+export declare function ClipboardProvider({ write, children, }: {
+    readonly write: ClipboardWrite;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** Clipboard write with a transient "copied" flag (resets after `resetMs`). */
+export declare function useCopyToClipboard(resetMs?: number): readonly [boolean, (text: string) => void];

package/dist/lib/use-copy-to-clipboard.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useEffect, useRef, useState } from "react";
+const browserWrite = (text) => navigator.clipboard.writeText(text);
+const ClipboardContext = createContext(browserWrite);
+/**
+ * The host's clipboard for every copy control below it (the desktop shell's writes without the
+ * browser's permission prompt); without one, the browser's.
+ */
+export function ClipboardProvider({ write, children, }) {
+    return _jsx(ClipboardContext, { value: write, children: children });
+}
+/** The clipboard write the host provides. */
+function useClipboardWrite() {
+    return use(ClipboardContext);
+}
+/** Clipboard write with a transient "copied" flag (resets after `resetMs`). */
+export function useCopyToClipboard(resetMs = 1600) {
+    const write = useClipboardWrite();
+    const [copied, setCopied] = useState(false);
+    const timer = useRef(undefined);
+    useEffect(() => () => clearTimeout(timer.current), []);
+    const copy = useCallback((text) => {
+        if (typeof navigator === "undefined")
+            return;
+        const run = async () => {
+            try {
+                await write(text);
+                setCopied(true);
+                clearTimeout(timer.current);
+                timer.current = setTimeout(() => setCopied(false), resetMs);
+            }
+            catch {
+                setCopied(false);
+            }
+        };
+        void run();
+    }, [resetMs, write]);
+    return [copied, copy];
+}

package/dist/lib/use-delayed-loading.d.ts

@@ -0,0 +1,11 @@
+export interface DelayedLoadingOptions {
+    /** Wait this long before showing (ms). */
+    delay?: number;
+    /** Once shown, stay visible at least this long (ms). */
+    minVisible?: number;
+}
+/**
+ * Turns a raw `loading` flag into a flicker-free one: fast operations never flash a loader, and a
+ * loader that does appear stays long enough to read as intentional (Vercel's 150–300 / 300–500 ms rule).
+ */
+export declare function useDelayedLoading(loading: boolean, { delay, minVisible }?: DelayedLoadingOptions): boolean;