shelving 1.236.0 → 1.236.2

package/ui/notice/Message.js

@@ -5,11 +5,32 @@ import { getColorClass } from "../style/Color.js";
 import { getStatusClass } from "../style/Status.js";
 import { getClass } from "../util/css.js";
 import MESSAGE_CSS from "./Message.module.css";
+/**
+ * Base `className` applied to every `<Message>` paragraph.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/MESSAGE_CLASS
+ */
 export const MESSAGE_CLASS = getClass(MESSAGE_CSS.message);
-/** Paragraph with status colours. */
+/**
+ * Status-coloured paragraph used for inline feedback messages.
+ *
+ * - Sets an ARIA `role` of `"alert"` for error/danger statuses, otherwise `"status"`.
+ *
+ * @param children The message content.
+ * @param props Paragraph, colour, and status styling variants.
+ * @returns The message paragraph element.
+ * @example <Message status="error">Something went wrong</Message>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/Message
+ */
 export function Message({ children, ...props }) {
     const { status } = props;
     return (_jsx("p", { role: status === "error" || status === "danger" ? "alert" : "status", className: getClass(PARAGRAPH_CLASS, //
         MESSAGE_CLASS, getStatusClass(props), getColorClass(props)), children: children }));
 }
+/**
+ * Shared loading `<Message>` element containing the `<Loading>` spinner.
+ *
+ * @example return isLoading ? LOADING_MESSAGE : <Message>{text}</Message>;
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/LOADING_MESSAGE
+ */
 export const LOADING_MESSAGE = _jsx(Message, { status: "loading", children: LOADING });

package/ui/notice/Message.tsx

@@ -5,11 +5,31 @@ import { getStatusClass, type StatusVariants } from "../style/Status.js";
 import { getClass } from "../util/css.js";
 import MESSAGE_CSS from "./Message.module.css";
 
+/**
+ * Base `className` applied to every `<Message>` paragraph.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/MESSAGE_CLASS
+ */
 export const MESSAGE_CLASS = getClass(MESSAGE_CSS.message);
 
+/**
+ * Props for `<Message>` — paragraph props plus colour and status styling variants.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/MessageProps
+ */
 export interface MessageProps extends ParagraphProps, ColorVariants, StatusVariants {}
 
