shelving 1.236.0 → 1.236.2

package/ui/misc/Loading.js

@@ -1,6 +1,21 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import styles from "./Loading.module.css";
+/**
+ * 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 function Loading() {
     return (_jsxs("svg", { "aria-hidden": "true", viewBox: "0 0 24 24", xmlns: "http://www.w3.org/2000/svg", className: styles.spinner, "data-slot": "icon", children: [_jsx("title", { children: "Loading..." }), _jsx("circle", { className: styles.track, cx: "12", cy: "12", r: "9", pathLength: "100" }), _jsxs("g", { children: [_jsx("animateTransform", { attributeName: "transform", attributeType: "xml", type: "rotate", from: "0 12 12", to: "360 12 12", dur: "0.5s", repeatCount: "indefinite" }), _jsx("circle", { className: styles.indicator, cx: "12", cy: "12", r: "9", pathLength: "100" })] })] }));
 }
+/**
+ * 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 const LOADING = _jsx(Loading, {}, "loading");

package/ui/misc/Loading.tsx

@@ -3,10 +3,24 @@ import styles from "./Loading.module.css";
 
 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 function Loading(): ReactElement {
 	return (
 		<svg aria-hidden="true" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" className={styles.spinner} data-slot="icon">
@@ -28,4 +42,10 @@ export 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 const LOADING = <Loading key="loading" />;

package/ui/misc/Mapper.d.ts

@@ -5,11 +5,17 @@ import type { ChildProps } from "../util/props.js";
  * Dispatch table from a `JSX.IntrinsicElements` key to a renderer component.
  * - Each entry is optional — unmapped elements fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` HTML element).
  * - Per-entry component receives `JSX.IntrinsicElements[K] & E` — the declared props for that element type, plus any extra props `E` the mapper is configured to thread through.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/Mapping
  */
 export type Mapping<E = unknown> = {
     [K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K] & E>;
 };
