@astralarium/repo-ui 0.1.0 → 0.2.0

package/README.md

@@ -5,3 +5,58 @@ Headless React UI following Base UI patterns.
 App setup:
 
 - `themeScript(cookie)` in `<head>` to apply theme pre-paint.
+
+```tsx
+const [title, setTitle] = useDebounce(draft.title, (title) => save({ title }));
+
+// debounced search param (./router)
+const [query, setQuery] = useSearchParam("q");
+
+// sticky headers: level n sits at `top: var(--sticky-h<n>)`
+<StickyHeightProvider>{children}</StickyHeightProvider>;
+<h2
+  ref={useStickyHeight(1)}
+  style={{ position: "sticky", top: "var(--sticky-h1)" }}
+/>;
+```
+
+Parts carry `data-slot` and state attributes; the app supplies styling.
+Responsive tables: below its breakpoint, a column collapses into the lead cell;
+the app's CSS hides the inactive copy.
+
+```tsx
+const columns = [
+  { key: "name", label: "Name", render: (row: Row) => row.name },
+  {
+    key: "rank",
+    label: "Rank",
+    breakpoint: "md",
+    render: (row: Row) => row.rank,
+  },
+] as const;
+
+<table>
+  <ResponsiveTH columns={columns} />
+  <tbody>
+    {rows.map((row, index) => (
+      <ResponsiveTR key={row.id} item={row} index={index} columns={columns} />
+    ))}
+  </tbody>
+</table>;
+```
+
+```css
+[data-slot="responsive-cell"][data-breakpoint="md"],
+[data-slot="responsive-header"][data-breakpoint="md"] {
+  display: none;
+}
+@media (width >= 48rem) {
+  [data-slot="responsive-cell"][data-breakpoint="md"],
+  [data-slot="responsive-header"][data-breakpoint="md"] {
+    display: table-cell;
+  }
+  [data-slot="responsive-detail"][data-breakpoint="md"] {
+    display: none;
+  }
+}
+```

package/dist/index.d.ts

@@ -1,16 +1,23 @@
 /** Headless React building blocks: theme, tree, page tree, timeline, sorted
- *  lookups, status, error boundary, storage and small hooks. */
+ *  lookups, status, error boundary, storage, sticky headers, responsive
+ *  tables, external scripts and small hooks. */
 export * from "./error-boundary.tsx";
+export * from "./lazy-google-analytics.tsx";
 export * from "./page-tree.ts";
+export * from "./responsive-table.tsx";
 export * from "./sorted.ts";
 export * from "./status.tsx";
+export * from "./sticky-height.tsx";
 export * from "./storage.ts";
 export * from "./theme/index.ts";
 export * from "./timeline.ts";
 export * from "./tree/index.ts";
 export * from "./use-copy-feedback.ts";
+export * from "./use-debounce.ts";
+export * from "./use-external-script.ts";
 export * from "./use-frame.ts";
 export * from "./use-hover-focus.ts";
 export * from "./use-media-query.ts";
 export * from "./use-pausable-hover.ts";
 export * from "./use-pulse-style.ts";
+export { useStickyHeight } from "./use-sticky-height.ts";

package/dist/index.js

@@ -1,16 +1,23 @@
 /** Headless React building blocks: theme, tree, page tree, timeline, sorted
- *  lookups, status, error boundary, storage and small hooks. */
+ *  lookups, status, error boundary, storage, sticky headers, responsive
+ *  tables, external scripts and small hooks. */
 export * from "./error-boundary.js";
+export * from "./lazy-google-analytics.js";
 export * from "./page-tree.js";
+export * from "./responsive-table.js";
 export * from "./sorted.js";
 export * from "./status.js";
+export * from "./sticky-height.js";
 export * from "./storage.js";
 export * from "./theme/index.js";
 export * from "./timeline.js";
 export * from "./tree/index.js";
 export * from "./use-copy-feedback.js";
+export * from "./use-debounce.js";
+export * from "./use-external-script.js";
 export * from "./use-frame.js";
 export * from "./use-hover-focus.js";
 export * from "./use-media-query.js";
 export * from "./use-pausable-hover.js";
 export * from "./use-pulse-style.js";
+export { useStickyHeight } from "./use-sticky-height.js";

package/dist/l10n/repo-ui/en.json

