shelving 1.236.0 → 1.236.2

package/ui/tree/TreeMenu.js

@@ -5,8 +5,14 @@ import { Menu, MenuItem } from "../menu/Menu.js";
 import { createMapper } from "../misc/Mapper.js";
 /**
  * Match an element that should appear in the sidebar menu.
+ *
  * - Generic tree elements (directories and files) always qualify.
  * - For documentation elements, only `kind: "module"` qualifies — functions, classes, methods, properties, etc. are kept off the navigation.
+ *
+ * @param element The element to test.
+ * @returns `true` when the element should appear in the menu, `false` otherwise.
+ * @example matchMenuElement(element) // true
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/matchMenuElement
  */
 export function matchMenuElement(element) {
     const { type, props } = element;
@@ -18,24 +24,40 @@ export function matchMenuElement(element) {
 }
 /**
  * Default menu item renderer for any `tree-*` element.
+ *
  * - Computes its own URL path by appending its `name` to the parent's `path`.
  * - Passes both the label and the nested `<TreeMenuMapper>` to `<MenuItem>`; `<MenuItem>` itself decides whether to reveal the nested submenu based on the current URL.
+ *
+ * @param props The tree element props plus the parent's `path`.
+ * @returns A `<MenuItem>` for the element, with a nested `<Menu>` when it has menu-eligible children.
+ * @example <TreeMenuItem {...element.props} path="/" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenuItem
  */
 export function TreeMenuItem({ path = "/", name, title, children }) {
     const href = joinPath(path, name);
     const submenu = Array.from(filterElements(children, matchMenuElement));
     return (_jsxs(MenuItem, { href: href, children: [title ?? name, submenu.length ? (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: href, children: submenu }) })) : null] }));
 }
-/** Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override. */
+/**
+ * Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override the per-type menu-item renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenuMapping
+ */
 export const [TreeMenuMapping, TreeMenuMapper] = createMapper({
     "tree-element": TreeMenuItem,
     "tree-documentation": TreeMenuItem,
 });
 /**
  * Sidebar navigation menu built from the children of a root tree element.
+ *
  * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`).
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
+ *
+ * @param props The root `tree` element and optional root `path`.
+ * @returns A `<Menu>` of navigation links to the root's children.
+ * @example <TreeMenu tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenu
  */
 export function TreeMenu({ path = "/", tree }) {
     return (_jsx(Menu, { children: _jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) }) }));

package/ui/tree/TreeMenu.tsx

