shelving 1.236.0 → 1.236.2

package/ui/layout/CenteredLayout.tsx

@@ -5,13 +5,24 @@ import type { OptionalChildProps } from "../util/props.js";
 import CENTERED_LAYOUT_CSS from "./CenteredLayout.module.css";
 import { LAYOUT_CLASS } from "./Layout.js";
 
+/**
+ * Props for `<CenteredLayout>` — optional `children` and a `fullWidth` flag to drop the max-width.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/layout/CenteredLayout/CenteredLayoutProps
+ */
 export interface CenteredLayoutProps extends OptionalChildProps {
 	fullWidth?: boolean;
 }
 
 /**
- * Layout that puts the content in the center of the screen with no header/footer and a narrow max-width.
+ * Layout that centres its content with no header/footer and a narrow max-width.
  * - Used for e.g. login/register/error/form pages where the content is the only focus.
+ *
+ * @param children The content to centre.
+ * @param fullWidth Drop the narrow max-width and let content fill the width (defaults to `false`).
+ * @returns The centred layout element.
+ * @example <CenteredLayout><LoginForm /></CenteredLayout>
+ * @see https://dhoulb.github.io/shelving/ui/layout/CenteredLayout/CenteredLayout
  */
 export function CenteredLayout({ children, fullWidth = false }: CenteredLayoutProps): ReactElement {
 	const { path } = requireMetaURL();

package/ui/layout/Layout.d.ts

@@ -1,9 +1,18 @@
-/** Resolved `.layout` class — for components that want to compose the layout's padding/scroll/safe-area behaviour onto their own element (e.g. `CenteredLayout`). */
+/**
+ * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
+ *
+ * @example <main className={LAYOUT_CLASS}>…</main>
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
+ */
 export declare const LAYOUT_CLASS: string | undefined;
 /**
- * Adapt the property to the dynamic height of the view port when the keyboard pops up.
- * - This dynamically updates the value we use as the "safe area"
+ * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
+ *
+ * - Writes a `--layout-inset-bottom` custom property reflecting the space hidden behind the keyboard.
  *
+ * @returns A cleanup function that removes the listeners and property, or `undefined` when `visualViewport` is unavailable.
  * @todo This can be removed once Safari iOS supports interactive-widget viewport property. https://caniuse.com/mdn-html_elements_meta_name_viewport_interactive-widget
+ * @example useEffect(useSafeKeyboardArea, []);
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/useSafeKeyboardArea
  */
 export declare function useSafeKeyboardArea(): (() => void) | undefined;

package/ui/layout/Layout.js

@@ -1,12 +1,21 @@
 import { getModuleClass } from "../util/css.js";
 import styles from "./Layout.module.css";
-/** Resolved `.layout` class — for components that want to compose the layout's padding/scroll/safe-area behaviour onto their own element (e.g. `CenteredLayout`). */
+/**
+ * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
+ *
+ * @example <main className={LAYOUT_CLASS}>…</main>
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
+ */
 export const LAYOUT_CLASS = getModuleClass(styles, "layout");
 /**
- * Adapt the property to the dynamic height of the view port when the keyboard pops up.
- * - This dynamically updates the value we use as the "safe area"
+ * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
+ *
+ * - Writes a `--layout-inset-bottom` custom property reflecting the space hidden behind the keyboard.
  *
+ * @returns A cleanup function that removes the listeners and property, or `undefined` when `visualViewport` is unavailable.
  * @todo This can be removed once Safari iOS supports interactive-widget viewport property. https://caniuse.com/mdn-html_elements_meta_name_viewport_interactive-widget
+ * @example useEffect(useSafeKeyboardArea, []);
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/useSafeKeyboardArea
  */
 export function useSafeKeyboardArea() {
     const vv = window.visualViewport;

package/ui/layout/Layout.ts

@@ -1,14 +1,23 @@
 import { getModuleClass } from "../util/css.js";
 import styles from "./Layout.module.css";
 
-/** Resolved `.layout` class — for components that want to compose the layout's padding/scroll/safe-area behaviour onto their own element (e.g. `CenteredLayout`). */
+/**
+ * Resolved `.layout` class for composing the layout's padding/scroll/safe-area behaviour onto a custom element.
+ *
+ * @example <main className={LAYOUT_CLASS}>…</main>
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/LAYOUT_CLASS
+ */
 export const LAYOUT_CLASS = getModuleClass(styles, "layout");
 
 /**
- * Adapt the property to the dynamic height of the view port when the keyboard pops up.
- * - This dynamically updates the value we use as the "safe area"
+ * Track the dynamic viewport height so layout safe-area insets follow the on-screen keyboard.
+ *
+ * - Writes a `--layout-inset-bottom` custom property reflecting the space hidden behind the keyboard.
  *
+ * @returns A cleanup function that removes the listeners and property, or `undefined` when `visualViewport` is unavailable.
  * @todo This can be removed once Safari iOS supports interactive-widget viewport property. https://caniuse.com/mdn-html_elements_meta_name_viewport_interactive-widget
+ * @example useEffect(useSafeKeyboardArea, []);
+ * @see https://dhoulb.github.io/shelving/ui/layout/Layout/useSafeKeyboardArea
  */
 export function useSafeKeyboardArea() {
 	const vv = window.visualViewport;

package/ui/layout/SidebarLayout.d.ts

@@ -1,5 +1,10 @@
 import { type ReactElement, type ReactNode } from "react";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, and a `right` placement flag.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/layout/SidebarLayout/SidebarLayoutProps
+ */
 export interface SidebarLayoutProps extends OptionalChildProps {
     /** Content rendered in the fixed-width side column. */
     sidebar: ReactNode;
@@ -13,5 +18,12 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
+ *
+ * @param sidebar The side-column content, rendered inside a `<nav>`.
+ * @param children The main scrollable content.
+ * @param right Render the sidebar on the right rather than the left (defaults to `false`).
+ * @returns The sidebar layout element.
+ * @example <SidebarLayout sidebar={<Menu />}><Page /></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/layout/SidebarLayout/SidebarLayout
  */
 export declare function SidebarLayout({ sidebar, children, right }: SidebarLayoutProps): ReactElement;

package/ui/layout/SidebarLayout.js

@@ -13,6 +13,13 @@ import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
+ *
+ * @param sidebar The side-column content, rendered inside a `<nav>`.
+ * @param children The main scrollable content.
+ * @param right Render the sidebar on the right rather than the left (defaults to `false`).
+ * @returns The sidebar layout element.
+ * @example <SidebarLayout sidebar={<Menu />}><Page /></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/layout/SidebarLayout/SidebarLayout
  */
 export function SidebarLayout({ sidebar, children, right = false }) {
     const { path } = requireMetaURL();

package/ui/layout/SidebarLayout.tsx

@@ -7,6 +7,11 @@ import type { OptionalChildProps } from "../util/props.js";
 import { LAYOUT_CLASS } from "./Layout.js";
 import SIDEBAR_LAYOUT_CSS from "./SidebarLayout.module.css";
 
+/**
+ * Props for `<SidebarLayout>` — the `sidebar` column content, main `children`, and a `right` placement flag.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/layout/SidebarLayout/SidebarLayoutProps
+ */
 export interface SidebarLayoutProps extends OptionalChildProps {
 	/** Content rendered in the fixed-width side column. */
 	sidebar: ReactNode;
@@ -21,6 +26,13 @@ export interface SidebarLayoutProps extends OptionalChildProps {
  * - While the drawer is open an overlay dims the rest of the page; clicking the overlay closes the drawer.
  * - Inside a `<Navigation>` the drawer closes itself whenever the route changes (e.g. tapping a sidebar link).
  * - Use the `--sidebar-layout-width`, `--sidebar-layout-bg`, `--sidebar-layout-border`, and `--sidebar-layout-color-border` custom properties to override defaults.
+ *
+ * @param sidebar The side-column content, rendered inside a `<nav>`.
+ * @param children The main scrollable content.
+ * @param right Render the sidebar on the right rather than the left (defaults to `false`).
+ * @returns The sidebar layout element.
+ * @example <SidebarLayout sidebar={<Menu />}><Page /></SidebarLayout>
+ * @see https://dhoulb.github.io/shelving/ui/layout/SidebarLayout/SidebarLayout
  */
 export function SidebarLayout({ sidebar, children, right = false }: SidebarLayoutProps): ReactElement {
 	const { path } = requireMetaURL();

package/ui/menu/Menu.d.ts

@@ -1,14 +1,29 @@
 import type { ReactNode } from "react";
 import { type ClickableProps } from "../form/Clickable.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<Menu>` — optional `<MenuItem>` `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuProps
+ */
 export interface MenuProps extends OptionalChildProps {
 }
 /**
  * A `<menu>` list of `<MenuItem>` children.
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
+ *
+ * @param children The `<MenuItem>` entries to list.
+ * @returns The menu element.
+ * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/Menu
  */
 export declare function Menu({ children }: MenuProps): ReactNode;
+/**
+ * Props for `<MenuItem>` — `<Clickable>` props plus `children` whose first node is the label and the rest the submenu.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuItemProps
+ */
 export interface MenuItemProps extends ClickableProps {
     /**
      * The first child becomes the link label (rendered inside the `<a>`).
@@ -20,5 +35,12 @@ export interface MenuItemProps extends ClickableProps {
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
+ *
+ * @param href The link target, used to compute `active`/`proud` against the current URL.
+ * @param children The label (first node) and optional submenu (remaining nodes).
+ * @param props Additional `<Clickable>` props.
+ * @returns The menu item element.
+ * @example <MenuItem href="/settings">Settings</MenuItem>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuItem
  */
 export declare function MenuItem({ href, children, ...props }: MenuItemProps): ReactNode;

package/ui/menu/Menu.js

@@ -14,6 +14,11 @@ const MENU_ACTIVE_CLASS = getModuleClass(MENU_CSS, "active");
  * A `<menu>` list of `<MenuItem>` children.
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
+ *
+ * @param children The `<MenuItem>` entries to list.
+ * @returns The menu element.
+ * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/Menu
  */
 export function Menu({ children }) {
     return _jsx("menu", { className: MENU_CLASS, children: children });
@@ -22,6 +27,13 @@ export function Menu({ children }) {
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
+ *
+ * @param href The link target, used to compute `active`/`proud` against the current URL.
+ * @param children The label (first node) and optional submenu (remaining nodes).
+ * @param props Additional `<Clickable>` props.
+ * @returns The menu item element.
+ * @example <MenuItem href="/settings">Settings</MenuItem>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuItem
  */
 export function MenuItem({ href, children, ...props }) {
     const { url, root } = requireMeta();

package/ui/menu/Menu.tsx

@@ -13,17 +13,32 @@ const MENU_LINK_CLASS = getModuleClass(MENU_CSS, "link");
 const MENU_PROUD_CLASS = getModuleClass(MENU_CSS, "proud");
 const MENU_ACTIVE_CLASS = getModuleClass(MENU_CSS, "active");
 
+/**
+ * Props for `<Menu>` — optional `<MenuItem>` `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuProps
+ */
 export interface MenuProps extends OptionalChildProps {}
 
 /**
  * A `<menu>` list of `<MenuItem>` children.
  * - Renders as a bare `<menu>` element — semantically equivalent to `<ul>` per HTML spec but more meaningful for menu contexts. Place inside a `<nav>` (or use the sidebar-style nav at the layout level) if a navigation landmark is needed.
  * - Nested `<Menu>` instances (typically inside a `<MenuItem>`) get indented via the `.menu .menu` CSS rule.
+ *
+ * @param children The `<MenuItem>` entries to list.
+ * @returns The menu element.
+ * @example <Menu><MenuItem href="/home">Home</MenuItem></Menu>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/Menu
  */
 export function Menu({ children }: MenuProps): ReactNode {
 	return <menu className={MENU_CLASS}>{children}</menu>;
 }
 
+/**
+ * Props for `<MenuItem>` — `<Clickable>` props plus `children` whose first node is the label and the rest the submenu.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuItemProps
+ */
 export interface MenuItemProps extends ClickableProps {
 	/**
 	 * The first child becomes the link label (rendered inside the `<a>`).
@@ -36,6 +51,13 @@ export interface MenuItemProps extends ClickableProps {
  * A `<li>` containing an `<a>` link, plus optional submenu content shown when this item is "proud".
  * - Reads the current page URL from `<Meta>` and computes `active` / `proud` against its own `href`.
  * - Splits `children` into `[label, ...after]`: label goes inside the `<a>`; `after` is rendered as siblings below it, only when proud.
+ *
+ * @param href The link target, used to compute `active`/`proud` against the current URL.
+ * @param children The label (first node) and optional submenu (remaining nodes).
+ * @param props Additional `<Clickable>` props.
+ * @returns The menu item element.
+ * @example <MenuItem href="/settings">Settings</MenuItem>
+ * @see https://dhoulb.github.io/shelving/ui/menu/Menu/MenuItem
  */
 export function MenuItem({ href, children, ...props }: MenuItemProps): ReactNode {
 	const { url, root } = requireMeta();

package/ui/misc/Catcher.d.ts

@@ -2,12 +2,38 @@ import { Component, type ReactElement, type ReactNode } from "react";
 import type { Callback } from "../../util/function.js";
 import { type ButtonVariants } from "../form/Button.js";
 import type { ChildProps, OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<RetryButton>` — `<Button>` variants plus optional `children` to override the default "Retry" label.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/RetryButtonProps
+ */
 export interface RetryButtonProps extends ButtonVariants, OptionalChildProps {
 }
+/**
+ * Button that retries the nearest `<Catcher>` error boundary when clicked.
+ *
+ * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
+ * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
+ *
+ * @param props `<Button>` variants and optional `children` for the label.
+ * @returns The retry button, or `null` when not inside a `<Catcher>`.
+ * @example <RetryButton small />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/RetryButton
+ */
 export declare function RetryButton({ children, ...props }: RetryButtonProps): ReactElement | null;
+/**
+ * Props for a component that renders a caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorComponentProps
+ */
 export interface ErrorComponentProps {
     reason: unknown;
 }
+/**
+ * Props for `<Catcher>` — the `children` to guard plus the `as` component used to render any caught error.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/CatcherProps
+ */
 export interface CatcherProps extends ChildProps {
     /** Component to render an error (defaults to `<ErrorNotice />`) */
     as: (props: ErrorComponentProps) => ReactElement;
@@ -17,8 +43,14 @@ type CatcherState = {
     reason: unknown;
 };
 /**
- * React component that provides an Error Boundary.
- * If an error occurs in any component under this, a general error will be shown to the user.
+ * React error boundary that renders a fallback component when any descendant throws.
+ *
+ * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
+ * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
+ *
+ * @example <Catcher><RiskyComponent /></Catcher>
+ * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher
  */
 export declare class Catcher extends Component<CatcherProps, CatcherState> {
     static defaultProps: Pick<CatcherProps, "as">;
@@ -27,16 +59,56 @@ export declare class Catcher extends Component<CatcherProps, CatcherState> {
     static getDerivedStateFromError(reason: unknown): CatcherState;
     render(): ReactNode;
 }
+/**
+ * Props for `<PageCatcher>` — the page `children` to guard.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/PageCatcherProps
+ */
 export interface PageCatcherProps extends ChildProps {
 }
-/** Catch errors in a page. */
+/**
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
+ *
+ * @param children The page content to guard.
+ * @returns A `<Catcher>` configured to render `<ErrorPage>` on error.
+ * @example <PageCatcher><SettingsPage /></PageCatcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/PageCatcher
+ */
 export declare function PageCatcher({ children }: PageCatcherProps): ReactElement;
+/**
+ * Props for `<ErrorNotice>` — the caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorNoticeProps
+ */
 export interface ErrorNoticeProps extends ErrorComponentProps {
 }
-/** Output a `<Notice>` for an unknown error reason. */
+/**
+ * Render a caught error as an inline `<Notice>` with a retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns An error `<Notice>` containing the message and a `<RetryButton>`.
+ * @example <ErrorNotice reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorNotice
+ */
 export declare function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement;
+/**
+ * Props for `<ErrorPage>` — the caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorPageProps
+ */
 export interface ErrorPageProps extends ErrorComponentProps {
 }
-/** Output a `<Page>` with an error `<Card>` for an unknown error reason. */
+/**
+ * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns A centered error page containing the message and a `<RetryButton>`.
+ * @example <ErrorPage reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorPage
+ */
 export declare function ErrorPage({ reason }: ErrorPageProps): ReactElement;
 export {};

package/ui/misc/Catcher.js

@@ -13,6 +13,17 @@ import { StatusIcon } from "./StatusIcon.js";
 const RetryContext = createContext(undefined);
 RetryContext.displayName = "RetryContext";
 const RETRY_CHILDREN = (_jsxs(_Fragment, { children: [_jsx(ArrowPathIcon, {}), "Retry"] }));
+/**
+ * Button that retries the nearest `<Catcher>` error boundary when clicked.
+ *
+ * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
+ * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
+ *
+ * @param props `<Button>` variants and optional `children` for the label.
+ * @returns The retry button, or `null` when not inside a `<Catcher>`.
+ * @example <RetryButton small />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/RetryButton
+ */
 export function RetryButton({ children = RETRY_CHILDREN, ...props }) {
     const retry = use(RetryContext);
     if (!retry)
@@ -20,8 +31,14 @@ export function RetryButton({ children = RETRY_CHILDREN, ...props }) {
     return (_jsx(Button, { onClick: retry, ...props, children: children }));
 }
 /**
- * React component that provides an Error Boundary.
- * If an error occurs in any component under this, a general error will be shown to the user.
+ * React error boundary that renders a fallback component when any descendant throws.
+ *
+ * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
+ * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
+ *
+ * @example <Catcher><RiskyComponent /></Catcher>
+ * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher
  */
 export class Catcher extends Component {
     static defaultProps = {
@@ -45,16 +62,41 @@ export class Catcher extends Component {
         return (_jsx(RetryContext, { value: retry, children: _jsx(ErrorComponent, { reason: reason }) }));
     }
 }
-/** Catch errors in a page. */
+/**
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
+ *
+ * @param children The page content to guard.
+ * @returns A `<Catcher>` configured to render `<ErrorPage>` on error.
+ * @example <PageCatcher><SettingsPage /></PageCatcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/PageCatcher
+ */
 export function PageCatcher({ children }) {
     return _jsx(Catcher, { as: ErrorPage, children: children });
 }
-/** Output a `<Notice>` for an unknown error reason. */
+/**
+ * Render a caught error as an inline `<Notice>` with a retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns An error `<Notice>` containing the message and a `<RetryButton>`.
+ * @example <ErrorNotice reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorNotice
+ */
 export function ErrorNotice({ reason }) {
     const message = getMessage(reason) ?? "Unknown error";
     return (_jsxs(Notice, { status: "error", children: [_jsx("p", { children: message }), _jsx(RetryButton, { small: true })] }));
 }
-/** Output a `<Page>` with an error `<Card>` for an unknown error reason. */
+/**
+ * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns A centered error page containing the message and a `<RetryButton>`.
+ * @example <ErrorPage reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorPage
+ */
 export function ErrorPage({ reason }) {
     const message = getMessage(reason) ?? "Unknown error";
     return (_jsx(Page, { title: "Error", children: _jsx(CenteredLayout, { children: _jsx(Card, { status: "error", children: _jsxs(Subheading, { children: [_jsxs(Row, { left: true, children: [_jsx(StatusIcon, { status: "error", size: "xlarge" }), " ", message] }), _jsx(RetryButton, {})] }) }) }) }));

package/ui/misc/Catcher.tsx

@@ -15,6 +15,11 @@ import { StatusIcon } from "./StatusIcon.js";
 const RetryContext = createContext<Callback | undefined>(undefined);
 RetryContext.displayName = "RetryContext";
 
+/**
+ * Props for `<RetryButton>` — `<Button>` variants plus optional `children` to override the default "Retry" label.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/RetryButtonProps
+ */
 export interface RetryButtonProps extends ButtonVariants, OptionalChildProps {}
 
 const RETRY_CHILDREN = (
@@ -24,6 +29,17 @@ const RETRY_CHILDREN = (
 	</>
 );
 
+/**
+ * Button that retries the nearest `<Catcher>` error boundary when clicked.
+ *
+ * - Reads the retry callback from `<Catcher>`'s private context, so it renders `null` when there is no boundary above it to retry.
+ * - Defaults to an "Retry" label with a refresh icon; pass `children` to override.
+ *
+ * @param props `<Button>` variants and optional `children` for the label.
+ * @returns The retry button, or `null` when not inside a `<Catcher>`.
+ * @example <RetryButton small />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/RetryButton
+ */
 export function RetryButton({ children = RETRY_CHILDREN, ...props }: RetryButtonProps): ReactElement | null {
 	const retry = use(RetryContext);
 	if (!retry) return null;
@@ -34,10 +50,20 @@ export function RetryButton({ children = RETRY_CHILDREN, ...props }: RetryButton
 	);
 }
 
+/**
+ * Props for a component that renders a caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorComponentProps
+ */
 export interface ErrorComponentProps {
 	reason: unknown;
 }
 
+/**
+ * Props for `<Catcher>` — the `children` to guard plus the `as` component used to render any caught error.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/CatcherProps
+ */
 export interface CatcherProps extends ChildProps {
 	/** Component to render an error (defaults to `<ErrorNotice />`) */
 	as: (props: ErrorComponentProps) => ReactElement;
@@ -49,8 +75,14 @@ type CatcherState = {
 };
 
 /**
- * React component that provides an Error Boundary.
- * If an error occurs in any component under this, a general error will be shown to the user.
+ * React error boundary that renders a fallback component when any descendant throws.
+ *
+ * - Catches render-time errors below it and shows the `as` component (defaults to `<ErrorNotice>`) with the caught `reason`.
+ * - Provides a retry callback to descendant `<RetryButton>`s that clears the error and re-renders `children`.
+ *
+ * @example <Catcher><RiskyComponent /></Catcher>
+ * @example <Catcher as={ErrorPage}><RiskyComponent /></Catcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/Catcher
  */
 export class Catcher extends Component<CatcherProps, CatcherState> {
 	static defaultProps: Pick<CatcherProps, "as"> = {
@@ -78,16 +110,42 @@ export class Catcher extends Component<CatcherProps, CatcherState> {
 	}
 }
 
+/**
+ * Props for `<PageCatcher>` — the page `children` to guard.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/PageCatcherProps
+ */
 export interface PageCatcherProps extends ChildProps {}
 
-/** Catch errors in a page. */
+/**
+ * Error boundary for a whole page that renders a full `<ErrorPage>` fallback on error.
+ *
+ * @param children The page content to guard.
+ * @returns A `<Catcher>` configured to render `<ErrorPage>` on error.
+ * @example <PageCatcher><SettingsPage /></PageCatcher>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/PageCatcher
+ */
 export function PageCatcher({ children }: PageCatcherProps): ReactElement {
 	return <Catcher as={ErrorPage}>{children}</Catcher>;
 }
 
+/**
+ * Props for `<ErrorNotice>` — the caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorNoticeProps
+ */
 export interface ErrorNoticeProps extends ErrorComponentProps {}
 
-/** Output a `<Notice>` for an unknown error reason. */
+/**
+ * Render a caught error as an inline `<Notice>` with a retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns An error `<Notice>` containing the message and a `<RetryButton>`.
+ * @example <ErrorNotice reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorNotice
+ */
 export function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (
@@ -98,9 +156,23 @@ export function ErrorNotice({ reason }: ErrorNoticeProps): ReactElement {
 	);
 }
 
+/**
+ * Props for `<ErrorPage>` — the caught error `reason`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorPageProps
+ */
 export interface ErrorPageProps extends ErrorComponentProps {}
 
-/** Output a `<Page>` with an error `<Card>` for an unknown error reason. */
+/**
+ * Render a caught error as a full-page `<Page>` with an error `<Card>` and retry button.
+ *
+ * - Uses `getMessage()` to extract a human-readable message, falling back to `"Unknown error"`.
+ *
+ * @param reason The caught error to display.
+ * @returns A centered error page containing the message and a `<RetryButton>`.
+ * @example <ErrorPage reason={thrown} />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Catcher/ErrorPage
+ */
 export function ErrorPage({ reason }: ErrorPageProps): ReactElement {
 	const message = getMessage(reason) ?? "Unknown error";
 	return (

package/ui/misc/Loading.d.ts

@@ -1,8 +1,28 @@
 import type { ReactElement } from "react";
 declare const _componentProps: unique symbol;
+/**
+ * Props for `<Loading>` — takes no props (branded empty interface).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Loading/LoadingProps
+ */
 export interface LoadingProps {
     readonly [_componentProps]?: never;
 }
+/**
+ * Animated spinner SVG used as a loading indicator.
+ *
+ * - Self-contained inline SVG with a rotating indicator arc; inherits its colour and size from the surrounding text.
+ *
+ * @returns The spinner element.
+ * @example <Loading />
+ * @see https://dhoulb.github.io/shelving/ui/misc/Loading/Loading
+ */
 export declare function Loading(): ReactElement;
+/**
+ * Shared `<Loading>` element with a stable `key`, ready to drop into `Suspense` fallbacks and lists.
+ *
+ * @example <Suspense fallback={LOADING}>…</Suspense>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Loading/LOADING
+ */
 export declare const LOADING: import("react").JSX.Element;
 export {};