@@ -1,4 +1,8 @@
 {
+  "@astralarium/repo-ui/router/tab-bar.messages#barName": {
+    "defaultMessage": "Tabs",
+    "description": "Accessible name of a tab bar switching between page sections. Shows: screen readers."
+  },
   "@astralarium/repo-ui/slider/slider.messages#rangeEnd": {
     "defaultMessage": "{value}, range end",
     "description": "Spoken value of a range slider's last thumb. Shows: screen readers, sliders with several thumbs. Arguments: value (string) the thumb's formatted value."

package/dist/lazy-google-analytics.d.ts

@@ -0,0 +1,4 @@
+/** Loads Google Analytics property `gaId` once the browser idles. */
+export declare function LazyGoogleAnalytics({ gaId }: {
+    gaId: string;
+}): null;

package/dist/lazy-google-analytics.js

@@ -0,0 +1,34 @@
+"use client";
+
+import { c as _c } from "react/compiler-runtime";
+import { useExternalScript } from "./use-external-script.js";
+/** Queues gtag's start and `gaId`'s config ahead of its script. */
+function initGtag(gaId) {
+  const dataLayer = window.dataLayer ??= [];
+  function gtag(..._args) {
+    // eslint-disable-next-line prefer-rest-params -- gtag.js reads queued `arguments` objects; arrays go unread
+    dataLayer.push(arguments);
+  }
+  gtag("js", new Date());
+  gtag("config", gaId);
+}
+/** Loads Google Analytics property `gaId` once the browser idles. */
+export function LazyGoogleAnalytics(t0) {
+  const $ = _c(2);
+  const {
+    gaId
+  } = t0;
+  let t1;
+  if ($[0] !== gaId) {
+    t1 = {
+      idle: true,
+      init: () => initGtag(gaId)
+    };
+    $[0] = gaId;
+    $[1] = t1;
+  } else {
+    t1 = $[1];
+  }
+  useExternalScript(`https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(gaId)}`, t1);
+  return null;
+}

package/dist/responsive-table.d.ts

@@ -0,0 +1,54 @@
+import type { ComponentProps, ReactNode } from "react";
+/** Tailwind's breakpoints, smallest first. */
+declare const TAILWIND_BREAKPOINTS: readonly ["sm", "md", "lg", "xl", "2xl"];
+/** A Tailwind breakpoint. */
+export type TailwindBreakpoint = (typeof TAILWIND_BREAKPOINTS)[number];
+/** A column's header: its label and where it collapses. */
+export interface ResponsiveColumnLabel<B extends string = TailwindBreakpoint> {
+    key: string;
+    /** Header text; also the detail's `<dt>`, visually hidden. */
+    label?: ReactNode;
+    /** From this breakpoint up, the column shows as a cell; below it, as a
+     *  detail in the lead cell. Absent, or on the lead column: always a
+     *  cell. */
+    breakpoint?: B;
+    /** Class of the column's `<th>` and `<td>`. */
+    className?: string;
+    /** Class of the column's `<dd>`. */
+    detailClassName?: string;
+    colSpan?: number;
+}
+/** A column: its header and how it renders a row's item. */
+export interface ResponsiveColumn<T, B extends string = TailwindBreakpoint> extends ResponsiveColumnLabel<B> {
+    /** The cell's content for the row at `index`. */
+    render: (item: T, index: number) => ReactNode;
+    /** The detail's content; `render`'s by default. */
+    renderDetail?: (item: T, index: number) => ReactNode;
+}
+/** `ResponsiveTH` props: a `<thead>`'s, and the columns it heads. */
+export interface ResponsiveTHProps<B extends string = TailwindBreakpoint> extends Omit<ComponentProps<"thead">, "children"> {
+    columns: readonly ResponsiveColumnLabel<B>[];
+}
+/** The table head: one `<th>` per column. */
+export declare function ResponsiveTH<B extends string = TailwindBreakpoint>({ columns, ...props }: ResponsiveTHProps<B>): import("react/jsx-runtime").JSX.Element;
+/** `ResponsiveTR` props: a `<tr>`'s, the item it renders, and the app's
+ *  breakpoints, required for breakpoints beyond Tailwind's. */
+export type ResponsiveTRProps<T, B extends string = TailwindBreakpoint> = ResponsiveTRBaseProps<T, B> & ([B] extends [TailwindBreakpoint] ? Partial<ResponsiveTRBreakpoints<B>> : ResponsiveTRBreakpoints<B>);
+/** `ResponsiveTR` props besides `breakpoints`. */
+interface ResponsiveTRBaseProps<T, B extends string = TailwindBreakpoint> extends Omit<ComponentProps<"tr">, "children"> {
+    item: T;
+    /** The row's index, passed to `render`. */
+    index: number;
+    columns: readonly ResponsiveColumn<T, B>[];
+    /** Renders the lead as the row's header, `<th scope="row">`. */
+    rowHeader?: boolean;
+}
+/** `ResponsiveTR`'s breakpoint order. */
+interface ResponsiveTRBreakpoints<B extends string> {
+    /** The app's breakpoints, smallest first; Tailwind's when omitted. */
+    breakpoints: readonly B[];
+}
+/** A body row: its item's cells, the collapsing columns repeated as
+ *  details in the lead cell. */
+export declare function ResponsiveTR<T, B extends string = TailwindBreakpoint>({ item, index, columns, breakpoints, rowHeader, ...props }: ResponsiveTRProps<T, B>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/responsive-table.js

@@ -0,0 +1,180 @@
+import { c as _c } from "react/compiler-runtime";
+/**
+ * Table rows whose columns collapse below a breakpoint into the lead
+ * cell's `<dl>`. Parts carry `data-slot`; `data-breakpoint` names where
+ * a part's layout changes, and the app's CSS shows or hides each part
+ * there:
+ * - `responsive-header` / `responsive-cell`: the column's `<th>` / `<td>`,
+ *   a cell from its breakpoint up. The lead column is always a cell.
+ * - `responsive-lead`: the row's first `<td>` (or `<th scope="row">`),
+ *   holding the details; the lowest breakpoint, where the first column
+ *   leaves it.
+ * - `responsive-details`: the lead's `<dl>`; the highest breakpoint, where
+ *   the last column leaves it.
+ * - `responsive-detail`: a column's `<dt>` + `<dd>` in the `<dl>`, until
+ *   its breakpoint.
+ */
+import { visuallyHidden } from "@base-ui/utils/visuallyHidden";
+/** Tailwind's breakpoints, smallest first. */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const TAILWIND_BREAKPOINTS = ["sm", "md", "lg", "xl", "2xl"];
+/** The table head: one `<th>` per column. */
+export function ResponsiveTH(t0) {
+  const $ = _c(10);
+  let columns;
+  let props;
+  if ($[0] !== t0) {
+    ({
+      columns,
+      ...props
+    } = t0);
+    $[0] = t0;
+    $[1] = columns;
+    $[2] = props;
+  } else {
+    columns = $[1];
+    props = $[2];
+  }
+  let t1;
+  if ($[3] !== columns) {
+    t1 = columns.map(_temp);
+    $[3] = columns;
+    $[4] = t1;
+  } else {
+    t1 = $[4];
+  }
+  let t2;
+  if ($[5] !== t1) {
+    t2 = /*#__PURE__*/_jsx("tr", {
+      children: t1
+    });
+    $[5] = t1;
+    $[6] = t2;
+  } else {
+    t2 = $[6];
+  }
+  let t3;
+  if ($[7] !== props || $[8] !== t2) {
+    t3 = /*#__PURE__*/_jsx("thead", {
+      "data-slot": "responsive-head",
+      ...props,
+      children: t2
+    });
+    $[7] = props;
+    $[8] = t2;
+    $[9] = t3;
+  } else {
+    t3 = $[9];
+  }
+  return t3;
+}
+/** The lowest and highest of `breakpoints` the columns name. */
+function _temp(column, index) {
+  return /*#__PURE__*/_jsx("th", {
+    scope: "col",
+    colSpan: column.colSpan,
+    className: column.className,
+    "data-slot": "responsive-header",
+    "data-breakpoint": index === 0 ? undefined : column.breakpoint,
+    children: column.label
+  }, column.key);
+}
+function breakpointRange(columns, breakpoints) {
+  const named = breakpoints.filter(breakpoint => columns.some(column => column.breakpoint === breakpoint));
+  return {
+    min: named[0],
+    max: named.at(-1)
+  };
+}
+/** A body row: its item's cells, the collapsing columns repeated as
+ *  details in the lead cell. */
+export function ResponsiveTR(t0) {
+  const $ = _c(14);
+  let columns;
+  let index;
+  let item;
+  let props;
+  let t1;
+  let t2;
+  if ($[0] !== t0) {
+    ({
+      item,
+      index,
+      columns,
+      breakpoints: t1,
+      rowHeader: t2,
+      ...props
+    } = t0);
+    $[0] = t0;
+    $[1] = columns;
+    $[2] = index;
+    $[3] = item;
+    $[4] = props;
+    $[5] = t1;
+    $[6] = t2;
+  } else {
+    columns = $[1];
+    index = $[2];
+    item = $[3];
+    props = $[4];
+    t1 = $[5];
+    t2 = $[6];
+  }
+  const breakpoints = t1 === undefined ? TAILWIND_BREAKPOINTS : t1;
+  const rowHeader = t2 === undefined ? false : t2;
+  let t3;
+  if ($[7] !== breakpoints || $[8] !== columns || $[9] !== index || $[10] !== item || $[11] !== props || $[12] !== rowHeader) {
+    const [lead, ...rest] = columns;
+    const collapsing = rest.filter(_temp2);
+    const {
+      min,
+      max
+    } = breakpointRange(collapsing, breakpoints);
+    const Lead = rowHeader ? "th" : "td";
+    t3 = /*#__PURE__*/_jsxs("tr", {
+      "data-slot": "responsive-row",
+      ...props,
+      children: [lead ? /*#__PURE__*/_jsxs(Lead, {
+        scope: rowHeader ? "row" : undefined,
+        colSpan: lead.colSpan,
+        className: lead.className,
+        "data-slot": "responsive-lead",
+        "data-breakpoint": min,
+        children: [lead.render(item, index), collapsing.length > 0 ? /*#__PURE__*/_jsx("dl", {
+          "data-slot": "responsive-details",
+          "data-breakpoint": max,
+          children: collapsing.map(column_0 => /*#__PURE__*/_jsxs("div", {
+            "data-slot": "responsive-detail",
+            "data-breakpoint": column_0.breakpoint,
+            children: [/*#__PURE__*/_jsx("dt", {
+              style: visuallyHidden,
+              children: column_0.label
+            }), /*#__PURE__*/_jsx("dd", {
+              className: column_0.detailClassName,
+              children: (column_0.renderDetail ?? column_0.render)(item, index)
+            })]
+          }, column_0.key))
+        }) : null]
+      }) : null, rest.map(column_1 => /*#__PURE__*/_jsx("td", {
+        colSpan: column_1.colSpan,
+        className: column_1.className,
+        "data-slot": "responsive-cell",
+        "data-breakpoint": column_1.breakpoint,
+        children: column_1.render(item, index)
+      }, column_1.key))]
+    });
+    $[7] = breakpoints;
+    $[8] = columns;
+    $[9] = index;
+    $[10] = item;
+    $[11] = props;
+    $[12] = rowHeader;
+    $[13] = t3;
+  } else {
+    t3 = $[13];
+  }
+  return t3;
+}
+function _temp2(column) {
+  return column.breakpoint !== undefined;
+}

package/dist/router/index.d.ts

@@ -0,0 +1,5 @@
+/** Router-bound UI: link tabs, debounced search params and dev routes. */
+export * from "./dev-route.ts";
+export * from "./tab-bar.tsx";
+export * from "./tabs.ts";
+export * from "./use-search-param.ts";

package/dist/router/index.js

@@ -0,0 +1,5 @@
+/** Router-bound UI: link tabs, debounced search params and dev routes. */
+export * from "./dev-route.js";
+export * from "./tab-bar.js";
+export * from "./tabs.js";
+export * from "./use-search-param.js";

package/dist/router/tab-bar.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentProps } from "react";
+import type { Tab } from "./tabs.ts";
+/** `TabBar` props: a `<nav>`'s, and its tabs. */
+export interface TabBarProps extends Omit<ComponentProps<"nav">, "children"> {
+    tabs: readonly Tab[];
+    /** Class of each tab. */
+    tabClassName?: string;
+}
+/** A tab bar: router `Link`s current on their exact path, search aside,
+ *  unless the link sets `activeOptions`; buttons current while `active`.
+ *  Named "Tabs" unless `aria-label` says otherwise. */
+export declare function TabBar({ tabs, tabClassName, ...props }: TabBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/router/tab-bar.js

@@ -0,0 +1,98 @@
+"use client";
+
+/**
+ * A `<nav>` of tabs. Each tab carries `data-slot="tab"`; the current tab
+ * carries `data-status="active"` and `aria-current`: `"page"` on a link,
+ * `"true"` on a button. Everything visual comes from the app.
+ */
+import { c as _c } from "react/compiler-runtime";
+import { useFormat } from "@astralarium/localizable";
+import { Link } from "@tanstack/react-router";
+import messages from "./tab-bar.messages.json" with { type: "json" };
+/** A link tab's default `activeOptions`: current on its exact path,
+ *  search aside. */
+import { jsx as _jsx } from "react/jsx-runtime";
+const TAB_ACTIVE_OPTIONS = {
+  exact: true,
+  includeSearch: false
+};
+/** A tab bar: router `Link`s current on their exact path, search aside,
+ *  unless the link sets `activeOptions`; buttons current while `active`.
+ *  Named "Tabs" unless `aria-label` says otherwise. */
+export function TabBar(t0) {
+  const $ = _c(15);
+  let props;
+  let tabClassName;
+  let tabs;
+  if ($[0] !== t0) {
+    ({
+      tabs,
+      tabClassName,
+      ...props
+    } = t0);
+    $[0] = t0;
+    $[1] = props;
+    $[2] = tabClassName;
+    $[3] = tabs;
+  } else {
+    props = $[1];
+    tabClassName = $[2];
+    tabs = $[3];
+  }
+  const format = useFormat();
+  let t1;
+  if ($[4] !== format) {
+    t1 = format(messages.barName);
+    $[4] = format;
+    $[5] = t1;
+  } else {
+    t1 = $[5];
+  }
+  let t2;
+  if ($[6] !== tabClassName || $[7] !== tabs) {
+    let t3;
+    if ($[9] !== tabClassName) {
+      t3 = tab => tab.link ? /*#__PURE__*/_jsx(Link, {
+        ...tab.link,
+        activeOptions: tab.link.activeOptions ?? TAB_ACTIVE_OPTIONS,
+        className: tabClassName,
+        "data-slot": "tab",
+        children: tab.label
+      }, tab.name) : /*#__PURE__*/_jsx("button", {
+        type: "button",
+        onClick: () => tab.onClick?.(tab),
+        className: tabClassName,
+        "aria-current": tab.active ? "true" : undefined,
+        "data-slot": "tab",
+        "data-status": tab.active ? "active" : undefined,
+        children: tab.label
+      }, tab.name);
+      $[9] = tabClassName;
+      $[10] = t3;
+    } else {
+      t3 = $[10];
+    }
+    t2 = tabs.map(t3);
+    $[6] = tabClassName;
+    $[7] = tabs;
+    $[8] = t2;
+  } else {
+    t2 = $[8];
+  }
+  let t3;
+  if ($[11] !== props || $[12] !== t1 || $[13] !== t2) {
+    t3 = /*#__PURE__*/_jsx("nav", {
+      "aria-label": t1,
+      "data-slot": "tab-bar",
+      ...props,
+      children: t2
+    });
+    $[11] = props;
+    $[12] = t1;
+    $[13] = t2;
+    $[14] = t3;
+  } else {
+    t3 = $[14];
+  }
+  return t3;
+}

package/dist/router/tab-bar.messages.d.json.ts

@@ -0,0 +1,7 @@
+// Generated by l10n-types.
+import type { Message } from "@astralarium/localizable";
+
+declare const messages: {
+  barName: Message<Record<never, never>>;
+};
+export = messages;

package/dist/router/tab-bar.messages.json

@@ -0,0 +1,6 @@
+{
+  "barName": {
+    "id": "@astralarium/repo-ui/router/tab-bar.messages#barName",
+    "defaultMessage": "Tabs"
+  }
+}

package/dist/router/tabs.d.ts

@@ -0,0 +1,21 @@
+import { type LinkOptions } from "@tanstack/react-router";
+import type { ReactNode } from "react";
+/** A tab: a router link, or a button. */
+export interface Tab {
+    /** Identifies the tab; `buildTabs` selects by it. */
+    name: string;
+    label: ReactNode;
+    /** Destination of a link tab; current on its exact path, search
+     *  aside, unless `activeOptions` says otherwise. */
+    link?: LinkOptions;
+    /** Press of a button tab. */
+    onClick?: (tab: Tab) => unknown;
+    /** The selected tab: current among button tabs. */
+    active?: boolean;
+}
+/** Binds fixed tabs to a selection: `tabsOf(tab, setTab, onChange)` marks
+ *  tab `tab` active and selects a pressed tab. */
+export declare function buildTabs(tabs: readonly Omit<Tab, "onClick" | "active">[]): (tab: string, setTab: (name: string) => unknown, onChange?: () => unknown) => Tab[];
+/** Selects a tab outside a `TabBar`, e.g. from a dropdown: navigates to a
+ *  link tab, presses a button tab. */
+export declare function useSelectTab(): (tab: Tab) => void;

package/dist/router/tabs.js

@@ -0,0 +1,37 @@
+import { c as _c } from "react/compiler-runtime";
+import { useNavigate } from "@tanstack/react-router";
+/** Binds fixed tabs to a selection: `tabsOf(tab, setTab, onChange)` marks
+ *  tab `tab` active and selects a pressed tab. */
+export function buildTabs(tabs) {
+  return function tabsOf(tab, setTab, onChange) {
+    return tabs.map(x => ({
+      ...x,
+      active: x.name === tab,
+      onClick: () => {
+        setTab(x.name);
+        onChange?.();
+      }
+    }));
+  };
+}
+/** Selects a tab outside a `TabBar`, e.g. from a dropdown: navigates to a
+ *  link tab, presses a button tab. */
+export function useSelectTab() {
+  const $ = _c(2);
+  const navigate = useNavigate();
+  let t0;
+  if ($[0] !== navigate) {
+    t0 = tab => {
+      if (tab.link) {
+        navigate(tab.link);
+      } else {
+        tab.onClick?.(tab);
+      }
+    };
+    $[0] = navigate;
+    $[1] = t0;
+  } else {
+    t0 = $[1];
+  }
+  return t0;
+}

package/dist/router/use-search-param.d.ts

@@ -0,0 +1,5 @@
+/** String-valued search param `name`, written back after `ms` idle
+ *  (`useDebounce`), replacing the history entry and keeping the hash;
+ *  empty text removes it. Other values read as JSON and write back as
+ *  strings. */
+export declare function useSearchParam(name: string, ms?: number): [string, (text: string) => void];

package/dist/router/use-search-param.js

@@ -0,0 +1,46 @@
+import { c as _c } from "react/compiler-runtime";
+import { useNavigate, useSearch } from "@tanstack/react-router";
+import { useDebounce } from "../use-debounce.js";
+/** A search param's value as text; empty when absent. */
+function searchText(value) {
+  if (value === undefined || value === null) return "";
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** String-valued search param `name`, written back after `ms` idle
+ *  (`useDebounce`), replacing the history entry and keeping the hash;
+ *  empty text removes it. Other values read as JSON and write back as
+ *  strings. */
+export function useSearchParam(name, ms) {
+  const $ = _c(5);
+  let t0;
+  if ($[0] !== name) {
+    t0 = {
+      strict: false,
+      select: search => searchText(search[name])
+    };
+    $[0] = name;
+    $[1] = t0;
+  } else {
+    t0 = $[1];
+  }
+  const value = useSearch(t0);
+  const navigate = useNavigate();
+  let t1;
+  if ($[2] !== name || $[3] !== navigate) {
+    t1 = text => navigate({
+      to: ".",
+      search: prev => ({
+        ...prev,
+        [name]: text || undefined
+      }),
+      hash: true,
+      replace: true
+    });
+    $[2] = name;
+    $[3] = navigate;
+    $[4] = t1;
+  } else {
+    t1 = $[4];
+  }
+  return useDebounce(value, t1, ms);
+}

package/dist/sticky-height.d.ts

@@ -0,0 +1,10 @@
+import { useRender } from "@base-ui/react/use-render";
+/** `StickyHeightProvider` props: a div's, or `render`'s element's. */
+export interface StickyHeightProviderProps extends useRender.ComponentProps<"div"> {
+    /** Sticky levels measured: 0…`levels - 1`. */
+    levels?: number;
+}
+/** Stacks sticky headers: sets `--sticky-h<n>` on its element, the summed
+ *  heights `useStickyHeight` reports for levels below n. A level-n header
+ *  sticks at `top: var(--sticky-h<n>)`. */
+export declare function StickyHeightProvider({ levels, render, style, ...props }: StickyHeightProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/sticky-height.js

@@ -0,0 +1,133 @@
+"use client";
+
+import { c as _c } from "react/compiler-runtime";
+import { useRender } from "@base-ui/react/use-render";
+// eslint-disable-next-line no-restricted-imports -- every `useStickyHeight` ref keys on `setHeight`; its identity holds in uncompiled builds too
+import { useCallback, useState } from "react";
+import { StickyHeightContext } from "./use-sticky-height.js";
+/** `--sticky-h<n>` for n in 1…`levels`: the summed `heights` of levels
+ *  below n. */
+import { jsx as _jsx } from "react/jsx-runtime";
+function stickyHeightStyle(heights, levels) {
+  let sum = 0;
+  return Object.fromEntries(Array.from({
+    length: levels
+  }, (_, level) => {
+    sum += heights[level] ?? 0;
+    return [`--sticky-h${level + 1}`, `${sum}px`];
+  }));
+}
+/** Stacks sticky headers: sets `--sticky-h<n>` on its element, the summed
+ *  heights `useStickyHeight` reports for levels below n. A level-n header
+ *  sticks at `top: var(--sticky-h<n>)`. */
+export function StickyHeightProvider(t0) {
+  const $ = _c(21);
+  let props;
+  let render;
+  let style;
+  let t1;
+  if ($[0] !== t0) {
+    ({
+      levels: t1,
+      render,
+      style,
+      ...props
+    } = t0);
+    $[0] = t0;
+    $[1] = props;
+    $[2] = render;
+    $[3] = style;
+    $[4] = t1;
+  } else {
+    props = $[1];
+    render = $[2];
+    style = $[3];
+    t1 = $[4];
+  }
+  const levels = t1 === undefined ? 10 : t1;
+  let t2;
+  if ($[5] === Symbol.for("react.memo_cache_sentinel")) {
+    t2 = [];
+    $[5] = t2;
+  } else {
+    t2 = $[5];
+  }
+  const [heights, setHeights] = useState(t2);
+  let t3;
+  if ($[6] === Symbol.for("react.memo_cache_sentinel")) {
+    t3 = (level, height) => setHeights(prev => {
+      if ((prev[level] ?? 0) === height) {
+        return prev;
+      }
+      const next = Array.from({
+        length: Math.max(prev.length, level + 1)
+      }, (_, i) => prev[i] ?? 0);
+      next[level] = height;
+      return next;
+    });
+    $[6] = t3;
+  } else {
+    t3 = $[6];
+  }
+  const setHeight = t3;
+  let t4;
+  if ($[7] !== heights || $[8] !== levels) {
+    t4 = stickyHeightStyle(heights, levels);
+    $[7] = heights;
+    $[8] = levels;
+    $[9] = t4;
+  } else {
+    t4 = $[9];
+  }
+  let t5;
+  if ($[10] !== style || $[11] !== t4) {
+    t5 = {
+      ...t4,
+      ...style
+    };
+    $[10] = style;
+    $[11] = t4;
+    $[12] = t5;
+  } else {
+    t5 = $[12];
+  }
+  let t6;
+  if ($[13] !== props || $[14] !== t5) {
+    t6 = {
+      "data-slot": "sticky-heights",
+      ...props,
+      style: t5
+    };
+    $[13] = props;
+    $[14] = t5;
+    $[15] = t6;
+  } else {
+    t6 = $[15];
+  }
+  let t7;
+  if ($[16] !== render || $[17] !== t6) {
+    t7 = {
+      defaultTagName: "div",
+      render,
+      props: t6
+    };
+    $[16] = render;
+    $[17] = t6;
+    $[18] = t7;
+  } else {
+    t7 = $[18];
+  }
+  const element = useRender(t7);
+  let t8;
+  if ($[19] !== element) {
+    t8 = /*#__PURE__*/_jsx(StickyHeightContext, {
+      value: setHeight,
+      children: element
+    });
+    $[19] = element;
+    $[20] = t8;
+  } else {
+    t8 = $[20];
+  }
+  return t8;
+}

package/dist/theme/theme.d.ts

@@ -19,7 +19,7 @@ export declare const ThemeStateContext: import("react").Context<ThemeState | nul
 /** Effective theme: the setting, or the OS scheme under `system`. */
 export declare function useTheme(): SystemTheme;
 /** The visitor's theme setting. */
-export declare function useThemeSetting(): "system" | "light" | "dark";
+export declare function useThemeSetting(): "dark" | "light" | "system";
 /** Applies and persists a new theme setting. */
 export declare function useSetTheme(): (setting: ThemeSetting) => void;
 /** Inline `<head>` script: classes `<html>` from the `cookie` preference

package/dist/use-debounce.d.ts

@@ -0,0 +1,3 @@
+/** Local copy of `value`; edits write through `setValue` after `ms` idle.
+ *  A new `value` replaces the copy unless an edit is pending. */
+export declare function useDebounce<T>(value: T, setValue: (value: T) => unknown, ms?: number): [T, (value: T) => void];

package/dist/use-debounce.js

@@ -0,0 +1,66 @@
+import { c as _c } from "react/compiler-runtime";
+import { useEffect, useEffectEvent, useState } from "react";
+/** Local copy of `value`; edits write through `setValue` after `ms` idle.
+ *  A new `value` replaces the copy unless an edit is pending. */
+export function useDebounce(value, setValue, t0) {
+  const $ = _c(12);
+  const ms = t0 === undefined ? 400 : t0;
+  const [state, setState] = useState(value);
+  const [invoked, setInvoked] = useState(value);
+  const [seen, setSeen] = useState(value);
+  if (value !== seen) {
+    setSeen(value);
+    setInvoked(value);
+    if (state === invoked) {
+      setState(value);
+    }
+  }
+  let t1;
+  if ($[0] !== invoked || $[1] !== setValue || $[2] !== state) {
+    t1 = () => {
+      if (state === invoked) {
+        return;
+      }
+      setInvoked(state);
+      setValue(state);
+    };
+    $[0] = invoked;
+    $[1] = setValue;
+    $[2] = state;
+    $[3] = t1;
+  } else {
+    t1 = $[3];
+  }
+  const write = useEffectEvent(t1);
+  let t2;
+  if ($[4] !== ms || $[5] !== write) {
+    t2 = () => {
+      const timer = setTimeout(write, ms);
+      return () => clearTimeout(timer);
+    };
+    $[4] = ms;
+    $[5] = write;
+    $[6] = t2;
+  } else {
+    t2 = $[6];
+  }
+  let t3;
+  if ($[7] !== ms || $[8] !== state) {
+    t3 = [ms, state];
+    $[7] = ms;
+    $[8] = state;
+    $[9] = t3;
+  } else {
+    t3 = $[9];
+  }
+  useEffect(t2, t3);
+  let t4;
+  if ($[10] !== state) {
+    t4 = [state, setState];
+    $[10] = state;
+    $[11] = t4;
+  } else {
+    t4 = $[11];
+  }
+  return t4;
+}

package/dist/use-external-script.d.ts

@@ -0,0 +1,10 @@
+/** When and how `useExternalScript` loads its script. */
+export interface ExternalScriptOptions {
+    /** Runs once, right before the script loads: globals it reads. */
+    init?: () => void;
+    /** Waits for the browser to idle (2 s where `requestIdleCallback` is
+     *  absent). */
+    idle?: boolean;
+}
+/** Loads the script at `src` once per page, after hydration. */
+export declare function useExternalScript(src: string, { init, idle }?: ExternalScriptOptions): void;

package/dist/use-external-script.js

@@ -0,0 +1,73 @@
+import { c as _c } from "react/compiler-runtime";
+import { useEffect, useEffectEvent } from "react";
+/** Script sources this page loads or has loaded. */
+const loaded = new Set();
+/** Loads the script at `src` once per page, after hydration. */
+export function useExternalScript(src, t0) {
+  const $ = _c(11);
+  let t1;
+  if ($[0] !== t0) {
+    t1 = t0 === undefined ? {} : t0;
+    $[0] = t0;
+    $[1] = t1;
+  } else {
+    t1 = $[1];
+  }
+  const {
+    init,
+    idle: t2
+  } = t1;
+  const idle = t2 === undefined ? false : t2;
+  let t3;
+  if ($[2] !== init) {
+    t3 = () => init?.();
+    $[2] = init;
+    $[3] = t3;
+  } else {
+    t3 = $[3];
+  }
+  const runInit = useEffectEvent(t3);
+  let t4;
+  if ($[4] !== idle || $[5] !== runInit || $[6] !== src) {
+    t4 = () => {
+      if (loaded.has(src)) {
+        return;
+      }
+      const load = () => {
+        if (loaded.has(src)) {
+          return;
+        }
+        loaded.add(src);
+        runInit();
+        const script = document.createElement("script");
+        script.src = src;
+        document.head.appendChild(script);
+      };
+      if (!idle) {
+        return load();
+      }
+      if ("requestIdleCallback" in window) {
+        const handle = window.requestIdleCallback(load);
+        return () => window.cancelIdleCallback(handle);
+      }
+      const timer = setTimeout(load, 2000);
+      return () => clearTimeout(timer);
+    };
+    $[4] = idle;
+    $[5] = runInit;
+    $[6] = src;
+    $[7] = t4;
+  } else {
+    t4 = $[7];
+  }
+  let t5;
+  if ($[8] !== idle || $[9] !== src) {
+    t5 = [src, idle];
+    $[8] = idle;
+    $[9] = src;
+    $[10] = t5;
+  } else {
+    t5 = $[10];
+  }
+  useEffect(t4, t5);
+}

package/dist/use-sticky-height.d.ts

@@ -0,0 +1,10 @@
+import { type RefCallback } from "react";
+/** Reports sticky level `level`'s height, in px. */
+export type SetStickyHeight = (level: number, height: number) => void;
+/** The enclosing `StickyHeightProvider`'s height report. */
+export declare const StickyHeightContext: import("react").Context<SetStickyHeight>;
+/** Ref reporting its element's border-box height as sticky level `level`,
+ *  to the enclosing `StickyHeightProvider`; zero once detached. One
+ *  header per level: each report replaces the level's height. Stable per
+ *  `level` and provider: React re-attaches a changed ref callback. */
+export declare function useStickyHeight(level: number): RefCallback<HTMLElement>;

package/dist/use-sticky-height.js

@@ -0,0 +1,37 @@
+import { c as _c } from "react/compiler-runtime";
+// eslint-disable-next-line no-restricted-imports -- React Compiler skips a hook whose only hook call is `use`; the ref needs a stable identity
+import { createContext, use, useCallback } from "react";
+/** The enclosing `StickyHeightProvider`'s height report. */
+export const StickyHeightContext = createContext(() => undefined);
+/** Ref reporting its element's border-box height as sticky level `level`,
+ *  to the enclosing `StickyHeightProvider`; zero once detached. One
+ *  header per level: each report replaces the level's height. Stable per
+ *  `level` and provider: React re-attaches a changed ref callback. */
+export function useStickyHeight(level) {
+  const $ = _c(3);
+  const setHeight = use(StickyHeightContext);
+  let t0;
+  if ($[0] !== level || $[1] !== setHeight) {
+    t0 = element => {
+      if (!element) {
+        return;
+      }
+      const observer = new ResizeObserver(t1 => {
+        const [entry] = t1;
+        const box = entry?.borderBoxSize?.[0];
+        setHeight(level, box ? box.blockSize : element.getBoundingClientRect().height);
+      });
+      observer.observe(element);
+      return () => {
+        observer.disconnect();
+        setHeight(level, 0);
+      };
+    };
+    $[0] = level;
+    $[1] = setHeight;
+    $[2] = t0;
+  } else {
+    t0 = $[2];
+  }
+  return t0;
+}

package/l10n.json

@@ -3,6 +3,8 @@
   "resources": {
     "repo-ui": {
       "include": [
+        "*.messages.json",
+        "router/*.messages.json",
         "slider/*.messages.json"
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astralarium/repo-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "homepage": "https://github.com/astralarium/repo/tree/main/packages/repo-ui#readme",
   "repository": {
@@ -16,7 +16,7 @@
   ],
   "exports": {
     ".": "./dist/index.js",
-    "./dev-route": "./dist/dev-route.js",
+    "./router": "./dist/router/index.js",
     "./slider": "./dist/slider/index.js",
     "./testkit": "./dist/testkit/index.js",
     "./l10n/*": "./dist/l10n/*"
@@ -43,14 +43,14 @@
     "typescript": "^6.0.3",
     "vite": "^8.3.4",
     "vitest": "^5.0.3",
+    "@astralarium/repo-config-vitest": "^0.2.0",
+    "@astralarium/repo-config-eslint": "^0.3.0",
+    "@astralarium/repo-config-typescript": "^0.1.0",
     "@astralarium/localizable": "^0.1.0",
-    "@astralarium/repo-config-vitest": "^0.1.0",
+    "@astralarium/repo-l10n": "^0.2.0",
+    "@astralarium/repo-l10n-manifest": "^0.1.1",
     "@astralarium/repo-package-build": "^0.1.0",
-    "@astralarium/repo-config-typescript": "^0.1.0",
-    "@astralarium/repo-config-eslint": "^0.1.0",
-    "@astralarium/repo-l10n-manifest": "^0.1.0",
-    "@astralarium/repo-package-files": "^0.1.0",
-    "@astralarium/repo-l10n": "^0.1.0"
+    "@astralarium/repo-package-files": "^0.1.0"
   },
   "peerDependencies": {
     "@base-ui/react": "^1.9.0",
@@ -59,8 +59,8 @@
     "react-dom": "^19.2.0",
     "vitest": "^5.0.3",
     "@astralarium/localizable": "^0.1.0",
-    "@astralarium/repo-config-vitest": "^0.1.0",
-    "@astralarium/repo-l10n-manifest": "^0.1.0"
+    "@astralarium/repo-config-vitest": "^0.2.0",
+    "@astralarium/repo-l10n-manifest": "^0.1.1"
   },
   "peerDependenciesMeta": {
     "@astralarium/repo-config-vitest": {