shelving 1.236.0 → 1.236.2

package/ui/docs/DocumentationButtons.d.ts

@@ -2,7 +2,11 @@ import type { ReactElement } from "react";
 import type { DocumentationElementProps } from "../../util/tree.js";
 import { type FlexVariants } from "../style/Flex.js";
 import { type SpaceVariants } from "../style/Space.js";
-/** Props for `DocumentationButtons` — the relational metadata of a documented symbol, plus block-space overrides. */
+/**
+ * Props for `DocumentationButtons` — the relational metadata of a documented symbol (`class`, `extends`, `implements`), plus block-space and flex overrides.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationButtons/DocumentationButtonsProps
+ */
 export interface DocumentationButtonsProps extends Pick<DocumentationElementProps, "class" | "extends" | "implements">, SpaceVariants, FlexVariants {
 }
 /**

package/ui/docs/DocumentationButtons.tsx

@@ -6,7 +6,11 @@ import { getSpaceClass, type SpaceVariants } from "../style/Space.js";
 import { TreeButton } from "../tree/TreeButton.js";
 import { getClass } from "../util/css.js";
 
-/** Props for `DocumentationButtons` — the relational metadata of a documented symbol, plus block-space overrides. */
+/**
+ * Props for `DocumentationButtons` — the relational metadata of a documented symbol (`class`, `extends`, `implements`), plus block-space and flex overrides.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationButtons/DocumentationButtonsProps
+ */
 export interface DocumentationButtonsProps
 	extends Pick<DocumentationElementProps, "class" | "extends" | "implements">,
 		SpaceVariants,

package/ui/docs/DocumentationCard.d.ts