-/** Paragraph with status colours. */
+/**
+ * Status-coloured paragraph used for inline feedback messages.
+ *
+ * - Sets an ARIA `role` of `"alert"` for error/danger statuses, otherwise `"status"`.
+ *
+ * @param children The message content.
+ * @param props Paragraph, colour, and status styling variants.
+ * @returns The message paragraph element.
+ * @example <Message status="error">Something went wrong</Message>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/Message
+ */
 export function Message({ children, ...props }: MessageProps) {
 	const { status } = props;
 	return (
@@ -27,4 +47,10 @@ export function Message({ children, ...props }: MessageProps) {
 	);
 }
 
+/**
+ * Shared loading `<Message>` element containing the `<Loading>` spinner.
+ *
+ * @example return isLoading ? LOADING_MESSAGE : <Message>{text}</Message>;
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/LOADING_MESSAGE
+ */
 export const LOADING_MESSAGE = <Message status="loading">{LOADING}</Message>;

package/ui/notice/Notice.d.ts

@@ -3,10 +3,34 @@ import { type ColorVariants } from "../style/Color.js";
 import { type FlexVariants } from "../style/Flex.js";
 import { type StatusVariants } from "../style/Status.js";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `<Notice>` — flex/colour/status styling variants, optional `children`, and an optional `icon`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/NoticeProps
+ */
 export interface NoticeProps extends FlexVariants, ColorVariants, StatusVariants, OptionalChildProps {
     /** Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). */
     icon?: ReactElement | false | undefined;
 }
+/**
+ * Block-level status callout with an icon and message, used to highlight feedback.
+ *
+ * - Shows a `<StatusIcon>` for the current `status` by default; pass `icon` to override, or `false`/`null` to hide it.
+ * - Sets an ARIA `role` of `"alert"` for error/danger statuses, otherwise `"status"`.
+ *
+ * @param children The notice content.
+ * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
+ * @param props Flex, colour, and status styling variants.
+ * @returns The notice callout element.
+ * @example <Notice status="success">Saved your changes</Notice>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
+ */
 export declare function Notice({ children, //
 icon, ...props }: NoticeProps): import("react").JSX.Element;
+/**
+ * Shared loading `<Notice>` element showing the loading spinner.
+ *
+ * @example <Suspense fallback={LOADING_NOTICE}>…</Suspense>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/LOADING_NOTICE
+ */
 export declare const LOADING_NOTICE: import("react").JSX.Element;

package/ui/notice/Notice.js

@@ -6,9 +6,28 @@ import { getFlexClass } from "../style/Flex.js";
 import { getStatusClass } from "../style/Status.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import NOTICE_CSS from "./Notice.module.css";
+/**
+ * Block-level status callout with an icon and message, used to highlight feedback.
+ *
+ * - Shows a `<StatusIcon>` for the current `status` by default; pass `icon` to override, or `false`/`null` to hide it.
+ * - Sets an ARIA `role` of `"alert"` for error/danger statuses, otherwise `"status"`.
+ *
+ * @param children The notice content.
+ * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
+ * @param props Flex, colour, and status styling variants.
+ * @returns The notice callout element.
+ * @example <Notice status="success">Saved your changes</Notice>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
+ */
 export function Notice({ children, //
 icon, ...props }) {
     const { status } = props;
     return (_jsxs("aside", { role: status === "danger" || status === "error" ? "alert" : "status", className: getClass(BLOCK_CLASS, getModuleClass(NOTICE_CSS, "notice", props), getFlexClass(props), getStatusClass(props), getColorClass(props)), children: [icon !== undefined ? icon : status && _jsx(StatusIcon, { status: status }), children] }));
 }
+/**
+ * Shared loading `<Notice>` element showing the loading spinner.
+ *
+ * @example <Suspense fallback={LOADING_NOTICE}>…</Suspense>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/LOADING_NOTICE
+ */
 export const LOADING_NOTICE = _jsx(Notice, { status: "loading" });

package/ui/notice/Notice.tsx

@@ -8,11 +8,29 @@ import { getClass, getModuleClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import NOTICE_CSS from "./Notice.module.css";
 
+/**
+ * Props for `<Notice>` — flex/colour/status styling variants, optional `children`, and an optional `icon`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/NoticeProps
+ */
 export interface NoticeProps extends FlexVariants, ColorVariants, StatusVariants, OptionalChildProps {
 	/** Icon for the notice (or `null` or `false` to hide the icon, defaults to `<StatusIcon>`). */
 	icon?: ReactElement | false | undefined;
 }
 
+/**
+ * Block-level status callout with an icon and message, used to highlight feedback.
+ *
+ * - Shows a `<StatusIcon>` for the current `status` by default; pass `icon` to override, or `false`/`null` to hide it.
+ * - Sets an ARIA `role` of `"alert"` for error/danger statuses, otherwise `"status"`.
+ *
+ * @param children The notice content.
+ * @param icon Optional icon override (`false`/`null` hides it; defaults to the matching `<StatusIcon>`).
+ * @param props Flex, colour, and status styling variants.
+ * @returns The notice callout element.
+ * @example <Notice status="success">Saved your changes</Notice>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/Notice
+ */
 export function Notice({
 	children, //
 	icon,
@@ -36,4 +54,10 @@ export function Notice({
 	);
 }
 
+/**
+ * Shared loading `<Notice>` element showing the loading spinner.
+ *
+ * @example <Suspense fallback={LOADING_NOTICE}>…</Suspense>
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notice/LOADING_NOTICE
+ */
 export const LOADING_NOTICE = <Notice status="loading" />;

package/ui/notice/NoticeStore.d.ts

@@ -5,13 +5,41 @@ type NoticeData<S extends string> = {
     readonly status?: S | undefined;
     readonly children?: ReactNode | undefined;
 };
-/** Store a single notice. */
+/**
+ * Store holding a single notice's content and status, owned by a `NoticesStore`.
+ *
+ * - Auto-closes itself a few seconds after opening unless its status is `"loading"`.
+ * - Adds itself to its parent `NoticesStore` on construction and removes itself on `close()` or disposal.
+ *
+ * @example const notice = notices.show("Saved", "success"); notice.close();
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore
+ */
 export declare class NoticeStore<S extends string> extends DataStore<NoticeData<S>> {
     private _notices;
     readonly key: string;
+    /**
+     * Create a notice and register it with its parent `NoticesStore`.
+     *
+     * @param notices The parent store to add this notice to.
+     * @param children The notice content (optional).
+     * @param status The notice status (optional).
+     */
     constructor(notices: NoticesStore<S>, children?: ReactNode | null, status?: S | undefined);
+    /**
+     * Update the notice's content and status, resetting its auto-close timer.
+     *
+     * @param children The new notice content.
+     * @param status The new status (defaults to the current status).
+     * @example notice.show("Updating…", "loading");
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/show
+     */
     show(children?: ReactNode | undefined, status?: S | undefined): void;
-    /** Close this notice (permanently). */
+    /**
+     * Close this notice permanently, removing it from its parent `NoticesStore`.
+     *
+     * @example notice.close();
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/close
+     */
     close(): void;
     write(data: NoticeData<S>): void;
     protected _autoclose(): void;

package/ui/notice/NoticeStore.js

@@ -5,20 +5,48 @@ import { getRandomKey } from "../../util/random.js";
 import { Timeout } from "../../util/timeout.js";
 // Constants.
 const TEMPORARY_NOTICE_MS = 5 * SECOND; // How long before notices hide themselves.
-/** Store a single notice. */
+/**
+ * Store holding a single notice's content and status, owned by a `NoticesStore`.
+ *
+ * - Auto-closes itself a few seconds after opening unless its status is `"loading"`.
+ * - Adds itself to its parent `NoticesStore` on construction and removes itself on `close()` or disposal.
+ *
+ * @example const notice = notices.show("Saved", "success"); notice.close();
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore
+ */
 export class NoticeStore extends DataStore {
     _notices;
     key = getRandomKey();
+    /**
+     * Create a notice and register it with its parent `NoticesStore`.
+     *
+     * @param notices The parent store to add this notice to.
+     * @param children The notice content (optional).
+     * @param status The notice status (optional).
+     */
     constructor(notices, children, status) {
         super({ status, children });
         this._notices = notices;
         notices.add(this);
         this._autoclose();
     }
+    /**
+     * Update the notice's content and status, resetting its auto-close timer.
+     *
+     * @param children The new notice content.
+     * @param status The new status (defaults to the current status).
+     * @example notice.show("Updating…", "loading");
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/show
+     */
     show(children, status = this.value.status) {
         this.value = { children, status };
     }
-    /** Close this notice (permanently). */
+    /**
+     * Close this notice permanently, removing it from its parent `NoticesStore`.
+     *
+     * @example notice.close();
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/close
+     */
     close() {
         this._notices.delete(this);
     }

package/ui/notice/NoticeStore.ts

@@ -14,12 +14,27 @@ type NoticeData<S extends string> = {
 	readonly children?: ReactNode | undefined;
 };
 
-/** Store a single notice. */
+/**
+ * Store holding a single notice's content and status, owned by a `NoticesStore`.
+ *
+ * - Auto-closes itself a few seconds after opening unless its status is `"loading"`.
+ * - Adds itself to its parent `NoticesStore` on construction and removes itself on `close()` or disposal.
+ *
+ * @example const notice = notices.show("Saved", "success"); notice.close();
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore
+ */
 export class NoticeStore<S extends string> extends DataStore<NoticeData<S>> {
 	private _notices: NoticesStore<S>;
 
 	readonly key = getRandomKey();
 
+	/**
+	 * Create a notice and register it with its parent `NoticesStore`.
+	 *
+	 * @param notices The parent store to add this notice to.
+	 * @param children The notice content (optional).
+	 * @param status The notice status (optional).
+	 */
 	constructor(notices: NoticesStore<S>, children?: ReactNode | null, status?: S | undefined) {
 		super({ status, children });
 		this._notices = notices;
@@ -27,11 +42,24 @@ export class NoticeStore<S extends string> extends DataStore<NoticeData<S>> {
 		this._autoclose();
 	}
 
+	/**
+	 * Update the notice's content and status, resetting its auto-close timer.
+	 *
+	 * @param children The new notice content.
+	 * @param status The new status (defaults to the current status).
+	 * @example notice.show("Updating…", "loading");
+	 * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/show
+	 */
 	show(children?: ReactNode | undefined, status: S | undefined = this.value.status): void {
 		this.value = { children, status };
 	}
 
-	/** Close this notice (permanently). */
+	/**
+	 * Close this notice permanently, removing it from its parent `NoticesStore`.
+	 *
+	 * @example notice.close();
+	 * @see https://dhoulb.github.io/shelving/ui/notice/NoticeStore/NoticeStore/close
+	 */
 	close() {
 		this._notices.delete(this);
 	}

package/ui/notice/Notices.d.ts

@@ -1,10 +1,20 @@
 import { type ReactElement } from "react";
 import { type FlexVariants } from "../style/Flex.js";
+/**
+ * Props for `<Notices>` — flex styling variants for the notices container.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notices/NoticesProps
+ */
 export interface NoticesProps extends FlexVariants {
 }
 /**
- * Output the global list of notices.
+ * Render the global list of notices and subscribe to incoming `"notice"` events.
  * - Listens for `"notice"` events on `window` (or that bubble up to `window`) and shows them in the global notice list.
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices into the global list.
+ *
+ * @param props Flex styling variants for the container.
+ * @returns The notices container element.
+ * @example <Notices column />
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */
 export declare function Notices(props: NoticesProps): ReactElement;

package/ui/notice/Notices.js

@@ -9,9 +9,14 @@ import NOTICES_CSS from "./Notices.module.css";
 import { NOTICES } from "./NoticesStore.js";
 const NOTICES_CLASS = getModuleClass(NOTICES_CSS, "notices");
 /**
- * Output the global list of notices.
+ * Render the global list of notices and subscribe to incoming `"notice"` events.
  * - Listens for `"notice"` events on `window` (or that bubble up to `window`) and shows them in the global notice list.
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices into the global list.
+ *
+ * @param props Flex styling variants for the container.
+ * @returns The notices container element.
+ * @example <Notices column />
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */
 export function Notices(props) {
     const notices = useStore(NOTICES).value;

package/ui/notice/Notices.tsx

@@ -9,12 +9,22 @@ import { NOTICES } from "./NoticesStore.js";
 
 const NOTICES_CLASS = getModuleClass(NOTICES_CSS, "notices");
 
+/**
+ * Props for `<Notices>` — flex styling variants for the notices container.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notices/NoticesProps
+ */
 export interface NoticesProps extends FlexVariants {}
 
 /**
- * Output the global list of notices.
+ * Render the global list of notices and subscribe to incoming `"notice"` events.
  * - Listens for `"notice"` events on `window` (or that bubble up to `window`) and shows them in the global notice list.
  * - This is how e.g. `<Button>` and `<FormNotify>` components send notices into the global list.
+ *
+ * @param props Flex styling variants for the container.
+ * @returns The notices container element.
+ * @example <Notices column />
+ * @see https://dhoulb.github.io/shelving/ui/notice/Notices/Notices
  */
 export function Notices(props: NoticesProps): ReactElement {
 	const notices = useStore(NOTICES).value;

package/ui/notice/NoticesStore.d.ts

@@ -1,11 +1,31 @@
 import type { ReactNode } from "react";
 import { ArrayStore } from "../../store/ArrayStore.js";
 import { NoticeStore } from "./NoticeStore.js";
-/** Store a list of notices. */
+/**
+ * Store holding the live list of `NoticeStore` notices currently shown.
+ *
+ * - Disposing the store disposes (and closes) every notice it contains.
+ *
+ * @example const notices = new NoticesStore(); notices.show("Hello");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore
+ */
 export declare class NoticesStore<S extends string> extends ArrayStore<NoticeStore<S>> {
-    /** Show a notice with an optional status. */
+    /**
+     * Create and show a new notice, adding it to this list.
+     *
+     * @param children The notice content (optional).
+     * @param status The notice status (optional).
+     * @returns The newly created `NoticeStore`.
+     * @example notices.show("Saved your changes", "success");
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore/show
+     */
     show(children?: ReactNode | undefined, status?: S | undefined): NoticeStore<S>;
     [Symbol.asyncDispose](): Promise<void>;
 }
-/** Create a global list of shown notices allowing any of the default statuses. */
+/**
+ * Global `NoticesStore` shown by `<Notices>`, accepting any of the default statuses.
+ *
+ * @example NOTICES.show("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NOTICES
+ */
 export declare const NOTICES: NoticesStore<"danger" | "error" | "info" | "loading" | "success" | "warning">;

package/ui/notice/NoticesStore.js

@@ -1,9 +1,24 @@
 import { ArrayStore } from "../../store/ArrayStore.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { NoticeStore } from "./NoticeStore.js";
-/** Store a list of notices. */
+/**
+ * Store holding the live list of `NoticeStore` notices currently shown.
+ *
+ * - Disposing the store disposes (and closes) every notice it contains.
+ *
+ * @example const notices = new NoticesStore(); notices.show("Hello");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore
+ */
 export class NoticesStore extends ArrayStore {
-    /** Show a notice with an optional status. */
+    /**
+     * Create and show a new notice, adding it to this list.
+     *
+     * @param children The notice content (optional).
+     * @param status The notice status (optional).
+     * @returns The newly created `NoticeStore`.
+     * @example notices.show("Saved your changes", "success");
+     * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore/show
+     */
     show(children, status) {
         return new NoticeStore(this, children, status);
     }
@@ -12,5 +27,10 @@ export class NoticesStore extends ArrayStore {
         super[Symbol.asyncDispose]());
     }
 }
-/** Create a global list of shown notices allowing any of the default statuses. */
+/**
+ * Global `NoticesStore` shown by `<Notices>`, accepting any of the default statuses.
+ *
+ * @example NOTICES.show("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NOTICES
+ */
 export const NOTICES = new NoticesStore();

package/ui/notice/NoticesStore.ts

@@ -4,9 +4,24 @@ import { awaitDispose } from "../../util/dispose.js";
 import type { Status } from "../style/Status.js";
 import { NoticeStore } from "./NoticeStore.js";
 
-/** Store a list of notices. */
+/**
+ * Store holding the live list of `NoticeStore` notices currently shown.
+ *
+ * - Disposing the store disposes (and closes) every notice it contains.
+ *
+ * @example const notices = new NoticesStore(); notices.show("Hello");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore
+ */
 export class NoticesStore<S extends string> extends ArrayStore<NoticeStore<S>> {
-	/** Show a notice with an optional status. */
+	/**
+	 * Create and show a new notice, adding it to this list.
+	 *
+	 * @param children The notice content (optional).
+	 * @param status The notice status (optional).
+	 * @returns The newly created `NoticeStore`.
+	 * @example notices.show("Saved your changes", "success");
+	 * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NoticesStore/show
+	 */
 	show(children?: ReactNode | undefined, status?: S | undefined): NoticeStore<S> {
 		return new NoticeStore(this, children, status);
 	}
@@ -19,5 +34,10 @@ export class NoticesStore<S extends string> extends ArrayStore<NoticeStore<S>> {
 	}
 }
 
-/** Create a global list of shown notices allowing any of the default statuses. */
+/**
+ * Global `NoticesStore` shown by `<Notices>`, accepting any of the default statuses.
+ *
+ * @example NOTICES.show("Saved your changes", "success");
+ * @see https://dhoulb.github.io/shelving/ui/notice/NoticesStore/NOTICES
+ */
 export const NOTICES = new NoticesStore<Status>();

package/ui/page/HTML.d.ts

@@ -1,10 +1,21 @@
 import type { ReactElement } from "react";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `<HTML>` — initial `Meta` (language/root/app) plus the page `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/page/HTML/HTMLProps
+ */
 export interface HTMLProps extends PossibleMeta, ChildProps {
 }
 /**
- * Output a `<html>` element wrapping `<head>` (via `<Head>`) and `<body>`.
- * - `<Head>` renders the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<PageHead>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ * Render the full `<html>` document shell wrapping `<head>` and `<body>`.
+ * - Emits the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<Head>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ *
+ * @param children The document body content.
+ * @param meta Initial meta (language/root/app) merged with the surrounding `<Meta>` context.
+ * @returns The `<html>` document element.
+ * @example <HTML app="My App" root="https://example.com/"><App /></HTML>
+ * @see https://dhoulb.github.io/shelving/ui/page/HTML/HTML
  */
 export declare function HTML({ children, ...meta }: HTMLProps): ReactElement;

package/ui/page/HTML.js

@@ -1,8 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { MetaContext, requireMeta } from "../misc/MetaContext.js";
 /**
- * Output a `<html>` element wrapping `<head>` (via `<Head>`) and `<body>`.
- * - `<Head>` renders the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<PageHead>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ * Render the full `<html>` document shell wrapping `<head>` and `<body>`.
+ * - Emits the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<Head>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ *
+ * @param children The document body content.
+ * @param meta Initial meta (language/root/app) merged with the surrounding `<Meta>` context.
+ * @returns The `<html>` document element.
+ * @example <HTML app="My App" root="https://example.com/"><App /></HTML>
+ * @see https://dhoulb.github.io/shelving/ui/page/HTML/HTML
  */
 export function HTML({ children, ...meta }) {
     const merged = requireMeta(meta);

package/ui/page/HTML.tsx

@@ -3,11 +3,22 @@ import { MetaContext, requireMeta } from "../misc/MetaContext.js";
 import type { PossibleMeta } from "../util/index.js";
 import type { ChildProps } from "../util/props.js";
 
+/**
+ * Props for `<HTML>` — initial `Meta` (language/root/app) plus the page `children`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/page/HTML/HTMLProps
+ */
 export interface HTMLProps extends PossibleMeta, ChildProps {}
 
 /**
- * Output a `<html>` element wrapping `<head>` (via `<Head>`) and `<body>`.
- * - `<Head>` renders the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<PageHead>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ * Render the full `<html>` document shell wrapping `<head>` and `<body>`.
+ * - Emits the literal `<head>` with `<base>` and other shell-level metadata; per-page hoistable elements (title, meta, links, stylesheets, scripts) come from `<Head>` inside `<Page>` and are hoisted into this `<head>` by React 19.
+ *
+ * @param children The document body content.
+ * @param meta Initial meta (language/root/app) merged with the surrounding `<Meta>` context.
+ * @returns The `<html>` document element.
+ * @example <HTML app="My App" root="https://example.com/"><App /></HTML>
+ * @see https://dhoulb.github.io/shelving/ui/page/HTML/HTML
  */
 export function HTML({ children, ...meta }: HTMLProps): ReactElement {
 	const merged = requireMeta(meta);

package/ui/page/Head.d.ts

@@ -1,8 +1,12 @@
 import { type ReactElement } from "react";
 /**
- * Per-page meta tags plus history navigation.
+ * Emit the current page's head metadata and sync browser history to its URL.
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
+ *
+ * @returns The hoistable head elements derived from the current `<Meta>` context.
+ * @example <Page title="Settings"><Head />…</Page>
+ * @see https://dhoulb.github.io/shelving/ui/page/Head/Head
  */
 export declare function Head(): ReactElement;

package/ui/page/Head.js

@@ -6,10 +6,14 @@ import { joinTitles } from "../util/meta.js";
 /** Meta tags with a capital first letter and hyphens, e.g. `Content-Security-Policy` or `Accept`, are `http-equiv=""` tags. */
 const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 /**
- * Per-page meta tags plus history navigation.
+ * Emit the current page's head metadata and sync browser history to its URL.
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
+ *
+ * @returns The hoistable head elements derived from the current `<Meta>` context.
+ * @example <Page title="Settings"><Head />…</Page>
+ * @see https://dhoulb.github.io/shelving/ui/page/Head/Head
  */
 export function Head() {
     const meta = requireMeta();

package/ui/page/Head.tsx

@@ -8,10 +8,14 @@ import { joinTitles, type MetaAssets, type MetaLinks, type MetaTags } from "../u
 const R_HTTP_EQUIV = /^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$/;
 
 /**
- * Per-page meta tags plus history navigation.
+ * Emit the current page's head metadata and sync browser history to its URL.
  * - Emits hoistable head elements (title, meta, links, stylesheets, scripts) inline; React 19 hoists each one into the document `<head>`.
  * - Does not render `<base>` (not hoistable — that lives in `<Head>` in the `<HTML>` shell component).
  * - Updates `window.history` to match the page URL.
+ *
+ * @returns The hoistable head elements derived from the current `<Meta>` context.
+ * @example <Page title="Settings"><Head />…</Page>
+ * @see https://dhoulb.github.io/shelving/ui/page/Head/Head
  */
 export function Head(): ReactElement {
 	const meta = requireMeta();