@@ -7,8 +7,14 @@ import { createMapper } from "../misc/Mapper.js";
 
 /**
  * Match an element that should appear in the sidebar menu.
+ *
  * - Generic tree elements (directories and files) always qualify.
  * - For documentation elements, only `kind: "module"` qualifies — functions, classes, methods, properties, etc. are kept off the navigation.
+ *
+ * @param element The element to test.
+ * @returns `true` when the element should appear in the menu, `false` otherwise.
+ * @example matchMenuElement(element) // true
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/matchMenuElement
  */
 export function matchMenuElement(element: Element): boolean {
 	const { type, props } = element;
@@ -25,8 +31,14 @@ interface TreeMenuExtras {
 
 /**
  * Default menu item renderer for any `tree-*` element.
+ *
  * - Computes its own URL path by appending its `name` to the parent's `path`.
  * - Passes both the label and the nested `<TreeMenuMapper>` to `<MenuItem>`; `<MenuItem>` itself decides whether to reveal the nested submenu based on the current URL.
+ *
+ * @param props The tree element props plus the parent's `path`.
+ * @returns A `<MenuItem>` for the element, with a nested `<Menu>` when it has menu-eligible children.
+ * @example <TreeMenuItem {...element.props} path="/" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenuItem
  */
 export function TreeMenuItem({ path = "/", name, title, children }: TreeElementProps & TreeMenuExtras): ReactNode {
 	const href = joinPath(path, name);
@@ -43,12 +55,21 @@ export function TreeMenuItem({ path = "/", name, title, children }: TreeElementP
 	);
 }
 
-/** Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override. */
+/**
+ * Mapping + Mapper pair for the menu — wrap children in `<TreeMenuMapping>` to override the per-type menu-item renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenuMapping
+ */
 export const [TreeMenuMapping, TreeMenuMapper] = createMapper<TreeMenuExtras>({
 	"tree-element": TreeMenuItem,
 	"tree-documentation": TreeMenuItem,
 });
 
+/**
+ * Props for the `TreeMenu` component — the root tree element plus its URL path.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenuProps
+ */
 export interface TreeMenuProps {
 	/** Root element whose children become the navigation links. */
 	readonly tree: TreeElement;
@@ -58,9 +79,15 @@ export interface TreeMenuProps {
 
 /**
  * Sidebar navigation menu built from the children of a root tree element.
+ *
  * - Renders each child via `<TreeMenuItem>` (the default mapping for `tree-element`).
  * - To customise renderers for specific types, wrap in `<TreeMenuMapping mapping={…}>`.
  * - Only directories and files appear — code symbols are kept off the navigation.
+ *
+ * @param props The root `tree` element and optional root `path`.
+ * @returns A `<Menu>` of navigation links to the root's children.
+ * @example <TreeMenu tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeMenu/TreeMenu
  */
 export function TreeMenu({ path = "/", tree }: TreeMenuProps): ReactNode {
 	return (

package/ui/tree/TreePage.d.ts

@@ -2,7 +2,13 @@ import type { ReactNode } from "react";
 import type { TreeElementProps } from "../../util/tree.js";
 /**
  * Page renderer for a generic `tree-element` (a directory or file).
+ *
  * - Shows the title, any absorbed prose content, and the element's children as a stack of cards.
  * - Child cards cover both nested directories/files and the code symbols of a source file.
+ *
+ * @param props The tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with the title, prose content, and a stack of child cards.
+ * @example <TreePage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreePage/TreePage
  */
 export declare function TreePage({ title, name, description, content, children }: TreeElementProps): ReactNode;

package/ui/tree/TreePage.js

@@ -7,8 +7,14 @@ import { Page } from "../page/Page.js";
 import { TreeCards } from "./TreeCards.js";
 /**
  * Page renderer for a generic `tree-element` (a directory or file).
+ *
  * - Shows the title, any absorbed prose content, and the element's children as a stack of cards.
  * - Child cards cover both nested directories/files and the code symbols of a source file.
+ *
+ * @param props The tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with the title, prose content, and a stack of child cards.
+ * @example <TreePage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreePage/TreePage
  */
 export function TreePage({ title, name, description, content, children }) {
     return (_jsxs(Page, { title: title ?? name, description: description, children: [_jsx(Header, { wide: true, children: _jsx(Title, { children: title ?? name }) }), _jsx(Section, { wide: true, children: content && (_jsx(Prose, { children: _jsx(Markup, { children: content }) })) }), _jsx(Section, { wide: true, children: _jsx(TreeCards, { children: children }) })] }));

package/ui/tree/TreePage.tsx

@@ -9,8 +9,14 @@ import { TreeCards } from "./TreeCards.js";
 
 /**
  * Page renderer for a generic `tree-element` (a directory or file).
+ *
  * - Shows the title, any absorbed prose content, and the element's children as a stack of cards.
  * - Child cards cover both nested directories/files and the code symbols of a source file.
+ *
+ * @param props The tree element props (`title`, `name`, `description`, `content`, `children`).
+ * @returns A `<Page>` with the title, prose content, and a stack of child cards.
+ * @example <TreePage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreePage/TreePage
  */
 export function TreePage({ title, name, description, content, children }: TreeElementProps): ReactNode {
 	return (

package/ui/tree/TreeRouter.d.ts

@@ -1,10 +1,19 @@
 import type { ReactElement, ReactNode } from "react";
 import type { TreeElement } from "../../util/tree.js";
 import type { PossibleMeta } from "../util/index.js";
-/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override the per-type page renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouterMapping
+ */
 export declare const TreeRouterMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<unknown>>, TreeRouterMapper: import("react").FunctionComponent<{
     readonly children?: import("../../index.js").Elements;
 }>;
+/**
+ * Props for the `TreeRouter` component — the tree to route plus an optional fallback and app meta.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouterProps
+ */
 export interface TreeRouterProps extends PossibleMeta {
     /** The tree of elements to match routes for. */
     readonly tree: TreeElement;
@@ -16,10 +25,16 @@ export interface TreeRouterProps extends PossibleMeta {
 }
 /**
  * Resolve a URL path to a tree element and render it as a full page.
+ *
  * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
- * - Throws `NotFoundError` if no element matches and no `fallback` is given.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
+ *
+ * @param props The `tree` to route, an optional `fallback`, and app meta.
+ * @returns The resolved element rendered as a page, or the `fallback`.
+ * @throws NotFoundError When no element matches the URL and no `fallback` is given.
+ * @example <TreeRouter tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouter
  */
 export declare function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode;

package/ui/tree/TreeRouter.js

@@ -5,18 +5,28 @@ import { createMapper } from "../misc/Mapper.js";
 import { MetaContext, requireMetaURL } from "../misc/MetaContext.js";
 import { TreeProvider, useTreeMap } from "./TreeContext.js";
 import { TreePage } from "./TreePage.js";
-/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override the per-type page renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouterMapping
+ */
 export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
     "tree-element": TreePage,
     "tree-documentation": DocumentationPage,
 });
 /**
  * Resolve a URL path to a tree element and render it as a full page.
+ *
  * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
- * - Throws `NotFoundError` if no element matches and no `fallback` is given.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
+ *
+ * @param props The `tree` to route, an optional `fallback`, and app meta.
+ * @returns The resolved element rendered as a page, or the `fallback`.
+ * @throws NotFoundError When no element matches the URL and no `fallback` is given.
+ * @example <TreeRouter tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouter
  */
 export function TreeRouter({ tree, fallback, ...meta }) {
     const { path, ...combined } = requireMetaURL(meta);

package/ui/tree/TreeRouter.tsx

@@ -9,12 +9,21 @@ import type { PossibleMeta } from "../util/index.js";
 import { TreeProvider, useTreeMap } from "./TreeContext.js";
 import { TreePage } from "./TreePage.js";
 
-/** Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree routers — wrap children in `<TreeRouterMapping>` to override the per-type page renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouterMapping
+ */
 export const [TreeRouterMapping, TreeRouterMapper] = createMapper({
 	"tree-element": TreePage,
 	"tree-documentation": DocumentationPage,
 });
 
+/**
+ * Props for the `TreeRouter` component — the tree to route plus an optional fallback and app meta.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouterProps
+ */
 export interface TreeRouterProps extends PossibleMeta {
 	/** The tree of elements to match routes for. */
 	readonly tree: TreeElement;
@@ -28,11 +37,17 @@ export interface TreeRouterProps extends PossibleMeta {
 
 /**
  * Resolve a URL path to a tree element and render it as a full page.
+ *
  * - Flattens the tree once (via `<TreeProvider>`) into a `path` → element map, then resolves the current URL with a single `map.get(path)`.
  * - `/` renders the root itself; deeper paths render the matching descendant (composite module names like `/util/string` resolve for free — they're whole keys in the map).
  * - The resolved element is already stamped with its canonical `path`, so the page and its cards link straight to their own paths — nothing needs threading.
- * - Throws `NotFoundError` if no element matches and no `fallback` is given.
  * - To override the renderer for a specific element type, wrap in `<TreeRouterMapping mapping={…}>`.
+ *
+ * @param props The `tree` to route, an optional `fallback`, and app meta.
+ * @returns The resolved element rendered as a page, or the `fallback`.
+ * @throws NotFoundError When no element matches the URL and no `fallback` is given.
+ * @example <TreeRouter tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeRouter/TreeRouter
  */
 export function TreeRouter({ tree, fallback, ...meta }: TreeRouterProps): ReactNode {
 	const { path, ...combined } = requireMetaURL(meta);

package/ui/tree/TreeSidebar.d.ts

@@ -1,6 +1,11 @@
 import type { ReactNode } from "react";
 import type { AbsolutePath } from "../../util/path.js";
 import type { TreeElement } from "../../util/tree.js";
+/**
+ * Props for the `TreeSidebar` component — the root tree element plus its URL path.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebarProps
+ */
 export interface TreeSidebarProps {
     /** Root element of the tree. */
     readonly tree: TreeElement;
@@ -9,8 +14,14 @@ export interface TreeSidebarProps {
 }
 /**
  * Sidebar built from a tree element.
+ *
  * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ *
+ * @param props The root `tree` element and optional root `path`.
+ * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @example <TreeSidebar tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */
 export declare function TreeSidebar({ tree, path }: TreeSidebarProps): ReactNode;

package/ui/tree/TreeSidebar.js

@@ -4,9 +4,15 @@ import { Menu, MenuItem } from "../menu/Menu.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 /**
  * Sidebar built from a tree element.
+ *
  * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ *
+ * @param props The root `tree` element and optional root `path`.
+ * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @example <TreeSidebar tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */
 export function TreeSidebar({ tree, path = "/" }) {
     return (_jsxs(Menu, { children: [_jsx(MenuItem, { href: path, children: tree.props.title ?? tree.props.name }), _jsx(TreeMenuMapper, { path: path, children: filterElements(tree.props.children, matchMenuElement) })] }));

package/ui/tree/TreeSidebar.tsx

@@ -5,6 +5,11 @@ import type { TreeElement } from "../../util/tree.js";
 import { Menu, MenuItem } from "../menu/Menu.js";
 import { matchMenuElement, TreeMenuMapper } from "./TreeMenu.js";
 
+/**
+ * Props for the `TreeSidebar` component — the root tree element plus its URL path.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebarProps
+ */
 export interface TreeSidebarProps {
 	/** Root element of the tree. */
 	readonly tree: TreeElement;
@@ -14,9 +19,15 @@ export interface TreeSidebarProps {
 
 /**
  * Sidebar built from a tree element.
+ *
  * - Renders a single "home" `<MenuItem>` for the root element itself, then the root's children as a `<TreeMenuMapper>` underneath.
  * - The home link uses `path` as its href (defaulting to `/`). The children's hrefs are computed by appending their `name` to the root's path.
  * - To customise child renderers wrap in `<TreeMenuMapping mapping={…}>` (same context as `<TreeMenu>`).
+ *
+ * @param props The root `tree` element and optional root `path`.
+ * @returns A `<Menu>` with a home link plus the root's children as navigation items.
+ * @example <TreeSidebar tree={tree} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeSidebar/TreeSidebar
  */
 export function TreeSidebar({ tree, path = "/" as AbsolutePath }: TreeSidebarProps): ReactNode {
 	return (

package/ui/util/context.d.ts

@@ -1,6 +1,18 @@
 import { type Context } from "react";
 import type { AnyCaller } from "../../util/function.js";
-/** Use the value of a React `Context`, or throw `RequiredError` if the context was unset. */
+/**
+ * Use the value of a React `Context`, or throw `RequiredError` if the context was unset.
+ *
+ * - Reads the context with React's `use()`, so it must be called inside a component or hook.
+ * - Treats both `null` and `undefined` as "unset" and throws, naming the context's `displayName` in the message.
+ *
+ * @param context The React `Context` to read the current value of.
+ * @param caller Function to attribute the thrown `RequiredError` to (defaults to `requireContext`).
+ * @returns The current context value, guaranteed non-nullish.
+ * @throws RequiredError If the context value is `null` or `undefined` (i.e. used outside its provider).
+ * @example const theme = requireContext(ThemeContext);
+ * @see https://dhoulb.github.io/shelving/ui/util/context/requireContext
+ */
 export declare function requireContext<T>(context: Context<T | null>, caller?: AnyCaller): T;
 export declare function requireContext<T>(context: Context<T | undefined>, caller?: AnyCaller): T;
 export declare function requireContext<T>(context: Context<T>, caller?: AnyCaller): T;

package/ui/util/context.ts

@@ -3,7 +3,19 @@ import { RequiredError } from "../../error/RequiredError.js";
 import type { AnyCaller } from "../../util/function.js";
 import { type Nullish, notNullish } from "../../util/null.js";
 
-/** Use the value of a React `Context`, or throw `RequiredError` if the context was unset. */
+/**
+ * Use the value of a React `Context`, or throw `RequiredError` if the context was unset.
+ *
+ * - Reads the context with React's `use()`, so it must be called inside a component or hook.
+ * - Treats both `null` and `undefined` as "unset" and throws, naming the context's `displayName` in the message.
+ *
+ * @param context The React `Context` to read the current value of.
+ * @param caller Function to attribute the thrown `RequiredError` to (defaults to `requireContext`).
+ * @returns The current context value, guaranteed non-nullish.
+ * @throws RequiredError If the context value is `null` or `undefined` (i.e. used outside its provider).
+ * @example const theme = requireContext(ThemeContext);
+ * @see https://dhoulb.github.io/shelving/ui/util/context/requireContext
+ */
 export function requireContext<T>(context: Context<T | null>, caller?: AnyCaller): T;
 export function requireContext<T>(context: Context<T | undefined>, caller?: AnyCaller): T;
 export function requireContext<T>(context: Context<T>, caller?: AnyCaller): T;

package/ui/util/css.d.ts

@@ -1,24 +1,33 @@
 import { type ImmutableDictionary } from "../../util/dictionary.js";
 /**
- * Set of classnames that can be joined.
+ * Set of classnames that can be joined into a single `className` string.
  *
  * - `string` — used directly as a classname.
  * - `null` or `undefined` — ignored.
  * - Array of classnames — recursively parsed.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/Classes
  */
 export type Classes = string | null | undefined | readonly Classes[] | Variants;
 /**
- * Variants list is a dictionary of booleans.
+ * Dictionary of boolean variant flags whose `true`-valued keys become class names.
+ *
  * - `true` or `false` item values in dictionaries use the string `key` of the item if the value is `true`, or ignore it if the value is falsy.
  * - Anything that is not `true` has no effect, so other values can be passed in and will be ignored. This means you can pass the entire `props` into this and it'll work just fine.
  *
  * Typed as `object` (not `Data`/`Record<string, unknown>`) so plain `interface` types are accepted —
  * interfaces lack an implicit string index signature, so they don't satisfy index-signature types.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/Variants
  */
 export interface Variants {
     readonly [key: string]: boolean;
 }
-/** CSS modules mapping of local class names to hashed runtime class names. */
+/**
+ * CSS modules mapping of local class names to hashed runtime class names.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/CSSModule
+ */
 export type CSSModule = ImmutableDictionary<string | undefined>;
 /**
  * Parse a list of possible `className` strings and join them into a single string.
@@ -26,6 +35,8 @@ export type CSSModule = ImmutableDictionary<string | undefined>;
  *
  * @param classes The input set of classes to merge.
  * @returns The merged string classname.
+ * @example getClass("button", { active: true, disabled: false }) // "button active"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getClass
  */
 export declare function getClass(...classes: unknown[]): string;
 /**
@@ -37,6 +48,8 @@ export declare function getClass(...classes: unknown[]): string;
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname.
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @example getModuleClass(styles, "base", { active: true }) // "base_x7q active_p2k"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getModuleClass
  */
 export declare function getModuleClass(module: CSSModule | string, ...classes: unknown[]): string | undefined;

package/ui/util/css.js

@@ -6,6 +6,8 @@ import { getDictionaryItems, isDictionary } from "../../util/dictionary.js";
  *
  * @param classes The input set of classes to merge.
  * @returns The merged string classname.
+ * @example getClass("button", { active: true, disabled: false }) // "button active"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getClass
  */
 export function getClass(...classes) {
     return Array.from(getClasses(classes)).join(" ");
@@ -41,7 +43,9 @@ function* getClasses(classes) {
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname.
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @example getModuleClass(styles, "base", { active: true }) // "base_x7q active_p2k"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getModuleClass
  */
 export function getModuleClass(module, ...classes) {
     if (isDictionary(module))

package/ui/util/css.ts

@@ -2,27 +2,36 @@ import { isArray } from "../../util/array.js";
 import { getDictionaryItems, type ImmutableDictionary, isDictionary } from "../../util/dictionary.js";
 
 /**
- * Set of classnames that can be joined.
+ * Set of classnames that can be joined into a single `className` string.
  *
  * - `string` — used directly as a classname.
  * - `null` or `undefined` — ignored.
  * - Array of classnames — recursively parsed.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/Classes
  */
 export type Classes = string | null | undefined | readonly Classes[] | Variants;
 
 /**
- * Variants list is a dictionary of booleans.
+ * Dictionary of boolean variant flags whose `true`-valued keys become class names.
+ *
  * - `true` or `false` item values in dictionaries use the string `key` of the item if the value is `true`, or ignore it if the value is falsy.
  * - Anything that is not `true` has no effect, so other values can be passed in and will be ignored. This means you can pass the entire `props` into this and it'll work just fine.
  *
  * Typed as `object` (not `Data`/`Record<string, unknown>`) so plain `interface` types are accepted —
  * interfaces lack an implicit string index signature, so they don't satisfy index-signature types.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/Variants
  */
 export interface Variants {
 	readonly [key: string]: boolean;
 }
 
-/** CSS modules mapping of local class names to hashed runtime class names. */
+/**
+ * CSS modules mapping of local class names to hashed runtime class names.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/util/css/CSSModule
+ */
 export type CSSModule = ImmutableDictionary<string | undefined>;
 
 /**
@@ -31,6 +40,8 @@ export type CSSModule = ImmutableDictionary<string | undefined>;
  *
  * @param classes The input set of classes to merge.
  * @returns The merged string classname.
+ * @example getClass("button", { active: true, disabled: false }) // "button active"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getClass
  */
 export function getClass(...classes: unknown[]): string {
 	return Array.from(getClasses(classes)).join(" ");
@@ -67,7 +78,9 @@ function* getClasses(classes: unknown): Iterable<string> {
  * - This allows this situation to be handled gracefully and classes will be silently ignored in this environment.
  *
  * @param classes Class keys/values to merge.
- * @returns The merged string classname.
+ * @returns The merged string classname, or `undefined` when `module` is a string (unprocessed CSS module).
+ * @example getModuleClass(styles, "base", { active: true }) // "base_x7q active_p2k"
+ * @see https://dhoulb.github.io/shelving/ui/util/css/getModuleClass
  */
 export function getModuleClass(module: CSSModule | string, ...classes: unknown[]): string | undefined {
 	if (isDictionary(module)) return Array.from(getModuleClasses(module, classes)).join(" ");

package/ui/util/event.d.ts

@@ -1,2 +1,10 @@
-/** Call `event.preventDefault()` on an event. */
+/**
+ * Call `event.preventDefault()` on an event.
+ *
+ * - Handy as a ready-made event handler, e.g. `onSubmit={eventPreventDefault}`.
+ *
+ * @param e The event to suppress the default action of.
+ * @example <form onSubmit={eventPreventDefault}>…</form>
+ * @see https://dhoulb.github.io/shelving/ui/util/event/eventPreventDefault
+ */
 export declare function eventPreventDefault(e: Pick<Event, "preventDefault">): void;

package/ui/util/event.js

@@ -1,4 +1,12 @@
-/** Call `event.preventDefault()` on an event. */
+/**
+ * Call `event.preventDefault()` on an event.
+ *
+ * - Handy as a ready-made event handler, e.g. `onSubmit={eventPreventDefault}`.
+ *
+ * @param e The event to suppress the default action of.
+ * @example <form onSubmit={eventPreventDefault}>…</form>
+ * @see https://dhoulb.github.io/shelving/ui/util/event/eventPreventDefault
+ */
 export function eventPreventDefault(e) {
     e.preventDefault();
 }

package/ui/util/event.ts

@@ -1,4 +1,12 @@
-/** Call `event.preventDefault()` on an event. */
+/**
+ * Call `event.preventDefault()` on an event.
+ *
+ * - Handy as a ready-made event handler, e.g. `onSubmit={eventPreventDefault}`.
+ *
+ * @param e The event to suppress the default action of.
+ * @example <form onSubmit={eventPreventDefault}>…</form>
+ * @see https://dhoulb.github.io/shelving/ui/util/event/eventPreventDefault
+ */
 export function eventPreventDefault(e: Pick<Event, "preventDefault">) {
 	e.preventDefault();
 }

package/ui/util/focus.d.ts

@@ -1,14 +1,33 @@
 import type { Nullish } from "../../util/null.js";
-/** Focus on the first focusable element inside an element. */
+/**
+ * Focus on the first focusable element inside an element.
+ *
+ * - No-op for nullish input or non-`HTMLElement` nodes, and when the element contains nothing focusable.
+ *
+ * @param el The container element to focus the first focusable descendant of.
+ * @example focusFirstFocusable(dialogRef.current);
+ * @see https://dhoulb.github.io/shelving/ui/util/focus/focusFirstFocusable
+ */
 export declare function focusFirstFocusable(el: Nullish<Element>): void;
 /**
- * Loop focus inside an element.
- * - Attempts to blur outside the `from` element refocus back on the first focusable element inside the element.
+ * Loop focus inside an element so it can't escape — refocus the first focusable child when focus moves out.
+ *
+ * - When `nextTarget` falls outside `element`, focus is pulled back to the first focusable element inside it (a simple focus trap).
+ *
+ * @param element The container to keep focus within.
+ * @param nextTarget The element focus is moving to.
+ * @example loopFocus(dialog, document.activeElement);
+ * @see https://dhoulb.github.io/shelving/ui/util/focus/loopFocus
  */
 export declare function loopFocus(element: Nullish<Element>, nextTarget: Nullish<Element>): void;
 /**
- * Loop focus inside an element in response to a `blur` event.
- * - Attempts to blur outside the `currentTarget` element refocus back on the first focusable element inside the element.
+ * Loop focus inside an element in response to a `blur` event — a ready-made `onBlur` handler that traps focus.
+ *
+ * - Pulls focus back to the first focusable child when it blurs outside the event's `currentTarget`.
+ *
+ * @param event The `blur` event, providing `currentTarget` (the container) and `relatedTarget` (the new focus target).
+ * @example <div onBlur={eventLoopFocus}>…</div>
+ * @see https://dhoulb.github.io/shelving/ui/util/focus/eventLoopFocus
  */
 export declare function eventLoopFocus({ currentTarget, relatedTarget }: {
     currentTarget: Element;