@@ -1,8 +1,13 @@
 import type { ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/tree.js";
 /**
- * Card renderer for a `tree-documentation` element — a summary card.
+ * Card renderer for a `tree-documentation` element — a compact summary card linking to the symbol's detail page.
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
+ *
+ * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
+ * @returns A `<Card>` linking to the symbol's own page.
+ * @example <DocumentationCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationCard/DocumentationCard
  */
 export declare function DocumentationCard({ path, title, name, kind, description, signatures, class: _memberOf, ...props }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationCard.js

@@ -7,9 +7,14 @@ import { DocumentationButtons } from "./DocumentationButtons.js";
 import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKind.js";
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 /**
- * Card renderer for a `tree-documentation` element — a summary card.
+ * Card renderer for a `tree-documentation` element — a compact summary card linking to the symbol's detail page.
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
+ *
+ * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
+ * @returns A `<Card>` linking to the symbol's own page.
+ * @example <DocumentationCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationCard/DocumentationCard
  */
 export function DocumentationCard({ path, title, name, kind, description, signatures, 
 // Drop `class` so cards omit the "member of" relation — a member card almost always sits on its own class's page already.

package/ui/docs/DocumentationCard.tsx

@@ -9,9 +9,14 @@ import { DocumentationKind, getDocumentationKindColor } from "./DocumentationKin
 import { DocumentationSignatures } from "./DocumentationSignatures.js";
 
 /**
- * Card renderer for a `tree-documentation` element — a summary card.
+ * Card renderer for a `tree-documentation` element — a compact summary card linking to the symbol's detail page.
  * - Leads with the symbol's signature(s) as calm code blocks (`<DocumentationSignatures>`, same as the detail page), which already carry the name; falls back to the bare name for symbols with no signature (classes, interfaces, modules).
  * - The card is tinted by `kind` (colour carries the method/property/etc. distinction — no separate tag).
+ *
+ * @param props The documentation element's flattened props (`path`, `title`, `name`, `kind`, `description`, `signatures`, plus relational metadata); the `class` relation is dropped so member cards omit the redundant "member of" link.
+ * @returns A `<Card>` linking to the symbol's own page.
+ * @example <DocumentationCard {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationCard/DocumentationCard
  */
 export function DocumentationCard({
 	path,

package/ui/docs/DocumentationKind.d.ts

@@ -1,7 +1,11 @@
 import type { ReactElement } from "react";
 import { type TagProps } from "../misc/Tag.js";
 import type { UIColor } from "../style/Color.js";
-/** Props for `DocumentationKind`. */
+/**
+ * Props for `DocumentationKind` — a `TagProps` plus the documented symbol's `kind`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindProps
+ */
 export interface DocumentationKindProps extends TagProps {
     /** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
     readonly kind: string;
@@ -9,12 +13,20 @@ export interface DocumentationKindProps extends TagProps {
 /**
  * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
  * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ *
+ * @param kind The documented symbol's kind (e.g. `"function"`, `"class"`, `"method"`).
+ * @returns The matching `UIColor`, or `undefined` when the kind is unrecognised.
+ * @example getDocumentationKindColor("class") // "purple"
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/getDocumentationKindColor
  */
 export declare function getDocumentationKindColor(kind: string): UIColor | undefined;
 /**
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
  *
+ * @param props The kind to label plus any `TagProps` to forward to the underlying `<Tag>`.
+ * @returns A `<Tag>` showing the kind, tinted by its colour.
  * @example <DocumentationKind kind="function" />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKind
  */
 export declare function DocumentationKind({ kind, ...props }: DocumentationKindProps): ReactElement;

package/ui/docs/DocumentationKind.js

@@ -14,6 +14,11 @@ const KIND_COLOR = {
 /**
  * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
  * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ *
+ * @param kind The documented symbol's kind (e.g. `"function"`, `"class"`, `"method"`).
+ * @returns The matching `UIColor`, or `undefined` when the kind is unrecognised.
+ * @example getDocumentationKindColor("class") // "purple"
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/getDocumentationKindColor
  */
 export function getDocumentationKindColor(kind) {
     return KIND_COLOR[kind];
@@ -22,7 +27,10 @@ export function getDocumentationKindColor(kind) {
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
  *
+ * @param props The kind to label plus any `TagProps` to forward to the underlying `<Tag>`.
+ * @returns A `<Tag>` showing the kind, tinted by its colour.
  * @example <DocumentationKind kind="function" />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKind
  */
 export function DocumentationKind({ kind = "unknown", ...props }) {
     return (_jsx(Tag, { color: getDocumentationKindColor(kind), ...props, children: kind }));

package/ui/docs/DocumentationKind.tsx

@@ -2,7 +2,11 @@ import type { ReactElement } from "react";
 import { Tag, type TagProps } from "../misc/Tag.js";
 import type { UIColor } from "../style/Color.js";
 
-/** Props for `DocumentationKind`. */
+/**
+ * Props for `DocumentationKind` — a `TagProps` plus the documented symbol's `kind`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKindProps
+ */
 export interface DocumentationKindProps extends TagProps {
 	/** The documentation kind (e.g. `"function"`, `"class"`, `"interface"`, `"type"`, `"constant"`, `"method"`, `"property"`). */
 	readonly kind: string;
@@ -23,6 +27,11 @@ const KIND_COLOR: { readonly [K in string]?: UIColor } = {
 /**
  * Get the raw colour variant for a documented symbol's `kind`, or `undefined` for an unknown kind.
  * - Shared source of truth so the kind tag and its surrounding card pick the same hue.
+ *
+ * @param kind The documented symbol's kind (e.g. `"function"`, `"class"`, `"method"`).
+ * @returns The matching `UIColor`, or `undefined` when the kind is unrecognised.
+ * @example getDocumentationKindColor("class") // "purple"
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/getDocumentationKindColor
  */
 export function getDocumentationKindColor(kind: string): UIColor | undefined {
 	return KIND_COLOR[kind];
@@ -32,7 +41,10 @@ export function getDocumentationKindColor(kind: string): UIColor | undefined {
  * Colour-coded tag for a documented symbol's kind.
  * - Thin wrapper over `<Tag>` that maps the kind string to a raw colour variant.
  *
+ * @param props The kind to label plus any `TagProps` to forward to the underlying `<Tag>`.
+ * @returns A `<Tag>` showing the kind, tinted by its colour.
  * @example <DocumentationKind kind="function" />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationKind/DocumentationKind
  */
 export function DocumentationKind({ kind = "unknown", ...props }: DocumentationKindProps): ReactElement {
 	return (

package/ui/docs/DocumentationPage.d.ts

@@ -1,9 +1,14 @@
 import { type ReactNode } from "react";
 import type { DocumentationElementProps } from "../../util/tree.js";
 /**
- * Page renderer for a `tree-documentation` element.
+ * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
  * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
+ *
+ * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
+ * @returns A `<Page>` containing the symbol's full documentation.
+ * @example <DocumentationPage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
 export declare function DocumentationPage({ title, name, kind, description, content, signatures, params, returns, throws, examples, children, ...props }: DocumentationElementProps): ReactNode;

package/ui/docs/DocumentationPage.js

@@ -31,10 +31,15 @@ const KIND_SECTIONS = {
     property: "Properties",
 };
 /**
- * Page renderer for a `tree-documentation` element.
+ * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
  * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
+ *
+ * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
+ * @returns A `<Page>` containing the symbol's full documentation.
+ * @example <DocumentationPage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
 export function DocumentationPage({ title, name, kind = "unknown", description, content, signatures, params, returns, throws, examples, children, ...props }) {
     return (_jsx(Page, { title: title ?? name, description: description, children: _jsxs(Block, { color: getDocumentationKindColor(kind), children: [_jsx(Panel, { children: _jsxs(Header, { wide: true, children: [_jsx(TreeBreadcrumbs, {}), _jsx(Title, { children: _jsxs(Row, { left: true, wrap: true, children: [title ?? name, kind && _jsx(DocumentationKind, { kind: kind, size: "normal" })] }) }), _jsx(DocumentationButtons, { ...props })] }) }), signatures?.length || params?.length || returns?.length || throws?.length ? (_jsxs(Section, { wide: true, children: [_jsx(DocumentationSignatures, { signatures: signatures }), params?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Parameters" }), _jsx(Definitions, { children: params.map(({ name, type = DEFAULT_TYPE, description = "", optional }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsxs(Code, { size: "normal", children: [name, optional ? "?" : "", ": ", type] }) }), _jsx("dd", { children: description })] }, `${name}-${type}-${description}`))) })] })), returns?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Returns" }), _jsx(Definitions, { children: returns.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] })), throws?.length && (_jsxs(Section, { wide: true, children: [_jsx(Label, { children: "Throws" }), _jsx(Definitions, { children: throws.map(({ type = DEFAULT_TYPE, description = "" }) => (_jsxs(Fragment, { children: [_jsx("dt", { children: _jsx(Code, { size: "normal", children: type }) }), _jsx("dd", { children: description })] }, `${type}-${description}`))) })] }))] })) : null, content && (_jsx(Section, { wide: true, children: _jsx(Prose, { children: _jsx(Markup, { children: content }) }) })), examples?.length && (_jsxs(Section, { wide: true, children: [_jsx(Heading, { children: "Examples" }), examples.map(({ description }) => (_jsx(Preformatted, { children: description }, description)))] })), Object.entries(KIND_SECTIONS).map(([kind, label]) => {

package/ui/docs/DocumentationPage.tsx

@@ -35,10 +35,15 @@ const KIND_SECTIONS = {
 };
 
 /**
- * Page renderer for a `tree-documentation` element.
+ * Page renderer for a `tree-documentation` element — the full detail page for a documented symbol.
  * - Renders breadcrumbs, title (with kind + `readonly` tags), relational links (`member of`, `extends`, `implements`), signatures (one per overload), content, parameters, returns, throws, and examples.
  * - Child symbols are grouped by `kind` into card sections (Functions, Classes, Methods, Properties, …), each under its own heading.
  * - All sections are conditional — only render when they have entries.
+ *
+ * @param props The documentation element's flattened props (`title`, `name`, `kind`, `description`, `content`, `signatures`, `params`, `returns`, `throws`, `examples`, `children`, plus relational metadata).
+ * @returns A `<Page>` containing the symbol's full documentation.
+ * @example <DocumentationPage {...element.props} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationPage/DocumentationPage
  */
 export function DocumentationPage({
 	title,

package/ui/docs/DocumentationSignatures.d.ts

@@ -1,6 +1,10 @@
 import type { ReactNode } from "react";
 import type { ImmutableArray } from "../../util/array.js";
-/** Props for `DocumentationSignatures`. */
+/**
+ * Props for `DocumentationSignatures` — the type signatures to render, one block per overload.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationSignatures/DocumentationSignaturesProps
+ */
 export interface DocumentationSignaturesProps {
     /** Type signatures to render — one block per overload. */
     readonly signatures?: ImmutableArray<string> | undefined;
@@ -10,5 +14,10 @@ export interface DocumentationSignaturesProps {
  * - Shared by `DocumentationCard` and `DocumentationPage` so signatures render identically in both (calm code
  *   blocks, not a shouty heading).
  * - Renders nothing when there are no signatures.
+ *
+ * @param props The signatures to render — one block per overload.
+ * @returns One `<Preformatted>` block per signature, or `null` when there are none.
+ * @example <DocumentationSignatures signatures={["getArray<T>(arr: T[]): T"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationSignatures/DocumentationSignatures
  */
 export declare function DocumentationSignatures({ signatures }: DocumentationSignaturesProps): ReactNode;

package/ui/docs/DocumentationSignatures.js

@@ -5,6 +5,11 @@ import { Preformatted } from "../block/Preformatted.js";
  * - Shared by `DocumentationCard` and `DocumentationPage` so signatures render identically in both (calm code
  *   blocks, not a shouty heading).
  * - Renders nothing when there are no signatures.
+ *
+ * @param props The signatures to render — one block per overload.
+ * @returns One `<Preformatted>` block per signature, or `null` when there are none.
+ * @example <DocumentationSignatures signatures={["getArray<T>(arr: T[]): T"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationSignatures/DocumentationSignatures
  */
 export function DocumentationSignatures({ signatures }) {
     if (!signatures?.length)

package/ui/docs/DocumentationSignatures.tsx

@@ -2,7 +2,11 @@ import type { ReactNode } from "react";
 import type { ImmutableArray } from "../../util/array.js";
 import { Preformatted } from "../block/Preformatted.js";
 
-/** Props for `DocumentationSignatures`. */
+/**
+ * Props for `DocumentationSignatures` — the type signatures to render, one block per overload.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationSignatures/DocumentationSignaturesProps
+ */
 export interface DocumentationSignaturesProps {
 	/** Type signatures to render — one block per overload. */
 	readonly signatures?: ImmutableArray<string> | undefined;
@@ -13,6 +17,11 @@ export interface DocumentationSignaturesProps {
  * - Shared by `DocumentationCard` and `DocumentationPage` so signatures render identically in both (calm code
  *   blocks, not a shouty heading).
  * - Renders nothing when there are no signatures.
+ *
+ * @param props The signatures to render — one block per overload.
+ * @returns One `<Preformatted>` block per signature, or `null` when there are none.
+ * @example <DocumentationSignatures signatures={["getArray<T>(arr: T[]): T"]} />
+ * @see https://dhoulb.github.io/shelving/ui/docs/DocumentationSignatures/DocumentationSignatures
  */
 export function DocumentationSignatures({ signatures }: DocumentationSignaturesProps): ReactNode {
 	if (!signatures?.length) return null;

package/ui/form/ArrayInput.d.ts

@@ -2,6 +2,11 @@ import type { ReactElement } from "react";
 import type { Schema } from "../../schema/Schema.js";
 import { type ImmutableArray } from "../../util/array.js";
 import type { ValueInputProps } from "./Input.js";
+/**
+ * Props for `ArrayInput`, a repeating input that edits an array of schema-validated items.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayInput/ArrayInputProps
+ */
 export interface ArrayInputProps<T> extends ValueInputProps<ImmutableArray<T>> {
     one?: string;
     many?: string;
@@ -10,4 +15,14 @@ export interface ArrayInputProps<T> extends ValueInputProps<ImmutableArray<T>> {
     /** Schema for the items in the repeater. */
     items: Schema<T>;
 }
+/**
+ * Repeating input that edits an array of items, adding a `SchemaInput` row per item.
+ * - Each item is validated and rendered using the supplied `items` schema.
+ * - Enforces `min`/`max` length and offers add, remove, and clear controls.
+ *
+ * @param props Props including `value`, `onValue`, the `items` schema, and `min`/`max` length bounds.
+ * @returns Element rendering one input row per array item plus add/clear controls.
+ * @example <ArrayInput name="tags" items={STRING} value={tags} onValue={setTags} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayInput/ArrayInput
+ */
 export declare function ArrayInput<T>(props: ArrayInputProps<T>): ReactElement;

package/ui/form/ArrayInput.tsx

@@ -10,6 +10,11 @@ import { ButtonInput } from "./ButtonInput.js";
 import type { ValueInputProps } from "./Input.js";
 import { SchemaInput } from "./SchemaInput.js";
 
+/**
+ * Props for `ArrayInput`, a repeating input that edits an array of schema-validated items.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayInput/ArrayInputProps
+ */
 export interface ArrayInputProps<T> extends ValueInputProps<ImmutableArray<T>> {
 	one?: string;
 	many?: string;
@@ -19,6 +24,16 @@ export interface ArrayInputProps<T> extends ValueInputProps<ImmutableArray<T>> {
 	items: Schema<T>;
 }
 
+/**
+ * Repeating input that edits an array of items, adding a `SchemaInput` row per item.
+ * - Each item is validated and rendered using the supplied `items` schema.
+ * - Enforces `min`/`max` length and offers add, remove, and clear controls.
+ *
+ * @param props Props including `value`, `onValue`, the `items` schema, and `min`/`max` length bounds.
+ * @returns Element rendering one input row per array item plus add/clear controls.
+ * @example <ArrayInput name="tags" items={STRING} value={tags} onValue={setTags} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayInput/ArrayInput
+ */
 export function ArrayInput<T>(props: ArrayInputProps<T>): ReactElement;
 export function ArrayInput({
 	name,

package/ui/form/ArrayRadioInputs.d.ts

@@ -1,6 +1,11 @@
 import type { ReactElement, ReactNode } from "react";
 import type { ImmutableArray } from "../../util/array.js";
 import type { ValueInputProps } from "./Input.js";
+/**
+ * Props for `ArrayRadioInputs`, which renders a radio for each item in an array of values.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayRadioInputs/ArrayRadioInputsProps
+ */
 export interface ArrayRadioInputsProps<T> extends ValueInputProps<T> {
     /** Array of values to show in the list of radios. */
     items: ImmutableArray<T>;
@@ -11,5 +16,10 @@ export interface ArrayRadioInputsProps<T> extends ValueInputProps<T> {
  * Output a list of `<RadioInput>` elements for each item in an array.
  * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
  * - A `placeholder` option is shown at the bottom if `required=false`.
+ *
+ * @param props Props including the `items` array, current `value`, `onValue`, and an optional `formatter`.
+ * @returns Element rendering one radio per item plus an optional empty placeholder radio.
+ * @example <ArrayRadioInputs name="size" items={["s", "m", "l"]} value={size} onValue={setSize} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayRadioInputs/ArrayRadioInputs
  */
 export declare function ArrayRadioInputs<T>({ value, onValue, required, items, formatter, ...props }: ArrayRadioInputsProps<T>): ReactElement;

package/ui/form/ArrayRadioInputs.js

@@ -6,6 +6,11 @@ import { RadioInput } from "./RadioInput.js";
  * Output a list of `<RadioInput>` elements for each item in an array.
  * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
  * - A `placeholder` option is shown at the bottom if `required=false`.
+ *
+ * @param props Props including the `items` array, current `value`, `onValue`, and an optional `formatter`.
+ * @returns Element rendering one radio per item plus an optional empty placeholder radio.
+ * @example <ArrayRadioInputs name="size" items={["s", "m", "l"]} value={size} onValue={setSize} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayRadioInputs/ArrayRadioInputs
  */
 export function ArrayRadioInputs({ value, onValue, required = false, items, formatter = formatValue, ...props }) {
     return (_jsxs(Row, { column: true, children: [items.map((v, i) => {

package/ui/form/ArrayRadioInputs.tsx

@@ -5,6 +5,11 @@ import { Row } from "../style/Flex.js";
 import type { ValueInputProps } from "./Input.js";
 import { RadioInput } from "./RadioInput.js";
 
+/**
+ * Props for `ArrayRadioInputs`, which renders a radio for each item in an array of values.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayRadioInputs/ArrayRadioInputsProps
+ */
 export interface ArrayRadioInputsProps<T> extends ValueInputProps<T> {
 	/** Array of values to show in the list of radios. */
 	items: ImmutableArray<T>;
@@ -16,6 +21,11 @@ export interface ArrayRadioInputsProps<T> extends ValueInputProps<T> {
  * Output a list of `<RadioInput>` elements for each item in an array.
  * - The items can be any type, and can be formatted for output through an optional `formatter()` function.
  * - A `placeholder` option is shown at the bottom if `required=false`.
+ *
+ * @param props Props including the `items` array, current `value`, `onValue`, and an optional `formatter`.
+ * @returns Element rendering one radio per item plus an optional empty placeholder radio.
+ * @example <ArrayRadioInputs name="size" items={["s", "m", "l"]} value={size} onValue={setSize} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ArrayRadioInputs/ArrayRadioInputs
  */
 export function ArrayRadioInputs<T>({
 	value,

package/ui/form/Button.d.ts

@@ -4,7 +4,11 @@ import { type FlexVariants } from "../style/Flex.js";
 import { type StatusVariants } from "../style/Status.js";
 import { type TypographyVariants } from "../style/Typography.js";
 import { type ClickableProps } from "./Clickable.js";
-/** Variants for buttons. */
+/**
+ * Styling variants for a `Button`, combining flex, color, status, and typography options with button-specific toggles.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/ButtonVariants
+ */
 export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVariants, TypographyVariants {
     /** This is the default button in a form and should be displayed stronger. */
     strong?: boolean | undefined;
@@ -17,13 +21,25 @@ export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVaria
     /** Fill the available width instead of sizing to content (buttons are content-width by default). */
     full?: boolean | undefined;
 }
-/** Get the full className for a button. */
+/**
+ * Get the full combined `className` string for a button from its styling variants.
+ *
+ * @param variants The button styling variants (flex, color, status, typography, plus button toggles).
+ * @returns A space-separated `className` string combining all the resolved variant classes.
+ * @example getButtonClass({ color: "primary", small: true }) // "button …"
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/getButtonClass
+ */
 export declare function getButtonClass(variants: ButtonVariants): string;
 interface ButtonProps extends ButtonVariants, ClickableProps {
 }
 /**
- * Return either a `<button>` or an `<a href="">` styled as an button, based on whether an `onClick` or `href` prop is provided.
+ * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
+ *
+ * @example <Button onClick={save} color="primary">Save</Button>
+ * @example <Button href="/about">About</Button>
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/Button
  */
 export declare function Button(props: ButtonProps): ReactElement;
 export {};

package/ui/form/Button.js

@@ -6,13 +6,25 @@ import { getTypographyClass } from "../style/Typography.js";
 import { getClass, getModuleClass } from "../util/css.js";
 import BUTTON_CSS from "./Button.module.css";
 import { Clickable } from "./Clickable.js";
-/** Get the full className for a button. */
+/**
+ * Get the full combined `className` string for a button from its styling variants.
+ *
+ * @param variants The button styling variants (flex, color, status, typography, plus button toggles).
+ * @returns A space-separated `className` string combining all the resolved variant classes.
+ * @example getButtonClass({ color: "primary", small: true }) // "button …"
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/getButtonClass
+ */
 export function getButtonClass(variants) {
     return getClass(getModuleClass(BUTTON_CSS, "button", variants), getFlexClass(variants), getStatusClass(variants), getColorClass(variants), getTypographyClass(variants));
 }
 /**
- * Return either a `<button>` or an `<a href="">` styled as an button, based on whether an `onClick` or `href` prop is provided.
+ * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
+ *
+ * @example <Button onClick={save} color="primary">Save</Button>
+ * @example <Button href="/about">About</Button>
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/Button
  */
 export function Button(props) {
     return _jsx(Clickable, { ...props, className: getButtonClass(props) });

package/ui/form/Button.tsx

@@ -7,7 +7,11 @@ import { getClass, getModuleClass } from "../util/css.js";
 import BUTTON_CSS from "./Button.module.css";
 import { Clickable, type ClickableProps } from "./Clickable.js";
 
-/** Variants for buttons. */
+/**
+ * Styling variants for a `Button`, combining flex, color, status, and typography options with button-specific toggles.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/ButtonVariants
+ */
 export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVariants, TypographyVariants {
 	/** This is the default button in a form and should be displayed stronger. */
 	strong?: boolean | undefined;
@@ -21,7 +25,14 @@ export interface ButtonVariants extends FlexVariants, ColorVariants, StatusVaria
 	full?: boolean | undefined;
 }
 
-/** Get the full className for a button. */
+/**
+ * Get the full combined `className` string for a button from its styling variants.
+ *
+ * @param variants The button styling variants (flex, color, status, typography, plus button toggles).
+ * @returns A space-separated `className` string combining all the resolved variant classes.
+ * @example getButtonClass({ color: "primary", small: true }) // "button …"
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/getButtonClass
+ */
 export function getButtonClass(variants: ButtonVariants): string {
 	return getClass(
 		getModuleClass(BUTTON_CSS, "button", variants),
@@ -35,8 +46,13 @@ export function getButtonClass(variants: ButtonVariants): string {
 interface ButtonProps extends ButtonVariants, ClickableProps {}
 
 /**
- * Return either a `<button>` or an `<a href="">` styled as an button, based on whether an `onClick` or `href` prop is provided.
+ * Render either a `<button>` or an `<a href="">` styled as a button, based on whether an `onClick` or `href` prop is provided.
  * - Content-width by default (never grows); it won't shrink below its label. Pass `full` to fill the available width.
+ * - Accepts all `ButtonVariants` styling props plus the `ClickableProps` (`onClick`, `href`, `disabled`, etc.).
+ *
+ * @example <Button onClick={save} color="primary">Save</Button>
+ * @example <Button href="/about">About</Button>
+ * @see https://dhoulb.github.io/shelving/ui/form/Button/Button
  */
 export function Button(props: ButtonProps): ReactElement {
 	return <Clickable {...props} className={getButtonClass(props)} />;

package/ui/form/ButtonInput.d.ts

@@ -2,7 +2,20 @@ import type { ReactElement } from "react";
 import { type FlexVariants } from "../style/Flex.js";
 import { type ClickableProps } from "./Clickable.js";
 import { type InputProps } from "./Input.js";
+/**
+ * Props for `ButtonInput`, a clickable element styled to match form inputs.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInput/ButtonInputProps
+ */
 export interface ButtonInputProps extends InputProps, ClickableProps, FlexVariants {
 }
-/** Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided.
+ * - Falls back to rendering the `placeholder` when no `children`/`title` content is supplied.
+ *
+ * @param props Props including `title`/`placeholder` content plus `Clickable` and `Flex` variants.
+ * @returns A `Clickable` element styled with the button-input class.
+ * @example <ButtonInput name="choose" onClick={open}>Choose…</ButtonInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInput/ButtonInput
+ */
 export declare function ButtonInput({ title, placeholder, children, ...props }: ButtonInputProps): ReactElement;

package/ui/form/ButtonInput.js

@@ -4,7 +4,15 @@ import { getFlexClass } from "../style/Flex.js";
 import { getClass } from "../util/css.js";
 import { Clickable } from "./Clickable.js";
 import { BUTTON_INPUT_CLASS, PLACEHOLDER_CLASS } from "./Input.js";
-/** Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided.
+ * - Falls back to rendering the `placeholder` when no `children`/`title` content is supplied.
+ *
+ * @param props Props including `title`/`placeholder` content plus `Clickable` and `Flex` variants.
+ * @returns A `Clickable` element styled with the button-input class.
+ * @example <ButtonInput name="choose" onClick={open}>Choose…</ButtonInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInput/ButtonInput
+ */
 export function ButtonInput({ title, placeholder, children = title, ...props }) {
     const hasChildren = notNullish(children);
     return (_jsx(Clickable, { ...props, className: getClass(BUTTON_INPUT_CLASS, getFlexClass(props), hasChildren && PLACEHOLDER_CLASS), children: hasChildren ? children : placeholder }));

package/ui/form/ButtonInput.tsx

@@ -5,9 +5,22 @@ import { getClass } from "../util/css.js";
 import { Clickable, type ClickableProps } from "./Clickable.js";
 import { BUTTON_INPUT_CLASS, type InputProps, PLACEHOLDER_CLASS } from "./Input.js";
 
+/**
+ * Props for `ButtonInput`, a clickable element styled to match form inputs.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInput/ButtonInputProps
+ */
 export interface ButtonInputProps extends InputProps, ClickableProps, FlexVariants {}
 
-/** Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Return either a `<button>` or an `<a href="">` styled as an input, based on whether an `onClick` or `href` prop is provided.
+ * - Falls back to rendering the `placeholder` when no `children`/`title` content is supplied.
+ *
+ * @param props Props including `title`/`placeholder` content plus `Clickable` and `Flex` variants.
+ * @returns A `Clickable` element styled with the button-input class.
+ * @example <ButtonInput name="choose" onClick={open}>Choose…</ButtonInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInput/ButtonInput
+ */
 export function ButtonInput({ title, placeholder, children = title, ...props }: ButtonInputProps): ReactElement {
 	const hasChildren = notNullish(children);
 	return (

package/ui/form/ButtonInputPopover.d.ts

@@ -3,6 +3,11 @@
 import { type ReactElement } from "react";
 import type { InputProps } from "./Input.js";
 import { type PopoverChildren } from "./Popover.js";
+/**
+ * Props for `ButtonInputPopover`, an input button that toggles an adjacent popover.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInputPopover/ButtonInputPopoverProps
+ */
 export interface ButtonInputPopoverProps extends InputProps {
     children: PopoverChildren;
 }
@@ -11,6 +16,11 @@ export interface ButtonInputPopoverProps extends InputProps {
  * - The first element passed to `children` is used as the content for the button, the rest is the content of the popover.
  *
  * DH: Would love to use new HTML `popover="auto"` functionality for this but the anchor positioning it needs is not supported everywhere yet.
+ *
+ * @param props Props including the input `name` and `children` whose first node is the button and the rest the popover.
+ * @returns A `Popover` wrapping a `ButtonInput` that toggles it open and closed.
+ * @example <ButtonInputPopover name="filter">{label}{panel}</ButtonInputPopover>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonInputPopover/ButtonInputPopover
  */
 export declare function ButtonInputPopover({ children: [buttonChildren, ...popoverChildren], //
 ...props }: ButtonInputPopoverProps): ReactElement;