shelving 1.236.0 → 1.236.2

package/ui/transition/util.tsx

@@ -2,12 +2,12 @@
 import { addTransitionType } from "react";
 
 /**
- * List of known view transitions in `{ type: className }` format.
+ * Map of view-transition types to their CSS class names in `{ type: className }` format.
  *
- * @param type A "transition type" set with the React `addTransitionType()` API inside a `startTransition()` callback, e.g. "forward"
+ * - Each key is a "transition type" set with the React `addTransitionType()` API inside a `startTransition()` callback, e.g. `"forward"`.
+ * - Each value is a "transition class" that React sets on the element as its `view-transition-class: forward;` CSS property — should correspond to a `::view-transition-old(.slideForward)` rule.
  *
- * @param class A "transition class" that gets set by React on the element as its `view-transition-class: forward;` CSS property.
- * - Should correspond to a `::view-transition-old(.slideForward)`
+ * @see https://dhoulb.github.io/shelving/ui/transition/util/TransitionClasses
  */
 export type TransitionClasses = {
 	default: string;
@@ -15,10 +15,20 @@ export type TransitionClasses = {
 	back?: string;
 };
 
-/** List of known view transition types all of view transitions support. */
+/**
+ * Known view-transition type names that all transitions support — the keys of `TransitionClasses`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/transition/util/TransitionType
+ */
 export type TransitionType = keyof TransitionClasses;
 
-/** Type-safe passthrough for the React `addTransitionType()` that checks `type` is one of our known view transition types. */
+/**
+ * Type-safe passthrough for React's `addTransitionType()` that checks `type` is one of our known view-transition types.
+ *
+ * @param type The transition type to activate, constrained to a known `TransitionType`.
+ * @example setTransitionType("forward")
+ * @see https://dhoulb.github.io/shelving/ui/transition/util/setTransitionType
+ */
 export function setTransitionType(type: TransitionType): void {
 	addTransitionType(type);
 }

package/ui/tree/TreeApp.d.ts

@@ -2,6 +2,11 @@ import type { ReactElement } from "react";
 import type { TreeElement } from "../../util/index.js";
 import type { Routes } from "../router/Routes.js";
 import type { PossibleMeta } from "../util/index.js";
+/**
+ * Props for the `TreeApp` component — the tree to render plus optional extra routes and app meta.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeAppProps
+ */
 export interface TreeAppProps extends PossibleMeta {
     /** The tree elements to display. */
     tree: TreeElement;
@@ -12,10 +17,16 @@ export interface TreeAppProps extends PossibleMeta {
 }
 /**
  * Top-level app component for a tree-based documentation site.
+ *
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
+ *
+ * @param props The `tree` to render, optional extra `routes`, and app meta.
+ * @returns The configured `<App>` element with sidebar layout and tree routing.
+ * @example <TreeApp tree={tree} title="Docs" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeApp
  */
 export declare function TreeApp({ tree, routes: extraRoutes, ...meta }: TreeAppProps): ReactElement;

package/ui/tree/TreeApp.js

@@ -6,11 +6,17 @@ import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 /**
  * Top-level app component for a tree-based documentation site.
+ *
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
+ *
+ * @param props The `tree` to render, optional extra `routes`, and app meta.
+ * @returns The configured `<App>` element with sidebar layout and tree routing.
+ * @example <TreeApp tree={tree} title="Docs" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeApp
  */
 export function TreeApp({ tree, routes: extraRoutes, ...meta }) {
     return (_jsx(App, { ...meta, children: _jsx(PageCatcher, { children: _jsx(SidebarLayout, { sidebar: _jsx(TreeSidebar, { tree: tree }), children: _jsx(TreeRouter, { tree: tree }) }) }) }));

package/ui/tree/TreeApp.tsx

@@ -8,6 +8,11 @@ import type { PossibleMeta } from "../util/index.js";
 import { TreeRouter } from "./TreeRouter.js";
 import { TreeSidebar } from "./TreeSidebar.js";
 
+/**
+ * Props for the `TreeApp` component — the tree to render plus optional extra routes and app meta.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeAppProps
+ */
 export interface TreeAppProps extends PossibleMeta {
 	/** The tree elements to display. */
 	tree: TreeElement;
@@ -19,11 +24,17 @@ export interface TreeAppProps extends PossibleMeta {
 
 /**
  * Top-level app component for a tree-based documentation site.
+ *
  * - Wraps `<App>` with error catching and a sidebar layout.
  * - The sidebar shows a `<TreeSidebar>` (root as a home link + a menu of its children).
  * - `/` renders the root via `<TreePage>`; `/**` catches every deeper path and feeds the full sub-path into `<TreePage>`.
  * - Element rendering uses the default mappings on `<TreePage>`, `<TreeMenu>`, `<TreeCards>`.
  *   Override by wrapping with `<TreePageMapping>`, `<TreeMenuMapping>`, or `<TreeCardMapping>`.
+ *
+ * @param props The `tree` to render, optional extra `routes`, and app meta.
+ * @returns The configured `<App>` element with sidebar layout and tree routing.
+ * @example <TreeApp tree={tree} title="Docs" />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeApp/TreeApp
  */
 export function TreeApp({ tree, routes: extraRoutes, ...meta }: TreeAppProps): ReactElement {
 	return (

package/ui/tree/TreeBreadcrumbs.d.ts

@@ -2,14 +2,25 @@ import { type ReactElement } from "react";
 import { type FlexVariants } from "../style/Flex.js";
 import { type SpaceVariants } from "../style/Space.js";
 import { type TypographyVariants } from "../style/Typography.js";
+/**
+ * Props for the `TreeBreadcrumbs` component — typography, space, and flex variant props.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeBreadcrumbs/TreeBreadcrumbsProps
+ */
 export interface TreeBreadcrumbsProps extends TypographyVariants, SpaceVariants, FlexVariants {
 }
 /**
  * Breadcrumb trail of links to a tree page's ancestors, separated by `›` arrow icons.
+ *
  * - Built from the page's own `path`: each ancestor prefix is looked up in the tree map for its title, and links to its cumulative path.
  * - Prefixes with no entry (e.g. the partial half of a `"util/string"` module name) are skipped, so composite names collapse to a single crumb.
  * - The current item is deliberately omitted — the page `<Title>` already names it.
  * - Block spacing defaults to section spacing (via `BLOCK_CLASS`); pass `space` to override.
  * - Renders nothing at the tree root (no ancestors) or when there's no `<TreeProvider>` to resolve labels from.
+ *
+ * @param props Typography, space, and flex variant props.
+ * @returns A `<nav>` of breadcrumb links, or `null` at the tree root.
+ * @example <TreeBreadcrumbs />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeBreadcrumbs/TreeBreadcrumbs
  */
 export declare function TreeBreadcrumbs({ tint, left, wrap, ...variants }: TreeBreadcrumbsProps): ReactElement | null;

package/ui/tree/TreeBreadcrumbs.js

@@ -12,11 +12,17 @@ import { TreeButton } from "./TreeButton.js";
 import { useTreeMap } from "./TreeContext.js";
 /**
  * Breadcrumb trail of links to a tree page's ancestors, separated by `›` arrow icons.
+ *
  * - Built from the page's own `path`: each ancestor prefix is looked up in the tree map for its title, and links to its cumulative path.
  * - Prefixes with no entry (e.g. the partial half of a `"util/string"` module name) are skipped, so composite names collapse to a single crumb.
  * - The current item is deliberately omitted — the page `<Title>` already names it.
  * - Block spacing defaults to section spacing (via `BLOCK_CLASS`); pass `space` to override.
  * - Renders nothing at the tree root (no ancestors) or when there's no `<TreeProvider>` to resolve labels from.
+ *
+ * @param props Typography, space, and flex variant props.
+ * @returns A `<nav>` of breadcrumb links, or `null` at the tree root.
+ * @example <TreeBreadcrumbs />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeBreadcrumbs/TreeBreadcrumbs
  */
 export function TreeBreadcrumbs({ tint = "70", left = true, wrap = true, ...variants }) {
     const map = useTreeMap();

package/ui/tree/TreeBreadcrumbs.tsx

@@ -10,15 +10,26 @@ import { getClass } from "../util/css.js";
 import { TreeButton } from "./TreeButton.js";
 import { useTreeMap } from "./TreeContext.js";
 
+/**
+ * Props for the `TreeBreadcrumbs` component — typography, space, and flex variant props.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeBreadcrumbs/TreeBreadcrumbsProps
+ */
 export interface TreeBreadcrumbsProps extends TypographyVariants, SpaceVariants, FlexVariants {}
 
 /**
  * Breadcrumb trail of links to a tree page's ancestors, separated by `›` arrow icons.
+ *
  * - Built from the page's own `path`: each ancestor prefix is looked up in the tree map for its title, and links to its cumulative path.
  * - Prefixes with no entry (e.g. the partial half of a `"util/string"` module name) are skipped, so composite names collapse to a single crumb.
  * - The current item is deliberately omitted — the page `<Title>` already names it.
  * - Block spacing defaults to section spacing (via `BLOCK_CLASS`); pass `space` to override.
  * - Renders nothing at the tree root (no ancestors) or when there's no `<TreeProvider>` to resolve labels from.
+ *
+ * @param props Typography, space, and flex variant props.
+ * @returns A `<nav>` of breadcrumb links, or `null` at the tree root.
+ * @example <TreeBreadcrumbs />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeBreadcrumbs/TreeBreadcrumbs
  */
 export function TreeBreadcrumbs({ tint = "70", left = true, wrap = true, ...variants }: TreeBreadcrumbsProps): ReactElement | null {
 	const map = useTreeMap();

package/ui/tree/TreeButton.d.ts

@@ -1,6 +1,10 @@
 import type { ReactElement, ReactNode } from "react";
 import { type ButtonVariants } from "../form/Button.js";
-/** Props for `TreeButton`. */
+/**
+ * Props for the `TreeButton` component — the element reference plus button variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButtonProps
+ */
 export interface TreeButtonProps extends ButtonVariants {
     /** Reference to an element in the tree — a flat key (`"Store"`, `"Store.get"`) or a canonical path (`"/schema/BooleanSchema"`). */
     readonly name: string;
@@ -9,10 +13,14 @@ export interface TreeButtonProps extends ButtonVariants {
 }
 /**
  * Small button linking to a specific tree element, resolved by reference string.
+ *
  * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
  * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
+ * @param props The element reference `name`, optional `children` label, and button variants.
+ * @returns A `<Button>` element linking to the resolved element, or a plain label on a miss.
  * @example <TreeButton name="Store.get">Store.get()</TreeButton>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButton
  */
 export declare function TreeButton({ name, children, small, plain, ...variants }: TreeButtonProps): ReactElement;

package/ui/tree/TreeButton.js

@@ -3,11 +3,15 @@ import { Button } from "../form/Button.js";
 import { useTreeMap } from "./TreeContext.js";
 /**
  * Small button linking to a specific tree element, resolved by reference string.
+ *
  * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
  * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
+ * @param props The element reference `name`, optional `children` label, and button variants.
+ * @returns A `<Button>` element linking to the resolved element, or a plain label on a miss.
  * @example <TreeButton name="Store.get">Store.get()</TreeButton>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButton
  */
 export function TreeButton({ name, children, small = true, plain = true, ...variants }) {
     const element = useTreeMap().get(name);

package/ui/tree/TreeButton.tsx

@@ -2,7 +2,11 @@ import type { ReactElement, ReactNode } from "react";
 import { Button, type ButtonVariants } from "../form/Button.js";
 import { useTreeMap } from "./TreeContext.js";
 
-/** Props for `TreeButton`. */
+/**
+ * Props for the `TreeButton` component — the element reference plus button variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButtonProps
+ */
 export interface TreeButtonProps extends ButtonVariants {
 	/** Reference to an element in the tree — a flat key (`"Store"`, `"Store.get"`) or a canonical path (`"/schema/BooleanSchema"`). */
 	readonly name: string;
@@ -12,11 +16,15 @@ export interface TreeButtonProps extends ButtonVariants {
 
 /**
  * Small button linking to a specific tree element, resolved by reference string.
+ *
  * - Looks `name` up in the flattened tree map (`useTreeMap()`) — by flat key (`"Store"`, `"Store.get"`) or canonical path (`"/schema/BooleanSchema"`) — and links to the element's canonical `path`.
  * - A hit becomes an `<a>` link; a miss (e.g. a builtin like `Serializable`) stays a plain non-link label so it still reads as text.
  * - Defaults to `small plain` styling; pass other `ButtonVariants` to override.
  *
+ * @param props The element reference `name`, optional `children` label, and button variants.
+ * @returns A `<Button>` element linking to the resolved element, or a plain label on a miss.
  * @example <TreeButton name="Store.get">Store.get()</TreeButton>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeButton/TreeButton
  */
 export function TreeButton({ name, children, small = true, plain = true, ...variants }: TreeButtonProps): ReactElement {
 	const element = useTreeMap().get(name);

package/ui/tree/TreeCard.d.ts

@@ -1,4 +1,11 @@
 import type { ReactNode } from "react";
 import type { TreeElementProps } from "../../util/tree.js";
-/** Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description. */
+/**
+ * Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description.
+ *
+ * @param props The tree element props (`path`, `name`, `title`, `description`).
+ * @returns A `<Card>` linking to the element's canonical `path`.
+ * @example <TreeCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCard/TreeCard
+ */
 export declare function TreeCard({ path, name, title, description }: TreeElementProps): ReactNode;

package/ui/tree/TreeCard.js

@@ -2,7 +2,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Card } from "../block/Card.js";
 import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
-/** Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description. */
+/**
+ * Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description.
+ *
+ * @param props The tree element props (`path`, `name`, `title`, `description`).
+ * @returns A `<Card>` linking to the element's canonical `path`.
+ * @example <TreeCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCard/TreeCard
+ */
 export function TreeCard({ path, name, title, description }) {
     // `path` is the element's own canonical URL, stamped by `flattenTree()` — link straight to it.
     return (_jsxs(Card, { href: path, children: [_jsx(Subheading, { children: title ?? name }), description && _jsx(Paragraph, { children: description })] }));

package/ui/tree/TreeCard.tsx

@@ -4,7 +4,14 @@ import { Card } from "../block/Card.js";
 import { Paragraph } from "../block/Paragraph.js";
 import { Subheading } from "../block/Subheading.js";
 
-/** Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description. */
+/**
+ * Card renderer for a generic `tree-element` (a directory or file) — a summary card showing the heading and description.
+ *
+ * @param props The tree element props (`path`, `name`, `title`, `description`).
+ * @returns A `<Card>` linking to the element's canonical `path`.
+ * @example <TreeCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCard/TreeCard
+ */
 export function TreeCard({ path, name, title, description }: TreeElementProps): ReactNode {
 	// `path` is the element's own canonical URL, stamped by `flattenTree()` — link straight to it.
 	return (

package/ui/tree/TreeCards.d.ts

@@ -1,16 +1,31 @@
 import type { ReactNode } from "react";
 import type { TreeElements } from "../../util/tree.js";
-/** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override the per-type card renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCardMapping
+ */
 export declare const TreeCardMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<unknown>>, TreeCardMapper: import("react").FunctionComponent<{
     readonly children?: import("../../util/element.js").Elements;
 }>;
+/**
+ * Props for the `TreeCards` component — the tree elements to render as cards.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCardsProps
+ */
 export interface TreeCardsProps {
     /** The children to render as cards. */
     readonly children?: TreeElements;
 }
 /**
  * Render a list of tree elements as a stack of cards.
+ *
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer; each card links to its own stamped `path`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
+ *
+ * @param props The tree elements to render as `children`.
+ * @returns A `<TreeCardMapper>` rendering each element as a card.
+ * @example <TreeCards>{element.props.children}</TreeCards>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCards
  */
 export declare function TreeCards({ children }: TreeCardsProps): ReactNode;

package/ui/tree/TreeCards.js

@@ -3,15 +3,25 @@ import { walkElements } from "../../util/element.js";
 import { DocumentationCard } from "../docs/DocumentationCard.js";
 import { createMapper } from "../misc/Mapper.js";
 import { TreeCard } from "./TreeCard.js";
-/** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override the per-type card renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCardMapping
+ */
 export const [TreeCardMapping, TreeCardMapper] = createMapper({
     "tree-element": TreeCard,
     "tree-documentation": DocumentationCard,
 });
 /**
  * Render a list of tree elements as a stack of cards.
+ *
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer; each card links to its own stamped `path`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
+ *
+ * @param props The tree elements to render as `children`.
+ * @returns A `<TreeCardMapper>` rendering each element as a card.
+ * @example <TreeCards>{element.props.children}</TreeCards>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCards
  */
 export function TreeCards({ children }) {
     return _jsx(TreeCardMapper, { children: walkElements(children) });

package/ui/tree/TreeCards.tsx

@@ -5,12 +5,21 @@ import { DocumentationCard } from "../docs/DocumentationCard.js";
 import { createMapper } from "../misc/Mapper.js";
 import { TreeCard } from "./TreeCard.js";
 
-/** Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override. */
+/**
+ * Mapping + Mapper pair for tree cards — wrap children in `<TreeCardMapping>` to override the per-type card renderers.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCardMapping
+ */
 export const [TreeCardMapping, TreeCardMapper] = createMapper({
 	"tree-element": TreeCard,
 	"tree-documentation": DocumentationCard,
 });
 
+/**
+ * Props for the `TreeCards` component — the tree elements to render as cards.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCardsProps
+ */
 export interface TreeCardsProps {
 	/** The children to render as cards. */
 	readonly children?: TreeElements;
@@ -18,8 +27,14 @@ export interface TreeCardsProps {
 
 /**
  * Render a list of tree elements as a stack of cards.
+ *
  * - Each element is dispatched via `<TreeCardMapper>` to its registered renderer; each card links to its own stamped `path`.
  * - To override the renderer for a specific element type, wrap in `<TreeCardMapping mapping={…}>`.
+ *
+ * @param props The tree elements to render as `children`.
+ * @returns A `<TreeCardMapper>` rendering each element as a card.
+ * @example <TreeCards>{element.props.children}</TreeCards>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeCards/TreeCards
  */
 export function TreeCards({ children }: TreeCardsProps): ReactNode {
 	return <TreeCardMapper>{walkElements(children)}</TreeCardMapper>;

package/ui/tree/TreeContext.d.ts

@@ -1,11 +1,23 @@
 import { type ReactNode } from "react";
 import { type TreeElement } from "../../util/tree.js";
-/** A flattened `key` → `element` map of the surrounding tree(s) — keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) — for fast cross-reference lookup. */
+/**
+ * React context holding a flattened `key` → `element` map of the surrounding tree(s).
+ *
+ * - Keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) for fast cross-reference lookup.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeContext
+ */
 export declare const TreeContext: import("react").Context<ReadonlyMap<string, TreeElement<import("../../util/tree.js").TreeElementProps>>>;
 /**
  * Provide a tree to descendants as a flattened lookup map (see `flattenTree()`).
+ *
  * - Flattens `tree` **once** (memoised) when set — not on every lookup in every element.
  * - Merges onto any parent `<TreeProvider>`'s map, so cross-references resolve across an entire nested set of trees; the outer (parent) tree wins on collision.
+ *
+ * @param props The `tree` to flatten and provide, plus `children`.
+ * @returns A `<TreeContext>` provider wrapping the children with the flattened map.
+ * @example <TreeProvider tree={tree}>{children}</TreeProvider>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeProvider
  */
 export declare function TreeProvider({ tree, children }: {
     readonly tree: TreeElement;
@@ -13,6 +25,11 @@ export declare function TreeProvider({ tree, children }: {
 }): ReactNode;
 /**
  * Use the flattened tree lookup map from context.
+ *
  * - Returns an empty map when there's no `<TreeProvider>` above (e.g. an isolated card rendered outside the tree shell), so callers can look up freely and fall back to plain text on a miss.
+ *
+ * @returns The flattened `key` → `element` map, or an empty map when no `<TreeProvider>` is present.
+ * @example const element = useTreeMap().get("Store.get");
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/useTreeMap
  */
 export declare function useTreeMap(): ReadonlyMap<string, TreeElement>;

package/ui/tree/TreeContext.js

@@ -1,13 +1,25 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, use, useMemo } from "react";
 import { flattenTree } from "../../util/tree.js";
-/** A flattened `key` → `element` map of the surrounding tree(s) — keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) — for fast cross-reference lookup. */
+/**
+ * React context holding a flattened `key` → `element` map of the surrounding tree(s).
+ *
+ * - Keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) for fast cross-reference lookup.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeContext
+ */
 export const TreeContext = createContext(new Map());
 TreeContext.displayName = "TreeContext";
 /**
  * Provide a tree to descendants as a flattened lookup map (see `flattenTree()`).
+ *
  * - Flattens `tree` **once** (memoised) when set — not on every lookup in every element.
  * - Merges onto any parent `<TreeProvider>`'s map, so cross-references resolve across an entire nested set of trees; the outer (parent) tree wins on collision.
+ *
+ * @param props The `tree` to flatten and provide, plus `children`.
+ * @returns A `<TreeContext>` provider wrapping the children with the flattened map.
+ * @example <TreeProvider tree={tree}>{children}</TreeProvider>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeProvider
  */
 export function TreeProvider({ tree, children }) {
     const parent = use(TreeContext);
@@ -16,7 +28,12 @@ export function TreeProvider({ tree, children }) {
 }
 /**
  * Use the flattened tree lookup map from context.
+ *
  * - Returns an empty map when there's no `<TreeProvider>` above (e.g. an isolated card rendered outside the tree shell), so callers can look up freely and fall back to plain text on a miss.
+ *
+ * @returns The flattened `key` → `element` map, or an empty map when no `<TreeProvider>` is present.
+ * @example const element = useTreeMap().get("Store.get");
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/useTreeMap
  */
 export function useTreeMap() {
     return use(TreeContext);

package/ui/tree/TreeContext.tsx

@@ -1,14 +1,26 @@
 import { createContext, type ReactNode, use, useMemo } from "react";
 import { flattenTree, type TreeElement } from "../../util/tree.js";
 
-/** A flattened `key` → `element` map of the surrounding tree(s) — keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) — for fast cross-reference lookup. */
+/**
+ * React context holding a flattened `key` → `element` map of the surrounding tree(s).
+ *
+ * - Keyed by flat name (`"BooleanSchema"`, `"Class.member"`) and canonical path (`"/schema/BooleanSchema"`) for fast cross-reference lookup.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeContext
+ */
 export const TreeContext = createContext<ReadonlyMap<string, TreeElement>>(new Map());
 TreeContext.displayName = "TreeContext";
 
 /**
  * Provide a tree to descendants as a flattened lookup map (see `flattenTree()`).
+ *
  * - Flattens `tree` **once** (memoised) when set — not on every lookup in every element.
  * - Merges onto any parent `<TreeProvider>`'s map, so cross-references resolve across an entire nested set of trees; the outer (parent) tree wins on collision.
+ *
+ * @param props The `tree` to flatten and provide, plus `children`.
+ * @returns A `<TreeContext>` provider wrapping the children with the flattened map.
+ * @example <TreeProvider tree={tree}>{children}</TreeProvider>
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/TreeProvider
  */
 export function TreeProvider({ tree, children }: { readonly tree: TreeElement; readonly children: ReactNode }): ReactNode {
 	const parent = use(TreeContext);
@@ -18,7 +30,12 @@ export function TreeProvider({ tree, children }: { readonly tree: TreeElement; r
 
 /**
  * Use the flattened tree lookup map from context.
+ *
  * - Returns an empty map when there's no `<TreeProvider>` above (e.g. an isolated card rendered outside the tree shell), so callers can look up freely and fall back to plain text on a miss.
+ *
+ * @returns The flattened `key` → `element` map, or an empty map when no `<TreeProvider>` is present.
+ * @example const element = useTreeMap().get("Store.get");
+ * @see https://dhoulb.github.io/shelving/ui/tree/TreeContext/useTreeMap
  */
 export function useTreeMap(): ReadonlyMap<string, TreeElement> {
 	return use(TreeContext);

package/ui/tree/TreeMenu.d.ts

@@ -4,8 +4,14 @@ import { type AbsolutePath } from "../../util/path.js";
 import type { TreeElement, TreeElementProps } from "../../util/tree.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 declare function matchMenuElement(element: Element): boolean;
 /** Extras threaded through `TreeMenuMapper` to every menu item — the parent's URL path. */
@@ -15,12 +21,27 @@ 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 declare function TreeMenuItem({ path, name, title, children }: TreeElementProps & TreeMenuExtras): ReactNode;
-/** 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 declare const TreeMenuMapping: import("react").FunctionComponent<import("../misc/Mapper.js").MappingProps<TreeMenuExtras>>, TreeMenuMapper: import("react").FunctionComponent<import("../misc/Mapper.js").MapperProps<TreeMenuExtras>>;
+/**
+ * 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;
@@ -29,9 +50,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 declare function TreeMenu({ path, tree }: TreeMenuProps): ReactNode;
 export {};