-/** Props for the `Mapping` component returned by `createMapper()`. */
+/**
+ * Props for the `Mapping` component returned by `createMapper()`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/MappingProps
+ */
 export interface MappingProps<E = unknown> extends ChildProps {
     /** Mapping entries that extend or override the inherited mapping inside this subtree. */
     readonly mapping: Mapping<E>;
@@ -18,6 +24,8 @@ export interface MappingProps<E = unknown> extends ChildProps {
  * Props for the `Mapper` component returned by `createMapper()`.
  * - `children` holds the pre-walked elements to dispatch.
  * - All other props are spread onto every mapped child as additional props (`E`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/MapperProps
  */
 export type MapperProps<E = unknown> = E & {
     readonly children?: Elements;
@@ -31,6 +39,8 @@ export type MapperProps<E = unknown> = E & {
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
  * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
+ * @param defaults The initial mapping of element types to renderer components.
+ * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
  * // No extras:
@@ -45,5 +55,7 @@ export type MapperProps<E = unknown> = E & {
  *   "tree-element": TreeMenuItem,
  * });
  * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/createMapper
  */
 export declare function createMapper<E = unknown>(defaults?: Mapping<E>): [Mapping: FunctionComponent<MappingProps<E>>, Mapper: FunctionComponent<MapperProps<E>>];

package/ui/misc/Mapper.js

@@ -10,6 +10,8 @@ import { walkElements } from "../../util/element.js";
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
  * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
+ * @param defaults The initial mapping of element types to renderer components.
+ * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
  * // No extras:
@@ -24,6 +26,8 @@ import { walkElements } from "../../util/element.js";
  *   "tree-element": TreeMenuItem,
  * });
  * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/createMapper
  */
 export function createMapper(defaults = {}) {
     const Context = createContext(defaults);

package/ui/misc/Mapper.tsx

@@ -7,12 +7,18 @@ import type { ChildProps } from "../util/props.js";
  * Dispatch table from a `JSX.IntrinsicElements` key to a renderer component.
  * - Each entry is optional — unmapped elements fall through and render as themselves (e.g. an unmapped `<tree-foo>` appears as a raw `<tree-foo>` HTML element).
  * - Per-entry component receives `JSX.IntrinsicElements[K] & E` — the declared props for that element type, plus any extra props `E` the mapper is configured to thread through.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/Mapping
  */
 export type Mapping<E = unknown> = {
 	[K in keyof JSX.IntrinsicElements]?: ComponentType<JSX.IntrinsicElements[K] & E>;
 };
 
-/** Props for the `Mapping` component returned by `createMapper()`. */
+/**
+ * Props for the `Mapping` component returned by `createMapper()`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/MappingProps
+ */
 export interface MappingProps<E = unknown> extends ChildProps {
 	/** Mapping entries that extend or override the inherited mapping inside this subtree. */
 	readonly mapping: Mapping<E>;
@@ -22,6 +28,8 @@ export interface MappingProps<E = unknown> extends ChildProps {
  * Props for the `Mapper` component returned by `createMapper()`.
  * - `children` holds the pre-walked elements to dispatch.
  * - All other props are spread onto every mapped child as additional props (`E`).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/MapperProps
  */
 export type MapperProps<E = unknown> = E & {
 	readonly children?: Elements;
@@ -40,6 +48,8 @@ type AnyMapping = Record<string, ComponentType<any> | undefined>;
  * Each call creates its own context — independent mappers don't interfere with each other.
  *
  * @typeParam E The shape of any extra props the mapper threads through to every dispatched child. Defaults to `unknown` (no extras).
+ * @param defaults The initial mapping of element types to renderer components.
+ * @returns A `[Mapping, Mapper]` tuple of components sharing a private context.
  *
  * @example
  * // No extras:
@@ -54,6 +64,8 @@ type AnyMapping = Record<string, ComponentType<any> | undefined>;
  *   "tree-element": TreeMenuItem,
  * });
  * <TreeMenuMapper path="/foo">{queryElements(children, query)}</TreeMenuMapper>
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Mapper/createMapper
  */
 export function createMapper<E = unknown>(
 	defaults: Mapping<E> = {},

package/ui/misc/Markup.d.ts

@@ -1,6 +1,10 @@
 import type { ReactNode } from "react";
 import { type MarkupOptions } from "../../markup/MarkupParser.js";
-/** Props for `<Markup>` — extends `MarkupOptions` so callers can override `rules`, `rel`, `url`, `root`, or `schemes` directly. */
+/**
+ * Props for `<Markup>` — extends `MarkupOptions` so callers can override `rules`, `rel`, `url`, `root`, or `schemes` directly.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Markup/MarkupProps
+ */
 export interface MarkupProps extends Partial<MarkupOptions> {
     /** The source string to parse and render. */
     children?: string | undefined;
@@ -11,6 +15,10 @@ export interface MarkupProps extends Partial<MarkupOptions> {
  * - `url`/`root` default to the current `<Meta>` context so link rules resolve site-absolute and relative hrefs.
  * - Renders inside whatever ancestor element the caller provides — wrap in `<Prose>` to get the standard prose typography for the produced `<p>` / `<ul>` / `<pre>` / etc.
  *
+ * @param children The source markup string to parse and render (renders `null` when empty).
+ * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
+ * @returns The parsed markup as React nodes, or `null` when `children` is empty.
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */
 export declare function Markup({ children, ...options }: MarkupProps): ReactNode;

package/ui/misc/Markup.js

@@ -6,7 +6,11 @@ import { requireMeta } from "./MetaContext.js";
  * - `url`/`root` default to the current `<Meta>` context so link rules resolve site-absolute and relative hrefs.
  * - Renders inside whatever ancestor element the caller provides — wrap in `<Prose>` to get the standard prose typography for the produced `<p>` / `<ul>` / `<pre>` / etc.
  *
+ * @param children The source markup string to parse and render (renders `null` when empty).
+ * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
+ * @returns The parsed markup as React nodes, or `null` when `children` is empty.
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */
 export function Markup({ children, ...options }) {
     if (!children)

package/ui/misc/Markup.tsx

@@ -2,7 +2,11 @@ import type { ReactNode } from "react";
 import { type MarkupOptions, MarkupParser } from "../../markup/MarkupParser.js";
 import { requireMeta } from "./MetaContext.js";
 
-/** Props for `<Markup>` — extends `MarkupOptions` so callers can override `rules`, `rel`, `url`, `root`, or `schemes` directly. */
+/**
+ * Props for `<Markup>` — extends `MarkupOptions` so callers can override `rules`, `rel`, `url`, `root`, or `schemes` directly.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Markup/MarkupProps
+ */
 export interface MarkupProps extends Partial<MarkupOptions> {
 	/** The source string to parse and render. */
 	children?: string | undefined;
@@ -14,7 +18,11 @@ export interface MarkupProps extends Partial<MarkupOptions> {
  * - `url`/`root` default to the current `<Meta>` context so link rules resolve site-absolute and relative hrefs.
  * - Renders inside whatever ancestor element the caller provides — wrap in `<Prose>` to get the standard prose typography for the produced `<p>` / `<ul>` / `<pre>` / etc.
  *
+ * @param children The source markup string to parse and render (renders `null` when empty).
+ * @param options Optional `MarkupOptions` overrides (`rules`, `rel`, `url`, `root`, `schemes`).
+ * @returns The parsed markup as React nodes, or `null` when `children` is empty.
  * @example <Prose><Markup>{`A *bold* word with \`code\`.`}</Markup></Prose>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Markup/Markup
  */
 export function Markup({ children, ...options }: MarkupProps): ReactNode {
 	if (!children) return null;

package/ui/misc/MetaContext.d.ts

@@ -3,15 +3,29 @@ import type { AbsolutePath } from "../../util/path.js";
 import { type URIParams } from "../../util/uri.js";
 import { type ImmutableURL } from "../../util/url.js";
 import { type Meta, type PossibleMeta } from "../util/meta.js";
-/** Context to store the `Config` object. */
+/**
+ * React context holding the current `Meta` object (page URL, site root, title, etc.).
+ *
+ * @example <MetaContext value={meta}>…</MetaContext>
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/MetaContext
+ */
 export declare const MetaContext: import("react").Context<Meta>;
 /**
- * Use the current meta context in a component.
+ * Read the current `Meta` context, optionally merging in additional meta data.
+ *
+ * - Must be called inside a component or hook (reads context via React's `use()`).
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns The current `Meta`, with `meta` merged in when provided.
+ * @example const { title, url } = requireMeta();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMeta
  */
 export declare function requireMeta(meta?: PossibleMeta): Meta;
-/** A `Meta` object with a defined `url` object, and `path` and `params` properties combined in. */
+/**
+ * A `Meta` object with a guaranteed `url`, plus derived `path` and `params` properties.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/MetaURL
+ */
 export interface MetaURL extends Meta {
     url: ImmutableURL;
     /** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
@@ -20,11 +34,14 @@ export interface MetaURL extends Meta {
     params: URIParams;
 }
 /**
- * Use the current meta context in a component with some additional URL helpers.
+ * Read the current `Meta` context and derive URL helpers (`path` and `params`) from its `url`.
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
- * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
- * @throws {RequiredError} if the current meta has no `url`
- * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
+ * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
+ * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url`.
+ * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @example const { path, params } = requireMetaURL();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMetaURL
  */
 export declare function requireMetaURL(meta?: PossibleMeta, caller?: AnyCaller): MetaURL;

package/ui/misc/MetaContext.js

@@ -3,25 +3,38 @@ import { RequiredError } from "../../error/RequiredError.js";
 import { getURIParams } from "../../util/uri.js";
 import { matchURLPrefix } from "../../util/url.js";
 import { mergeMeta } from "../util/meta.js";
-/** Context to store the `Config` object. */
+/**
+ * React context holding the current `Meta` object (page URL, site root, title, etc.).
+ *
+ * @example <MetaContext value={meta}>…</MetaContext>
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/MetaContext
+ */
 export const MetaContext = createContext({});
 MetaContext.displayName = "MetaContext";
 /**
- * Use the current meta context in a component.
+ * Read the current `Meta` context, optionally merging in additional meta data.
+ *
+ * - Must be called inside a component or hook (reads context via React's `use()`).
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns The current `Meta`, with `meta` merged in when provided.
+ * @example const { title, url } = requireMeta();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMeta
  */
 export function requireMeta(meta) {
     const current = use(MetaContext);
     return meta ? mergeMeta(current, meta) : current;
 }
 /**
- * Use the current meta context in a component with some additional URL helpers.
+ * Read the current `Meta` context and derive URL helpers (`path` and `params`) from its `url`.
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
- * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
- * @throws {RequiredError} if the current meta has no `url`
- * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
+ * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
+ * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url`.
+ * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @example const { path, params } = requireMetaURL();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMetaURL
  */
 export function requireMetaURL(meta, caller = requireMetaURL) {
     const { url, root, ...combined } = requireMeta(meta);

package/ui/misc/MetaContext.tsx

@@ -6,21 +6,35 @@ import { getURIParams, type URIParams } from "../../util/uri.js";
 import { type ImmutableURL, matchURLPrefix } from "../../util/url.js";
 import { type Meta, mergeMeta, type PossibleMeta } from "../util/meta.js";
 
-/** Context to store the `Config` object. */
+/**
+ * React context holding the current `Meta` object (page URL, site root, title, etc.).
+ *
+ * @example <MetaContext value={meta}>…</MetaContext>
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/MetaContext
+ */
 export const MetaContext = createContext<Meta>({});
 MetaContext.displayName = "MetaContext";
 
 /**
- * Use the current meta context in a component.
+ * Read the current `Meta` context, optionally merging in additional meta data.
+ *
+ * - Must be called inside a component or hook (reads context via React's `use()`).
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
+ * @returns The current `Meta`, with `meta` merged in when provided.
+ * @example const { title, url } = requireMeta();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMeta
  */
 export function requireMeta(meta?: PossibleMeta): Meta {
 	const current = use(MetaContext);
 	return meta ? mergeMeta(current, meta) : current;
 }
 
-/** A `Meta` object with a defined `url` object, and `path` and `params` properties combined in. */
+/**
+ * A `Meta` object with a guaranteed `url`, plus derived `path` and `params` properties.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/MetaURL
+ */
 export interface MetaURL extends Meta {
 	url: ImmutableURL;
 	/** The path of `url` relative to `meta.root` (i.e. the _site-root-relative_ path). */
@@ -30,12 +44,15 @@ export interface MetaURL extends Meta {
 }
 
 /**
- * Use the current meta context in a component with some additional URL helpers.
+ * Read the current `Meta` context and derive URL helpers (`path` and `params`) from its `url`.
  *
  * @param meta A set of new possible meta data to combine into the current meta context.
- * @returns A `Meta` object with a defined `url` object, and `path` and `params` properties combined in.
- * @throws {RequiredError} if the current meta has no `url`
- * @throws {RequiredError} if the current meta `url` does not match the origin of the current meta `root`
+ * @param caller Function to attribute thrown `RequiredError`s to (defaults to `requireMetaURL`).
+ * @returns A `Meta` object with a defined `url`, plus `path` and `params` properties combined in.
+ * @throws RequiredError If the current meta has no `url`.
+ * @throws RequiredError If the current meta `url` does not share an origin with the meta `root`.
+ * @example const { path, params } = requireMetaURL();
+ * @see https://dhoulb.github.io/shelving/ui/misc/MetaContext/requireMetaURL
  */
 export function requireMetaURL(meta?: PossibleMeta, caller: AnyCaller = requireMetaURL): MetaURL {
 	const { url, root, ...combined } = requireMeta(meta);

package/ui/misc/StatusIcon.d.ts

@@ -1,9 +1,24 @@
 import type { ReactElement } from "react";
 import type { Status } from "../style/Status.js";
+/**
+ * Props for `<StatusIcon>` — the `status` to represent and optional icon `size`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIconProps
+ */
 export interface StatusIconProps {
     status?: Status;
     /** Size of the icon (defaults to the current line height). */
     size?: "small" | "normal" | "large" | "xlarge" | "xxlarge" | undefined;
 }
-/** Output a status icon based on the current status of something. */
+/**
+ * Render the icon for a given status, coloured to match.
+ *
+ * - Picks a heroicon per status (`success`, `error`, `warning`, etc.), falling back to an info icon, and uses the animated `<Loading>` spinner for `"loading"`.
+ *
+ * @param status The status to represent (defaults to `"info"`).
+ * @param size Optional icon size (defaults to the current line height).
+ * @returns The status icon element.
+ * @example <StatusIcon status="error" size="large" />
+ * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
+ */
 export declare function StatusIcon({ status, size }: StatusIconProps): ReactElement;

package/ui/misc/StatusIcon.js

@@ -11,7 +11,17 @@ const STATUS_ICONS = {
     warning: ExclamationTriangleIcon,
     danger: ExclamationTriangleIcon,
 };
-/** Output a status icon based on the current status of something. */
+/**
+ * Render the icon for a given status, coloured to match.
+ *
+ * - Picks a heroicon per status (`success`, `error`, `warning`, etc.), falling back to an info icon, and uses the animated `<Loading>` spinner for `"loading"`.
+ *
+ * @param status The status to represent (defaults to `"info"`).
+ * @param size Optional icon size (defaults to the current line height).
+ * @returns The status icon element.
+ * @example <StatusIcon status="error" size="large" />
+ * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
+ */
 export function StatusIcon({ status = "info", size }) {
     const Icon = STATUS_ICONS[status] ?? InformationCircleIcon;
     return _jsx(Icon, { className: `${getModuleClass(styles, "icon", size)} ${getModuleClass(statusStyles, status)}` });

package/ui/misc/StatusIcon.tsx

@@ -16,13 +16,28 @@ const STATUS_ICONS: {
 	danger: ExclamationTriangleIcon,
 };
 
+/**
+ * Props for `<StatusIcon>` — the `status` to represent and optional icon `size`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIconProps
+ */
 export interface StatusIconProps {
 	status?: Status;
 	/** Size of the icon (defaults to the current line height). */
 	size?: "small" | "normal" | "large" | "xlarge" | "xxlarge" | undefined;
 }
 
-/** Output a status icon based on the current status of something. */
+/**
+ * Render the icon for a given status, coloured to match.
+ *
+ * - Picks a heroicon per status (`success`, `error`, `warning`, etc.), falling back to an info icon, and uses the animated `<Loading>` spinner for `"loading"`.
+ *
+ * @param status The status to represent (defaults to `"info"`).
+ * @param size Optional icon size (defaults to the current line height).
+ * @returns The status icon element.
+ * @example <StatusIcon status="error" size="large" />
+ * @see https://dhoulb.github.io/shelving/ui/misc/StatusIcon/StatusIcon
+ */
 export function StatusIcon({ status = "info", size }: StatusIconProps): ReactElement {
 	const Icon = STATUS_ICONS[status] ?? InformationCircleIcon;
 	return <Icon className={`${getModuleClass(styles, "icon", size)} ${getModuleClass(statusStyles, status)}`} />;

package/ui/misc/Tag.d.ts

@@ -3,9 +3,27 @@ import { type ClickableProps } from "../form/Clickable.js";
 import { type ColorVariants } from "../style/Color.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
+/**
+ * Styling variants accepted by `<Tag>` — status, colour, and typography options.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/TagVariants
+ */
 export interface TagVariants extends StatusVariants, ColorVariants, TypographyVariants {
 }
+/**
+ * Build the combined `className` string for a `<Tag>` from its styling variants.
+ *
+ * @param variants The status, colour, and typography variants to apply.
+ * @returns The merged tag `className` string.
+ * @example getTagClass({ success: true }) // "tag … status-success"
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/getTagClass
+ */
 export declare function getTagClass(variants: TagVariants): string;
+/**
+ * Props for `<Tag>` — `TagVariants` styling options plus `<Clickable>` props (`href`, `onClick`, `children`, etc.).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/TagProps
+ */
 export interface TagProps extends TagVariants, ClickableProps {
 }
 /**
@@ -13,7 +31,10 @@ export interface TagProps extends TagVariants, ClickableProps {
  * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
  *
+ * @param props Tag styling variants and clickable props.
+ * @returns The tag element.
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag
  */
 export declare function Tag(props: TagProps): ReactElement;

package/ui/misc/Tag.js

@@ -6,6 +6,14 @@ import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import TAG_CSS from "./Tag.module.css";
 const TAG_CLASS = getModuleClass(TAG_CSS, "tag");
+/**
+ * Build the combined `className` string for a `<Tag>` from its styling variants.
+ *
+ * @param variants The status, colour, and typography variants to apply.
+ * @returns The merged tag `className` string.
+ * @example getTagClass({ success: true }) // "tag … status-success"
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/getTagClass
+ */
 export function getTagClass(variants) {
     return getClass(TAG_CLASS, //
     getStatusClass(variants), getColorClass(variants), getTypographyClass(variants));
@@ -15,8 +23,11 @@ export function getTagClass(variants) {
  * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
  *
+ * @param props Tag styling variants and clickable props.
+ * @returns The tag element.
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag
  */
 export function Tag(props) {
     return _jsx(Clickable, { ...props, className: getTagClass(props) });

package/ui/misc/Tag.tsx

@@ -8,8 +8,21 @@ import TAG_CSS from "./Tag.module.css";
 
 const TAG_CLASS = getModuleClass(TAG_CSS, "tag");
 
+/**
+ * Styling variants accepted by `<Tag>` — status, colour, and typography options.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/TagVariants
+ */
 export interface TagVariants extends StatusVariants, ColorVariants, TypographyVariants {}
 
+/**
+ * Build the combined `className` string for a `<Tag>` from its styling variants.
+ *
+ * @param variants The status, colour, and typography variants to apply.
+ * @returns The merged tag `className` string.
+ * @example getTagClass({ success: true }) // "tag … status-success"
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/getTagClass
+ */
 export function getTagClass(variants: TagVariants) {
 	return getClass(
 		TAG_CLASS, //
@@ -19,6 +32,11 @@ export function getTagClass(variants: TagVariants) {
 	);
 }
 
+/**
+ * Props for `<Tag>` — `TagVariants` styling options plus `<Clickable>` props (`href`, `onClick`, `children`, etc.).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/TagProps
+ */
 export interface TagProps extends TagVariants, ClickableProps {}
 
 /**
@@ -26,8 +44,11 @@ export interface TagProps extends TagVariants, ClickableProps {}
  * - Delegates to `getClickable()` — renders as `<a>` when `href` is set, otherwise `<button>`.
  * - Accepts a status variant (`success`, `info`, `error`, etc.) _or_ a raw colour (`color="red"`, `color="purple"`, etc.).
  *
+ * @param props Tag styling variants and clickable props.
+ * @returns The tag element.
  * @example <Tag success>Active</Tag>
  * @example <Tag color="purple" href="/beta">Beta</Tag>
+ * @see https://dhoulb.github.io/shelving/ui/misc/Tag/Tag
  */
 export function Tag(props: TagProps): ReactElement {
 	return <Clickable {...props} className={getTagClass(props)} />;

package/ui/notice/Message.d.ts

@@ -1,9 +1,35 @@
 import { type ParagraphProps } from "../block/Paragraph.js";
 import { type ColorVariants } from "../style/Color.js";
 import { type StatusVariants } from "../style/Status.js";
+/**
+ * Base `className` applied to every `<Message>` paragraph.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/notice/Message/MESSAGE_CLASS
+ */
 export declare const MESSAGE_CLASS: string;
+/**
+ * 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 declare function Message({ children, ...props }: MessageProps): import("react").JSX.Element;
+/**
+ * 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 declare const LOADING_MESSAGE: import("react").JSX.Element;