@apliteni/apliteni-ui 0.91.0 → 0.93.0

package/README.md

@@ -61,7 +61,7 @@ import { DataTable, Modal } from '@apliteni/apliteni-ui/react';
 
 The `appShell()` factory provides the complete product layout: the sticky rail, the page body
 and a topbar over it when you ask for one, so no product rebuilds it. The
-[component catalog](docs/library.md#component-catalog) lists this factory and every other one.
+[component catalog](docs/components.md#component-catalog) lists this factory and every other one.
 Account and personal settings belong in a modal over the product rather than on a page of
 their own — see [Guidelines / Account and settings](guidelines/account-and-settings.md).
 
@@ -100,7 +100,7 @@ only `data-accent` is present, the kit uses that accent with the dark theme. An
 `data-theme` does *not* mean “follow the system”: the kit has no `prefers-color-scheme`
 rule. If the host wants to follow the operating system preference, its JavaScript must
 choose the theme and add the attribute. See
-[an absent attribute means dark](docs/library.md#an-absent-attribute-means-dark).
+[an absent attribute means dark](docs/components.md#an-absent-attribute-means-dark).
 
 You can change the settings at runtime with `applyTheme('light')` and
 `applyAccent('phoenix')`. These functions save the choices to `localStorage`. You can also
@@ -121,12 +121,10 @@ section.
 
 | Page | What it answers |
 | --- | --- |
-| [specification.md](docs/specification.md) | What the kit guarantees and what it refuses to do. A gate on `npm test` holds every statement. |
-| [library.md](docs/library.md) | Architecture, the `src/` layout, tokens and theming, the component catalog. |
+| [foundations.md](docs/foundations.md) | The tokens and the floors: widths, breakpoints, spacing, type, colour, elevation, the focus ring, the tap floor. |
+| [components.md](docs/components.md) | The package: what to import, theming, the component catalog, and what each component guarantees. |
 | [react/README.md](react/README.md) | The React components, their props, and the Storybook on port 6007. |
-| [storybook.md](docs/storybook.md) | The workbench: config, theming toolbar, story conventions. |
-| [landing-page.md](docs/landing-page.md) | ui.apli.tech: the chrome, the static build, the hosting. |
-| [changelog.md](docs/changelog.md) | The changelog's data model and its Storybook deeplinks. |
+| [contributing.md](docs/contributing.md) | Working on the kit: the repository's layout, Storybook, the guidelines collection, the site, the changelog and releases. |
 
 ## Contribute
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -246,7 +246,7 @@ this component and compares what is left.
 Two things the factory has that this does not, both deliberate. It emits no `data-dropdown`
 on the container, so a page that calls `wireDropdown(document)` cannot adopt a dropdown React
 owns — the same decision `Drawer` makes about `data-drawer`; the row and panel hooks stay,
-because they are the row contract `docs/library.md` publishes. And it has no `portal: true`: the
+because they are the row contract `docs/components.md` publishes. And it has no `portal: true`: the
 panel is a child of the trigger's container, so a dropdown inside `.ui-app__rail`
 (`position: sticky` with `overflow-y: auto`) still wants the vanilla factory.
 
@@ -541,7 +541,7 @@ An optional `id` lets the caller choose the control ID; it must be unique.
 `type="search"` input, and no visible label, so the row keeps the height of the
 unlabelled controls beside it. `ariaLabel` is required and is the control's only
 name. It forwards its ref and the native input props, and `className` joins
-`.ui-input`. There is no clear button — see the specification for why.
+`.ui-input`. There is no clear button — see docs/components.md#react-search-field for why.
 
 ```tsx
 <div className="ui-toolbar">

package/react/dist/index.d.ts

@@ -730,7 +730,7 @@ type SearchFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'ar
  * No clear button. The browser paints its own near-black on the light field and
  * white on the dark one, beside the kit's `--muted` magnifier — two glyphs, and
  * only one answers to a token — so `input.css` suppresses it.
- * why: docs/specification.md#react-search-field
+ * why: docs/components.md#react-search-field
  */
 declare const SearchField: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "aria-label"> & {
     /** The control's name. A toolbar search box shows no label, so this is the
@@ -850,7 +850,7 @@ type SuccessProps = Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> &
     check?: SuccessMark;
     title?: string;
     /** One short line under the title, or nothing. There is no eyebrow tier.
-     *  why: docs/specification.md#success-confirmations */
+     *  why: docs/components.md#success-confirmations */
     body?: string;
     /** Removed: a confirmation carries one title and at most one line. Typed as
      *  `never` so a caller still passing it is told where it went rather than
@@ -869,7 +869,7 @@ declare const Success: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLD
     check?: SuccessMark;
     title?: string;
     /** One short line under the title, or nothing. There is no eyebrow tier.
-     *  why: docs/specification.md#success-confirmations */
+     *  why: docs/components.md#success-confirmations */
     body?: string;
     /** Removed: a confirmation carries one title and at most one line. Typed as
      *  `never` so a caller still passing it is told where it went rather than

package/react/dist/index.js

@@ -935,7 +935,7 @@ function rowId(uid, groups, item) {
 }
 
 // src/DataTable.tsx
-import { useEffect as useEffect5, useId as useId7, useMemo as useMemo2, useRef as useRef9, useState as useState5 } from "react";
+import { useMemo as useMemo2, useState as useState5 } from "react";
 import { DEFAULT_PAGE_SIZE as DEFAULT_PAGE_SIZE2 } from "@apliteni/apliteni-ui";
 
 // src/Pagination.tsx
@@ -1199,31 +1199,6 @@ function DataTable({
   hasMore = false
 }) {
   const scrollable = stickyHeader || pinnedIdentity;
-  const scrollId = useId7();
-  const scrollRegion = useRef9(null);
-  const [columnScroll, setColumnScroll] = useState5({ overflow: false, start: true, end: false });
-  const measureColumns = () => {
-    const region = scrollRegion.current;
-    if (region) setColumnScroll({
-      overflow: region.scrollWidth > region.clientWidth + 1,
-      start: region.scrollLeft <= 1,
-      end: region.scrollLeft + region.clientWidth >= region.scrollWidth - 1
-    });
-  };
-  useEffect5(() => {
-    if (!scrollable) return;
-    const region = scrollRegion.current;
-    if (!region) return;
-    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measureColumns);
-    observer?.observe(region);
-    if (region.firstElementChild) observer?.observe(region.firstElementChild);
-    measureColumns();
-    return () => observer?.disconnect();
-  }, [scrollable, columns, rows]);
-  const scrollColumns = (direction) => {
-    const region = scrollRegion.current;
-    if (region) region.scrollBy({ left: direction * region.clientWidth / 2, behavior: "instant" });
-  };
   const [localSort, setLocalSort] = useState5(
     { key: columns.find((c) => c.sortable)?.key, dir: -1 }
   );
@@ -1276,20 +1251,13 @@ function DataTable({
   );
   const pageAllOn = selectable && slice.length > 0 && slice.every((r) => selected.has(r.name));
   return /* @__PURE__ */ jsxs13(Fragment3, { children: [
-    scrollable && columnScroll.overflow && /* @__PURE__ */ jsxs13("div", { className: "ui-card__row", role: "group", "aria-label": `${scrollLabel} columns`, children: [
-      /* @__PURE__ */ jsx17(Button, { size: "sm", icon: "arrowLeft", "aria-controls": scrollId, disabled: columnScroll.start, onClick: () => scrollColumns(-1), children: "Previous columns" }),
-      /* @__PURE__ */ jsx17(Button, { size: "sm", iconRight: "arrowRight", "aria-controls": scrollId, disabled: columnScroll.end, onClick: () => scrollColumns(1), children: "More columns" })
-    ] }),
     /* @__PURE__ */ jsx17(
       "div",
       {
-        id: scrollId,
-        ref: scrollRegion,
-        onScroll: measureColumns,
-        className: stickyHeader || pinnedIdentity ? "ui-table-scroll" : void 0,
-        role: stickyHeader || pinnedIdentity ? "region" : void 0,
-        "aria-label": stickyHeader || pinnedIdentity ? scrollLabel : void 0,
-        tabIndex: stickyHeader || pinnedIdentity ? 0 : void 0,
+        className: scrollable ? "ui-table-scroll" : void 0,
+        role: scrollable ? "region" : void 0,
+        "aria-label": scrollable ? scrollLabel : void 0,
+        tabIndex: scrollable ? 0 : void 0,
         children: /* @__PURE__ */ jsxs13(
           "table",
           {
@@ -1442,9 +1410,9 @@ function Denied({
 // src/DatePicker.tsx
 import {
   useCallback as useCallback2,
-  useEffect as useEffect6,
+  useEffect as useEffect5,
   useMemo as useMemo3,
-  useRef as useRef10,
+  useRef as useRef9,
   useState as useState6
 } from "react";
 import { jsx as jsx19, jsxs as jsxs15 } from "react/jsx-runtime";
@@ -1457,7 +1425,7 @@ var DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 var PHONE_MAX = 560;
 function usePhone() {
   const [phone, setPhone] = useState6(false);
-  useEffect6(() => {
+  useEffect5(() => {
     const query = typeof window === "undefined" ? null : window.matchMedia?.(`(max-width: ${PHONE_MAX}px)`);
     if (!query) return;
     const read = () => setPhone(query.matches);
@@ -1552,9 +1520,9 @@ function DatePicker({
   const picksRange = mode === "range" || mode === "day-range";
   const phone = usePhone();
   const asSheet = sheet ?? phone;
-  const root = useRef10(null);
-  const trigger = useRef10(null);
-  const grid = useRef10(null);
+  const root = useRef9(null);
+  const trigger = useRef9(null);
+  const grid = useRef9(null);
   const [selfOpen, setSelfOpen] = useState6(defaultOpen);
   const open = openProp ?? selfOpen;
   const [selfValue, setSelfValue] = useState6(defaultValue);
@@ -1591,19 +1559,19 @@ function DatePicker({
   }, [today, grain]);
   const anchor = toIndex(picked, grain) ?? toIndex(picksRange ? span.start ?? span.end : null, grain) ?? todayIndex;
   const [cursor, setCursor] = useState6(() => clamp(anchor, lo, hi));
-  const land = useRef10(false);
+  const land = useRef9(false);
   const setOpen = useCallback2((next) => {
     if (openProp === void 0) setSelfOpen(next);
     onOpenChange?.(next);
   }, [openProp, onOpenChange]);
-  const close = useRef10(setOpen);
+  const close = useRef9(setOpen);
   useIsoLayoutEffect(() => {
     close.current = setOpen;
   });
-  useEffect6(() => {
+  useEffect5(() => {
     if (open) setCursor(clamp(anchor, lo, hi));
   }, [open]);
-  useEffect6(() => {
+  useEffect5(() => {
     if (!open || asSheet) return;
     const doc = root.current?.ownerDocument ?? document;
     const onClick = (e) => {
@@ -1913,9 +1881,9 @@ function DatePicker({
 import {
   Fragment as Fragment4,
   useCallback as useCallback3,
-  useEffect as useEffect7,
-  useId as useId8,
-  useRef as useRef11,
+  useEffect as useEffect6,
+  useId as useId7,
+  useRef as useRef10,
   useState as useState7
 } from "react";
 import {
@@ -1987,19 +1955,19 @@ function Dropdown({
   const [pick, setPick] = useState7(null);
   const [query, setQuery] = useState7(() => search && search !== true ? search.query || "" : "");
   const [activeKey, setActiveKey] = useState7(null);
-  const root = useRef11(null);
-  const panel = useRef11(null);
-  const trigger = useRef11(null);
-  const field = useRef11(null);
-  const landOn = useRef11(null);
-  const at = useRef11("");
-  const auto = useId8().replace(/:/g, "");
+  const root = useRef10(null);
+  const panel = useRef10(null);
+  const trigger = useRef10(null);
+  const field = useRef10(null);
+  const landOn = useRef10(null);
+  const at = useRef10("");
+  const auto = useId7().replace(/:/g, "");
   const uid = id ?? auto;
   const setOpen = useCallback3((next) => {
     if (openProp === void 0) setSelfOpen(next);
     onOpenChange?.(next);
   }, [openProp, onOpenChange]);
-  const close = useRef11(setOpen);
+  const close = useRef10(setOpen);
   useIsoLayoutEffect(() => {
     close.current = setOpen;
   });
@@ -2052,7 +2020,7 @@ function Dropdown({
       stop.forEach((off) => off());
     };
   }, [open]);
-  const opened = useRef11(false);
+  const opened = useRef10(false);
   useIsoLayoutEffect(() => {
     const el = panel.current;
     if (open) {
@@ -2091,7 +2059,7 @@ function Dropdown({
   const given = rows.find((it) => it.selected);
   const givenKey = given ? keyOf(given) : null;
   const pickedKey = pick && pick.against === givenKey ? pick.key : null;
-  useEffect7(() => {
+  useEffect6(() => {
     if (pick && pick.against !== givenKey) setPick(null);
   }, [givenKey, pick]);
   const picked = pickedKey != null ? rows.find((it) => keyOf(it) === pickedKey) : void 0;
@@ -2105,7 +2073,7 @@ function Dropdown({
   const rowIds = /* @__PURE__ */ new Map();
   rows.forEach((it, i) => rowIds.set(it, `${uid}-opt-${i}`));
   const listId = `${uid}-list`;
-  useEffect7(() => {
+  useEffect6(() => {
     if (!open) return;
     const mine = () => close.current(false);
     for (const other of [...openNow]) other();
@@ -2114,7 +2082,7 @@ function Dropdown({
       openNow.delete(mine);
     };
   }, [open]);
-  useEffect7(() => {
+  useEffect6(() => {
     if (!open) return;
     const doc = root.current?.ownerDocument ?? document;
     const onClick = (e) => {
@@ -2495,12 +2463,12 @@ function Segmented({ options, value, onChange, label, appearance = "pill", disab
 }
 
 // src/FilterBar.tsx
-import { useRef as useRef12, useState as useState8 } from "react";
+import { useRef as useRef11, useState as useState8 } from "react";
 import { filterChipText, filterChipName, filterChipUnset, filterChipItems, focusNextStop } from "@apliteni/apliteni-ui";
 import { jsx as jsx24, jsxs as jsxs19 } from "react/jsx-runtime";
 function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters", disabled = false, busy = false, onRemove, onClear, onChange }) {
-  const bar = useRef12(null);
-  const focused = useRef12(null);
+  const bar = useRef11(null);
+  const focused = useRef11(null);
   const [opened, setOpened] = useState8({});
   const blocked = disabled || busy;
   useIsoLayoutEffect(() => {
@@ -2606,13 +2574,13 @@ function DrawerSection({ title, headingLevel = 3, className, children, ...rest }
 }
 
 // src/Snippet.tsx
-import { useEffect as useEffect8, useRef as useRef13, useState as useState9 } from "react";
+import { useEffect as useEffect7, useRef as useRef12, useState as useState9 } from "react";
 import { Fragment as Fragment6, jsx as jsx26, jsxs as jsxs21 } from "react/jsx-runtime";
 function Snippet({ label = "shell", code = "", children, copy = true, reveal = false, copyLabel = "Copy code" }) {
   const [status, setStatus] = useState9("idle");
-  const request = useRef13(0);
-  const timer = useRef13(void 0);
-  useEffect8(() => {
+  const request = useRef12(0);
+  const timer = useRef12(void 0);
+  useEffect7(() => {
     setStatus("idle");
     return () => {
       request.current++;
@@ -2655,15 +2623,15 @@ function Snippet({ label = "shell", code = "", children, copy = true, reveal = f
 }
 
 // src/Tabs.tsx
-import { useEffect as useEffect9, useId as useId9, useRef as useRef14 } from "react";
+import { useEffect as useEffect8, useId as useId8, useRef as useRef13 } from "react";
 import { playEntrance } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment7, jsx as jsx27, jsxs as jsxs22 } from "react/jsx-runtime";
 function Tabs({ items, value, onChange, label }) {
-  const id = useId9();
-  const previous = useRef14(value);
-  const activePanel = useRef14(null);
-  const buttons = useRef14([]);
-  useEffect9(() => {
+  const id = useId8();
+  const previous = useRef13(value);
+  const activePanel = useRef13(null);
+  const buttons = useRef13([]);
+  useEffect8(() => {
     if (previous.current !== value) playEntrance(activePanel.current);
     previous.current = value;
   }, [value]);
@@ -2732,14 +2700,14 @@ function Tabs({ items, value, onChange, label }) {
 }
 
 // src/Timeline.tsx
-import { useEffect as useEffect10, useRef as useRef15 } from "react";
+import { useEffect as useEffect9, useRef as useRef14 } from "react";
 import { playEntrance as playEntrance2, prefersReducedMotion } from "@apliteni/apliteni-ui/motion";
 import { jsx as jsx28, jsxs as jsxs23 } from "react/jsx-runtime";
 var kindIcons = { person: "user", rule: "bolt", reversal: "refresh" };
 function Timeline({ events, className, ...rest }) {
-  const previousIds = useRef15(new Set(events.map((event) => event.id)));
-  const rows = useRef15(/* @__PURE__ */ new Map());
-  useEffect10(() => {
+  const previousIds = useRef14(new Set(events.map((event) => event.id)));
+  const rows = useRef14(/* @__PURE__ */ new Map());
+  useEffect9(() => {
     if (previousIds.current.size > 0 && !prefersReducedMotion()) {
       for (const event of events) {
         if (previousIds.current.has(event.id)) continue;
@@ -2782,7 +2750,7 @@ function Timeline({ events, className, ...rest }) {
 }
 
 // src/Field.tsx
-import { forwardRef as forwardRef6, useEffect as useEffect11, useId as useId10, useRef as useRef16, useState as useState10 } from "react";
+import { forwardRef as forwardRef6, useEffect as useEffect10, useId as useId9, useRef as useRef15, useState as useState10 } from "react";
 import { esc, icon as icon4 } from "@apliteni/apliteni-ui";
 import { jsx as jsx29, jsxs as jsxs24 } from "react/jsx-runtime";
 function messages(id, hint, error) {
@@ -2811,12 +2779,12 @@ function wiring(id, hint, error) {
   return { id, "aria-describedby": messages(id, hint, error), "aria-invalid": error ? true : void 0 };
 }
 function Field({ id: suppliedId, label, hint, error, required, children }) {
-  const generatedId = useId10();
+  const generatedId = useId9();
   const id = suppliedId ?? generatedId;
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: children({ ...wiring(id, hint, error), required }) });
 }
 var TextField = forwardRef6(function TextField2({ label, hint, error, required, type = "text", unit, icon: glyph, className = "", ...props }, ref) {
-  const id = useId10();
+  const id = useId9();
   const hasUnit = type === "number" && !!unit;
   const describedBy = [messages(id, hint, error), hasUnit ? `${id}-unit` : ""].filter(Boolean).join(" ") || void 0;
   const control = /* @__PURE__ */ jsx29(
@@ -2843,7 +2811,7 @@ var TextField = forwardRef6(function TextField2({ label, hint, error, required,
   ] }) : control });
 });
 function TextArea({ label, hint, error, required, className = "", ...props }) {
-  const id = useId10();
+  const id = useId9();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "textarea",
     {
@@ -2856,7 +2824,7 @@ function TextArea({ label, hint, error, required, className = "", ...props }) {
   ) });
 }
 function SelectField({ label, hint, error, required, className = "", children, ...props }) {
-  const id = useId10();
+  const id = useId9();
   return /* @__PURE__ */ jsx29(Frame, { ...{ id, label, hint, error, required }, children: /* @__PURE__ */ jsx29(
     "select",
     {
@@ -2869,11 +2837,11 @@ function SelectField({ label, hint, error, required, className = "", children, .
   ) });
 }
 function FileField({ label, hint, error, required, disabled, onFileChange, className = "", ...props }) {
-  const id = useId10();
-  const input = useRef16(null);
+  const id = useId9();
+  const input = useRef15(null);
   const [file, setFile] = useState10(null);
   const [dragging, setDragging] = useState10(false);
-  useEffect11(() => {
+  useEffect10(() => {
     const form = input.current?.form;
     const reset = () => {
       setFile(null);
@@ -2932,7 +2900,7 @@ function FileField({ label, hint, error, required, disabled, onFileChange, class
 }
 
 // src/FileDrop.tsx
-import { useRef as useRef17, useState as useState11 } from "react";
+import { useRef as useRef16, useState as useState11 } from "react";
 import { Fragment as Fragment8, jsx as jsx30, jsxs as jsxs25 } from "react/jsx-runtime";
 var MARKS = {
   uploading: "clock",
@@ -2966,7 +2934,7 @@ function FileDrop({
   children,
   className
 }) {
-  const input = useRef17(null);
+  const input = useRef16(null);
   const [over, setOver] = useState11(false);
   const status = file?.status ?? "uploading";
   const word = status === "error" ? file?.error ?? WORDS.error : file?.state ?? WORDS[status];
@@ -3101,7 +3069,7 @@ var SearchField = forwardRef7(function SearchField2({ ariaLabel, className, ...p
 });
 
 // src/Toast.tsx
-import { createContext as createContext2, useCallback as useCallback4, useContext as useContext2, useEffect as useEffect12, useLayoutEffect as useLayoutEffect4, useRef as useRef18, useState as useState12 } from "react";
+import { createContext as createContext2, useCallback as useCallback4, useContext as useContext2, useEffect as useEffect11, useLayoutEffect as useLayoutEffect4, useRef as useRef17, useState as useState12 } from "react";
 import { createPortal as createPortal4 } from "react-dom";
 import { jsx as jsx32, jsxs as jsxs27 } from "react/jsx-runtime";
 var Context = createContext2(null);
@@ -3112,10 +3080,10 @@ function useToast() {
   return push;
 }
 function Notice({ notice, remove }) {
-  const root = useRef18(null);
+  const root = useRef17(null);
   const [leaving2, setLeaving] = useState12(false);
-  const dismissed = useRef18(false);
-  const remaining = useRef18(5e3);
+  const dismissed = useRef17(false);
+  const remaining = useRef17(5e3);
   const [hovered, setHovered] = useState12(false);
   const [focused, setFocused] = useState12(false);
   const paused = hovered || focused;
@@ -3126,7 +3094,7 @@ function Notice({ notice, remove }) {
     if (typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches) remove();
     else setLeaving(true);
   }, [remove]);
-  useEffect12(() => {
+  useEffect11(() => {
     if (leaving2) {
       const element = root.current;
       const finish = (event) => {
@@ -3140,7 +3108,7 @@ function Notice({ notice, remove }) {
       };
     }
   }, [leaving2, remove]);
-  useEffect12(() => {
+  useEffect11(() => {
     if (leaving2 || notice.action || paused) return;
     const started = Date.now();
     const timer = setTimeout(dismiss, remaining.current);
@@ -3218,8 +3186,8 @@ function usePublishedReach(stack2, count) {
 }
 function Toast({ children }) {
   const [entries, setEntries] = useState12([]);
-  const nextId = useRef18(0);
-  const stack2 = useRef18(null);
+  const nextId = useRef17(0);
+  const stack2 = useRef17(null);
   const push = useCallback4((notice) => {
     const id = nextId.current++;
     const remove = () => setEntries((current) => current.filter((entry) => entry.id !== id));
@@ -3236,22 +3204,22 @@ function Toast({ children }) {
 }
 
 // src/AppShell.tsx
-import { useEffect as useEffect14, useId as useId12, useState as useState14 } from "react";
+import { useEffect as useEffect13, useId as useId11, useState as useState14 } from "react";
 import { applyTheme, paletteHotkey, prism, railCollapsed, themeIcon, themeName } from "@apliteni/apliteni-ui";
 
 // src/SidebarNav.tsx
-import { forwardRef as forwardRef8, useEffect as useEffect13, useId as useId11, useState as useState13 } from "react";
+import { forwardRef as forwardRef8, useEffect as useEffect12, useId as useId10, useState as useState13 } from "react";
 import { ENTRANCE_FALLBACK_MS } from "@apliteni/apliteni-ui/motion";
 import { Fragment as Fragment9, jsx as jsx33, jsxs as jsxs28 } from "react/jsx-runtime";
 var badgeText = (badge) => typeof badge === "object" ? badge.text : badge;
 function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
-  const uid = useId11();
+  const uid = useId10();
   const group = !sub && !!item.items?.length;
   const childActive = group && item.items.some((child) => child.id === active);
   const [expanded, setExpanded] = useState13();
   const open = expanded ?? item.defaultOpen ?? childActive;
   const [entering, setEntering] = useState13(false);
-  useEffect13(() => {
+  useEffect12(() => {
     if (!entering) return;
     const timer = setTimeout(() => setEntering(false), ENTRANCE_FALLBACK_MS);
     return () => clearTimeout(timer);
@@ -3302,7 +3270,7 @@ function Row({ item, active, activeIs, collapsed, renderLink, sub }) {
   return /* @__PURE__ */ jsx33("li", { children: renderLink ? renderLink(item, props) : /* @__PURE__ */ jsx33("a", { ...props }) });
 }
 function Section({ section, ...props }) {
-  const uid = useId11();
+  const uid = useId10();
   return /* @__PURE__ */ jsxs28("div", { className: "ui-nav__section", children: [
     section.label && /* @__PURE__ */ jsx33("div", { className: "ui-nav__cap", id: uid, "aria-hidden": props.collapsed || void 0, children: section.label }),
     /* @__PURE__ */ jsx33("ul", { className: "ui-nav__list", "aria-labelledby": section.label ? uid : void 0, children: section.items.map((item) => /* @__PURE__ */ jsx33(Row, { item, ...props }, item.id)) })
@@ -3358,21 +3326,21 @@ function AppShell({
   palette,
   renderLink
 }) {
-  const uid = useId12();
+  const uid = useId11();
   const [collapsed, setCollapsed] = useState14(defaultCollapsed);
   const [search, setSearch] = useState14(false);
   const [more, setMore] = useState14(false);
   const [theme, setTheme] = useState14("dark");
   const current = path(pathname);
   const active = sections.filter((section) => current === path(section.href) || path(section.href) !== "/" && current.startsWith(`${path(section.href)}/`)).sort((a, b) => path(b.href).length - path(a.href).length)[0];
-  useEffect14(() => {
+  useEffect13(() => {
     setCollapsed(railCollapsed() ?? defaultCollapsed);
   }, [defaultCollapsed]);
-  useEffect14(() => {
+  useEffect13(() => {
     setMore(false);
     setSearch(false);
   }, [pathname]);
-  useEffect14(() => {
+  useEffect13(() => {
     const root = document.documentElement;
     const sync2 = () => setTheme(root.getAttribute("data-theme") === "light" ? "light" : "dark");
     sync2();
@@ -3380,7 +3348,7 @@ function AppShell({
     observer.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
     return () => observer.disconnect();
   }, []);
-  useEffect14(() => {
+  useEffect13(() => {
     const hotkey = (event) => {
       if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.key.toLowerCase() !== "k") return;
       const target = event.target;
@@ -3607,7 +3575,7 @@ function ThemeToggle({ labelled = false }) {
 }
 
 // src/Success.tsx
-import { forwardRef as forwardRef9, useEffect as useEffect15, useRef as useRef19, useState as useState15 } from "react";
+import { forwardRef as forwardRef9, useEffect as useEffect14, useRef as useRef18, useState as useState15 } from "react";
 import { jsx as jsx37, jsxs as jsxs32 } from "react/jsx-runtime";
 var SuccessCheck = forwardRef9(function SuccessCheck2({ variant = "line", className, ...rest }, ref) {
   const circled = variant === "circled";
@@ -3655,11 +3623,11 @@ var pieces = [
 ];
 function Countdown({ seconds, label = "Redirecting", onDone }) {
   const [remaining, setRemaining] = useState15(seconds);
-  const callback = useRef19(onDone);
-  useEffect15(() => {
+  const callback = useRef18(onDone);
+  useEffect14(() => {
     callback.current = onDone;
   }, [onDone]);
-  useEffect15(() => {
+  useEffect14(() => {
     let count = seconds;
     const timer = setInterval(() => {
       count -= 1;

package/src/assets/icons.js

@@ -166,7 +166,7 @@ export const iconNames = Object.keys(ICONS);
 // `filter` — Lucide's funnel — fails the first test. Depicting a thing is not the
 // fault; `copy` is on this list and depicts one too. The kit reads the funnel alone
 // as not saying whether the control filters, sorts or exports — its own inference
-// from the sources in docs/specification.md, not a measured recognition finding.
+// from the sources in docs/foundations.md, not a measured recognition finding.
 // See #565.
 export const iconOnlyAllowed = {
   x: 'close or dismiss',

package/src/components/account-nav.js

@@ -2,8 +2,8 @@
 // that interpolates raw. It lives here rather than in shell.js because both
 // shell.js and topbar.js need it and shell.js already imports topbar.js — the
 // other direction would be a cycle. shell.js re-exports ACCOUNT_NAV, which is
-// the published name docs/library.md documents.
-// why: docs/specification.md#the-page-shell
+// the published name docs/components.md documents.
+// why: docs/components.md#the-page-shell
 import { esc } from './index.js';
 
 // nav.js item objects. Labels are raw text — every nav primitive escapes, so a

package/src/components/back.js

@@ -11,7 +11,7 @@
 // docs/reviews/270-back-control.html and the owner chose this one, so the other
 // three — a bordered button above the title, an icon-only arrow beside it, and
 // the breadcrumb trail alone — are not built here.
-// why: docs/specification.md#the-back-link
+// why: docs/components.md#the-back-link
 import { esc, icon } from './index.js';
 
 // "Back" names a direction rather than a place. It is what a caller who names no
@@ -29,7 +29,7 @@ const TAB_OR_NEWLINE = /[\t\n\r]/g;
 
 // A label that already says "Back to Invoices" names the place after those words, or the
 // link would be read as "Back to Back to Invoices". The whole phrase, since "Backups" and
-// "Back office" are places too. why: docs/specification.md#the-back-link
+// "Back office" are places too. why: docs/components.md#the-back-link
 const SAID = /^back\s+to(?:\s+|$)/i;
 
 const text = (v) => (typeof v === 'string' || typeof v === 'number' ? String(v).trim() : '');

package/src/components/command-palette.js

@@ -9,7 +9,7 @@ export { SCORE, scoreCommand, rankCommands, rankGroups, paletteHotkey } from '..
 // The kit ships the shell and the ranking and names no result kinds; a row goes
 // somewhere, runs something, or asks a confirm first. Inertness, Escape and the
 // focus trap come from ./overlay.js, the stack the drawer and the confirm share.
-// why: docs/specification.md#the-command-palette
+// why: docs/components.md#the-command-palette
 import { esc, icon } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 import { safeUrl } from '../html.js';
@@ -61,7 +61,7 @@ function keysFor(shortcut) {
  * the wiring, which is also what makes Cmd+Enter open it in a tab.
  *
  * A destructive item that names no confirm is rendered DISABLED. The kit's rule
- * is that a delete asks first (docs/specification.md#the-command-palette), and a
+ * is that a delete asks first (docs/components.md#the-command-palette), and a
  * palette is the one surface where a reader is typing fast and choosing from a
  * list that reorders under them.
  */

package/src/components/drawer.js

@@ -75,7 +75,7 @@ export function drawer({
  *
  *   drawer({ title, body: drawerSection({ title: 'Source', rows: [['Statement', '#4102']] }) })
  *
- * why: docs/specification.md#the-drawer
+ * why: docs/components.md#the-drawer
  *
  * @param {object} [o]
  * @param {string} [o.title]  group heading (escaped)