shelving 1.236.0 → 1.236.2

package/ui/form/ButtonInputPopover.js

@@ -9,6 +9,11 @@ import { Popover } from "./Popover.js";
  * - 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 function ButtonInputPopover({ children: [buttonChildren, ...popoverChildren], //
 ...props }) {

package/ui/form/ButtonInputPopover.tsx

@@ -6,6 +6,11 @@ import { ButtonInput } from "./ButtonInput.js";
 import type { InputProps } from "./Input.js";
 import { Popover, 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;
 }
@@ -15,6 +20,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 function ButtonInputPopover({
 	children: [buttonChildren, ...popoverChildren], //

package/ui/form/ButtonPopover.d.ts

@@ -3,14 +3,24 @@
 import { type ReactElement } from "react";
 import { type ButtonVariants } from "./Button.js";
 import { type PopoverChildren } from "./Popover.js";
+/**
+ * Props for `ButtonPopover`, a button that toggles an adjacent popover.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonPopover/ButtonPopoverProps
+ */
 export interface ButtonPopoverProps extends ButtonVariants {
     children: PopoverChildren;
 }
 /**
- * An input button that, when clicked, shows a popover next to it when clicked or focused.
+ * A button that, when clicked, shows a popover next to it when clicked or focused.
  * - 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 `Button` variants and `children` whose first node is the button and the rest the popover.
+ * @returns A `Popover` wrapping a `Button` that toggles it open and closed.
+ * @example <ButtonPopover>{label}{panel}</ButtonPopover>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonPopover/ButtonPopover
  */
 export declare function ButtonPopover({ children: [buttonChildren, ...popoverChildren], //
 ...props }: ButtonPopoverProps): ReactElement;

package/ui/form/ButtonPopover.js

@@ -5,10 +5,15 @@ import { useState } from "react";
 import { Button } from "./Button.js";
 import { Popover } from "./Popover.js";
 /**
- * An input button that, when clicked, shows a popover next to it when clicked or focused.
+ * A button that, when clicked, shows a popover next to it when clicked or focused.
  * - 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 `Button` variants and `children` whose first node is the button and the rest the popover.
+ * @returns A `Popover` wrapping a `Button` that toggles it open and closed.
+ * @example <ButtonPopover>{label}{panel}</ButtonPopover>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonPopover/ButtonPopover
  */
 export function ButtonPopover({ children: [buttonChildren, ...popoverChildren], //
 ...props }) {

package/ui/form/ButtonPopover.tsx

@@ -5,15 +5,25 @@ import { type ReactElement, useState } from "react";
 import { Button, type ButtonVariants } from "./Button.js";
 import { Popover, type PopoverChildren } from "./Popover.js";
 
+/**
+ * Props for `ButtonPopover`, a button that toggles an adjacent popover.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonPopover/ButtonPopoverProps
+ */
 export interface ButtonPopoverProps extends ButtonVariants {
 	children: PopoverChildren;
 }
 
 /**
- * An input button that, when clicked, shows a popover next to it when clicked or focused.
+ * A button that, when clicked, shows a popover next to it when clicked or focused.
  * - 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 `Button` variants and `children` whose first node is the button and the rest the popover.
+ * @returns A `Popover` wrapping a `Button` that toggles it open and closed.
+ * @example <ButtonPopover>{label}{panel}</ButtonPopover>
+ * @see https://dhoulb.github.io/shelving/ui/form/ButtonPopover/ButtonPopover
  */
 export function ButtonPopover({
 	children: [buttonChildren, ...popoverChildren], //

package/ui/form/CheckboxInput.d.ts

@@ -2,7 +2,20 @@ import type { ReactElement } from "react";
 import { type FlexVariants } from "../style/Flex.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { type ValueInputProps } from "./Input.js";
+/**
+ * Props for `CheckboxInput`, a boolean-valued checkbox input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/CheckboxInput/CheckboxProps
+ */
 export interface CheckboxProps extends ValueInputProps<boolean>, OptionalChildProps, FlexVariants {
 }
-/** Checkbox element. */
+/**
+ * Checkbox input bound to a `boolean` value, rendered as a labelled `<input type="checkbox">`.
+ * - The label content comes from `children`, falling back to `placeholder`/`title`.
+ *
+ * @param props Props including `value`, `onValue`, label `children`, and `Flex` variants.
+ * @returns A `<label>` wrapping the checkbox and its label content.
+ * @example <CheckboxInput name="agree" value={agree} onValue={setAgree}>I agree</CheckboxInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/CheckboxInput/CheckboxInput
+ */
 export declare function CheckboxInput({ name, title, placeholder, required, disabled, message, value, onValue, children, ...variants }: CheckboxProps): ReactElement;

package/ui/form/CheckboxInput.js

@@ -3,7 +3,15 @@ import { notNullish } from "../../util/null.js";
 import { getFlexClass } from "../style/Flex.js";
 import { getClass } from "../util/css.js";
 import { CHECKBOX_CLASS, LABEL_INPUT_CLASS, PLACEHOLDER_CLASS } from "./Input.js";
-/** Checkbox element. */
+/**
+ * Checkbox input bound to a `boolean` value, rendered as a labelled `<input type="checkbox">`.
+ * - The label content comes from `children`, falling back to `placeholder`/`title`.
+ *
+ * @param props Props including `value`, `onValue`, label `children`, and `Flex` variants.
+ * @returns A `<label>` wrapping the checkbox and its label content.
+ * @example <CheckboxInput name="agree" value={agree} onValue={setAgree}>I agree</CheckboxInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/CheckboxInput/CheckboxInput
+ */
 export function CheckboxInput({ name, title, placeholder = title || "Yes", required = false, disabled = false, message = "", value = false, onValue, children, ...variants }) {
     const hasChildren = notNullish(children);
     return (_jsxs("label", { className: getClass(LABEL_INPUT_CLASS, getFlexClass(variants), hasChildren && PLACEHOLDER_CLASS), "aria-invalid": !!message, children: [_jsx("input", { name: name, type: "checkbox", defaultChecked: !!value, onChange: e => onValue?.(!!e.currentTarget.checked), required: required, disabled: disabled, title: message, className: CHECKBOX_CLASS }), _jsx("span", { children: hasChildren ? children : placeholder })] }));

package/ui/form/CheckboxInput.tsx

@@ -5,9 +5,22 @@ import { getClass } from "../util/css.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { CHECKBOX_CLASS, LABEL_INPUT_CLASS, PLACEHOLDER_CLASS, type ValueInputProps } from "./Input.js";
 
+/**
+ * Props for `CheckboxInput`, a boolean-valued checkbox input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/CheckboxInput/CheckboxProps
+ */
 export interface CheckboxProps extends ValueInputProps<boolean>, OptionalChildProps, FlexVariants {}
 
-/** Checkbox element. */
+/**
+ * Checkbox input bound to a `boolean` value, rendered as a labelled `<input type="checkbox">`.
+ * - The label content comes from `children`, falling back to `placeholder`/`title`.
+ *
+ * @param props Props including `value`, `onValue`, label `children`, and `Flex` variants.
+ * @returns A `<label>` wrapping the checkbox and its label content.
+ * @example <CheckboxInput name="agree" value={agree} onValue={setAgree}>I agree</CheckboxInput>
+ * @see https://dhoulb.github.io/shelving/ui/form/CheckboxInput/CheckboxInput
+ */
 export function CheckboxInput({
 	name,
 	title,

package/ui/form/ChoiceRadioInputs.d.ts

@@ -1,6 +1,11 @@
 import type { ReactElement } from "react";
 import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
 import type { ValueInputProps } from "./Input.js";
+/**
+ * Props for `ChoiceRadioInputs`, which renders a radio for each entry in a `ChoiceOptions` set.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ChoiceRadioInputs/ChoiceRadioInputsProps
+ */
 export interface ChoiceRadioInputsProps<T extends string> extends ValueInputProps<T> {
     /** Options for the radios. */
     options: ChoiceOptions<T>;
@@ -13,5 +18,10 @@ export interface ChoiceRadioInputsProps<T extends string> extends ValueInputProp
  * Output a list of `<RadioInput>` elements for each item in a set of `ChoiceOptions` in `{ key: title }` format.
  * - This is the same type a `ChoiceSchema` uses for its `.options` field.
  * - A `placeholder` option is shown at the bottom if `required=false`.
+ *
+ * @param props Props including the `options` set, current `value`, `onValue`, and `wrap`/`column` layout flags.
+ * @returns Element rendering one radio per option plus an optional empty placeholder radio.
+ * @example <ChoiceRadioInputs name="role" options={{ admin: "Admin", user: "User" }} value={role} onValue={setRole} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ChoiceRadioInputs/ChoiceRadioInputs
  */
 export declare function ChoiceRadioInputs<T extends string>(props: ChoiceRadioInputsProps<T>): ReactElement;

package/ui/form/ChoiceRadioInputs.tsx

@@ -8,6 +8,11 @@ import { RadioInput } from "./RadioInput.js";
 /** Maximum number of options to show in a row. */
 const MAX_ROW_OPTIONS = 2;
 
+/**
+ * Props for `ChoiceRadioInputs`, which renders a radio for each entry in a `ChoiceOptions` set.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/ChoiceRadioInputs/ChoiceRadioInputsProps
+ */
 export interface ChoiceRadioInputsProps<T extends string> extends ValueInputProps<T> {
 	/** Options for the radios. */
 	options: ChoiceOptions<T>;
@@ -21,6 +26,11 @@ export interface ChoiceRadioInputsProps<T extends string> extends ValueInputProp
  * Output a list of `<RadioInput>` elements for each item in a set of `ChoiceOptions` in `{ key: title }` format.
  * - This is the same type a `ChoiceSchema` uses for its `.options` field.
  * - A `placeholder` option is shown at the bottom if `required=false`.
+ *
+ * @param props Props including the `options` set, current `value`, `onValue`, and `wrap`/`column` layout flags.
+ * @returns Element rendering one radio per option plus an optional empty placeholder radio.
+ * @example <ChoiceRadioInputs name="role" options={{ admin: "Admin", user: "User" }} value={role} onValue={setRole} />
+ * @see https://dhoulb.github.io/shelving/ui/form/ChoiceRadioInputs/ChoiceRadioInputs
  */
 export function ChoiceRadioInputs<T extends string>(props: ChoiceRadioInputsProps<T>): ReactElement;
 export function ChoiceRadioInputs({

package/ui/form/Clickable.d.ts

@@ -2,13 +2,21 @@ import type { MouseEvent, ReactElement, ReactNode } from "react";
 import type { Path } from "../../util/path.js";
 import type { ImmutableURI, URIString } from "../../util/uri.js";
 import type { OptionalChildProps } from "../util/props.js";
-/***
+/**
  * Handler for a clickable `onClick` event.
  * - Returned value (if defined) is notified to the user using `notifySuccess()`
  * - Thrown value is notified to the user using `notifyError()`
+ *
+ * @param event The `MouseEvent` from the underlying `<button>`.
+ * @returns A `ReactNode` (shown as a success notice), nothing, or a promise of either.
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ClickableCallback
  */
 export type ClickableCallback = (event: MouseEvent<HTMLButtonElement>) => ReactNode | void | PromiseLike<ReactNode | void>;
-/** Props for a thing that can be clicked, either has a string `href` link or an `onClick` callback handler. */
+/**
+ * Props for a thing that can be clicked — either has a string `href` link or an `onClick` callback handler.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ClickableProps
+ */
 export interface ClickableProps extends OptionalChildProps {
     /** Whether the clickable is currently disabled. */
     disabled?: boolean | undefined;
@@ -23,14 +31,46 @@ export interface ClickableProps extends OptionalChildProps {
     /** Title shown on hover. */
     title?: string | undefined;
 }
+/**
+ * Props for a clickable that also accepts a `className` for styling.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/StylableClickableProps
+ */
 export interface StylableClickableProps extends ClickableProps {
     className?: string | undefined;
 }
-/** Return either a `<button>` or an `<a href="">` based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
+ * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
+ *
+ * @example <Clickable href="/about">About</Clickable>
+ * @example <Clickable onClick={save}>Save</Clickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/Clickable
+ */
 export declare function Clickable(props: StylableClickableProps): ReactElement;
-/** Return an `<a href="">` element. */
+/**
+ * Render an `<a href="">` element, resolving its `href` against the current page URL and marking it active when it matches.
+ * - The `href` is resolved against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
+ * - Sets `aria-current="page"` when the link points at the current URL.
+ *
+ * @example <LinkClickable href="/about" className="link">About</LinkClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/LinkClickable
+ */
 export declare function LinkClickable({ href, disabled, target, download, title, children, className, }: StylableClickableProps): ReactElement;
-/** Return a `<button>` element. */
+/**
+ * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
+ * - Notifies the user of the handler's returned value (success) or thrown value (error).
+ * - Disabled and ignores clicks while a previous click is still pending.
+ *
+ * @example <ButtonClickable onClick={save} className="btn">Save</ButtonClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ButtonClickable
+ */
 export declare function ButtonClickable({ onClick, disabled, title, children, className, }: StylableClickableProps): ReactElement;
+/**
+ * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
+ *
+ * @example <SpanClickable className="label">Static</SpanClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/SpanClickable
+ */
 export declare function SpanClickable({ title, children, //
 className, }: StylableClickableProps): ReactElement;

package/ui/form/Clickable.js

@@ -7,11 +7,25 @@ import { getLink } from "../../util/link.js";
 import { LOADING } from "../misc/Loading.js";
 import { requireMeta } from "../misc/MetaContext.js";
 import { callNotifiedElement } from "../util/notice.js";
-/** Return either a `<button>` or an `<a href="">` based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
+ * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
+ *
+ * @example <Clickable href="/about">About</Clickable>
+ * @example <Clickable onClick={save}>Save</Clickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/Clickable
+ */
 export function Clickable(props) {
     return "href" in props ? (_jsx(LinkClickable, { ...props })) : "onClick" in props ? (_jsx(ButtonClickable, { ...props })) : (_jsx(SpanClickable, { ...props }));
 }
-/** Return an `<a href="">` element. */
+/**
+ * Render an `<a href="">` element, resolving its `href` against the current page URL and marking it active when it matches.
+ * - The `href` is resolved against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
+ * - Sets `aria-current="page"` when the link points at the current URL.
+ *
+ * @example <LinkClickable href="/about" className="link">About</LinkClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/LinkClickable
+ */
 export function LinkClickable({ href, disabled = !href, target, download, title, children = "Go", className, }) {
     // Resolve `href` against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
     const { url, root } = requireMeta();
@@ -20,7 +34,14 @@ export function LinkClickable({ href, disabled = !href, target, download, title,
     const active = isURLActive(link, url);
     return (_jsx("a", { href: link?.href, title: title, download: download, target: target, className: className, "aria-current": active ? "page" : undefined, children: children }));
 }
-/** Return a `<button>` element. */
+/**
+ * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
+ * - Notifies the user of the handler's returned value (success) or thrown value (error).
+ * - Disabled and ignores clicks while a previous click is still pending.
+ *
+ * @example <ButtonClickable onClick={save} className="btn">Save</ButtonClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ButtonClickable
+ */
 export function ButtonClickable({ onClick, disabled = !onClick, title, children = "Click", className, }) {
     // Create a `BusyStore<undefined>` to keep track of the `onClick` call and any thrown errors.
     const store = useInstance(BusyStore, undefined);
@@ -35,6 +56,12 @@ export function ButtonClickable({ onClick, disabled = !onClick, title, children
                 }
             }, children: busy ? LOADING : children }));
 }
+/**
+ * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
+ *
+ * @example <SpanClickable className="label">Static</SpanClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/SpanClickable
+ */
 export function SpanClickable({ title, children = "Click", //
 className, }) {
     return (_jsx("span", { title: title, className: className, children: children }));

package/ui/form/Clickable.tsx

@@ -11,14 +11,22 @@ import { requireMeta } from "../misc/MetaContext.js";
 import { callNotifiedElement } from "../util/notice.js";
 import type { OptionalChildProps } from "../util/props.js";
 
-/***
+/**
  * Handler for a clickable `onClick` event.
  * - Returned value (if defined) is notified to the user using `notifySuccess()`
  * - Thrown value is notified to the user using `notifyError()`
+ *
+ * @param event The `MouseEvent` from the underlying `<button>`.
+ * @returns A `ReactNode` (shown as a success notice), nothing, or a promise of either.
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ClickableCallback
  */
 export type ClickableCallback = (event: MouseEvent<HTMLButtonElement>) => ReactNode | void | PromiseLike<ReactNode | void>;
 
-/** Props for a thing that can be clicked, either has a string `href` link or an `onClick` callback handler. */
+/**
+ * Props for a thing that can be clicked — either has a string `href` link or an `onClick` callback handler.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ClickableProps
+ */
 export interface ClickableProps extends OptionalChildProps {
 	/** Whether the clickable is currently disabled. */
 	disabled?: boolean | undefined;
@@ -34,11 +42,23 @@ export interface ClickableProps extends OptionalChildProps {
 	title?: string | undefined;
 }
 
+/**
+ * Props for a clickable that also accepts a `className` for styling.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/StylableClickableProps
+ */
 export interface StylableClickableProps extends ClickableProps {
 	className?: string | undefined;
 }
 
-/** Return either a `<button>` or an `<a href="">` based on whether an `onClick` or `href` prop is provided. */
+/**
+ * Render either a `<button>`, an `<a href="">`, or a plain `<span>` based on whether an `onClick` or `href` prop is provided.
+ * - `href` renders a `LinkClickable`; `onClick` renders a `ButtonClickable`; neither renders a `SpanClickable`.
+ *
+ * @example <Clickable href="/about">About</Clickable>
+ * @example <Clickable onClick={save}>Save</Clickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/Clickable
+ */
 export function Clickable(props: StylableClickableProps): ReactElement {
 	return "href" in props ? (
 		<LinkClickable {...props} />
@@ -49,7 +69,14 @@ export function Clickable(props: StylableClickableProps): ReactElement {
 	);
 }
 
-/** Return an `<a href="">` element. */
+/**
+ * Render an `<a href="">` element, resolving its `href` against the current page URL and marking it active when it matches.
+ * - The `href` is resolved against the current page URL and site root so site-absolute paths (`/foo`) honour the base subfolder.
+ * - Sets `aria-current="page"` when the link points at the current URL.
+ *
+ * @example <LinkClickable href="/about" className="link">About</LinkClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/LinkClickable
+ */
 export function LinkClickable({
 	href,
 	disabled = !href,
@@ -80,7 +107,14 @@ export function LinkClickable({
 	);
 }
 
-/** Return a `<button>` element. */
+/**
+ * Render a `<button>` element that runs its `onClick` handler through a `BusyStore` and shows a loading spinner while busy.
+ * - Notifies the user of the handler's returned value (success) or thrown value (error).
+ * - Disabled and ignores clicks while a previous click is still pending.
+ *
+ * @example <ButtonClickable onClick={save} className="btn">Save</ButtonClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/ButtonClickable
+ */
 export function ButtonClickable({
 	onClick,
 	disabled = !onClick,
@@ -116,6 +150,12 @@ export function ButtonClickable({
 	);
 }
 
+/**
+ * Render a non-interactive `<span>` element, used as the fallback when neither `href` nor `onClick` is provided.
+ *
+ * @example <SpanClickable className="label">Static</SpanClickable>
+ * @see https://dhoulb.github.io/shelving/ui/form/Clickable/SpanClickable
+ */
 export function SpanClickable({
 	title,
 	children = "Click", //

package/ui/form/DataInput.d.ts

@@ -2,8 +2,22 @@ import type { ReactElement } from "react";
 import type { Schemas } from "../../schema/Schema.js";
 import type { Data } from "../../util/data.js";
 import type { ValueInputProps } from "./Input.js";
+/**
+ * Props for `DataInput`, a composite input that edits an object of schema-validated sub-fields.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/DataInput/DataInputProps
+ */
 export interface DataInputProps<T extends Data> extends ValueInputProps<T> {
     /** Schema for the sub-fields of this input. */
     props: Schemas<T>;
 }
+/**
+ * Composite input that edits a data object by rendering a `SchemaInput` for each property schema.
+ * - Each sub-field is keyed by its property name and validated using the matching schema in `props`.
+ *
+ * @param props Props including the per-property `props` schemas, current `value`, and `onValue`.
+ * @returns Element rendering one input per property, laid out in a row or column.
+ * @example <DataInput name="address" props={addressSchemas} value={address} onValue={setAddress} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DataInput/DataInput
+ */
 export declare function DataInput<T extends Data>(props: DataInputProps<T>): ReactElement;

package/ui/form/DataInput.tsx

@@ -7,11 +7,25 @@ import { Row } from "../style/Flex.js";
 import type { ValueInputProps } from "./Input.js";
 import { SchemaInput } from "./SchemaInput.js";
 
+/**
+ * Props for `DataInput`, a composite input that edits an object of schema-validated sub-fields.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/DataInput/DataInputProps
+ */
 export interface DataInputProps<T extends Data> extends ValueInputProps<T> {
 	/** Schema for the sub-fields of this input. */
 	props: Schemas<T>;
 }
 
+/**
+ * Composite input that edits a data object by rendering a `SchemaInput` for each property schema.
+ * - Each sub-field is keyed by its property name and validated using the matching schema in `props`.
+ *
+ * @param props Props including the per-property `props` schemas, current `value`, and `onValue`.
+ * @returns Element rendering one input per property, laid out in a row or column.
+ * @example <DataInput name="address" props={addressSchemas} value={address} onValue={setAddress} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DataInput/DataInput
+ */
 export function DataInput<T extends Data>(props: DataInputProps<T>): ReactElement;
 export function DataInput({
 	// name,

package/ui/form/DateInput.d.ts

@@ -2,11 +2,25 @@ import type { ReactElement } from "react";
 import type { DateInputType } from "../../schema/DateSchema.js";
 import { type PossibleDate } from "../../util/date.js";
 import { type ValueInputProps } from "./Input.js";
+/**
+ * Props for `DateInput`, a date/time `<input>` that emits an ISO string value.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/DateInput/DateInputProps
+ */
 export interface DateInputProps extends ValueInputProps<string, PossibleDate> {
     min?: PossibleDate | undefined;
     max?: PossibleDate | undefined;
     input?: DateInputType | undefined;
     step?: number | undefined;
 }
+/**
+ * Date, time, or datetime input that accepts a `PossibleDate` and emits an ISO string value.
+ * - The `input` prop selects the underlying `<input type="date|time|datetime-local">` and matching string format.
+ *
+ * @param props Props including `value`, `onValue`, optional `min`/`max` bounds, `input` type, and `step`.
+ * @returns A native date/time `<input>` element.
+ * @example <DateInput name="dob" input="date" value={dob} onValue={setDob} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DateInput/DateInput
+ */
 export declare function DateInput({ name, title, placeholder, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
 required, disabled, message, value, onValue, min, max, input, step, }: DateInputProps): ReactElement;

package/ui/form/DateInput.js

@@ -7,6 +7,15 @@ const _DATE_TO_STRING = {
     date: getDateString, // YYYY-MM-DD
     time: getTimeString, // HH:MM:SS
 };
+/**
+ * Date, time, or datetime input that accepts a `PossibleDate` and emits an ISO string value.
+ * - The `input` prop selects the underlying `<input type="date|time|datetime-local">` and matching string format.
+ *
+ * @param props Props including `value`, `onValue`, optional `min`/`max` bounds, `input` type, and `step`.
+ * @returns A native date/time `<input>` element.
+ * @example <DateInput name="dob" input="date" value={dob} onValue={setDob} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DateInput/DateInput
+ */
 export function DateInput({ name, title = "", placeholder = title, // Placeholder must be defined or `:placeholder-shown` CSS rules won't show.
 required = false, disabled = false, message = "", value, onValue, min, max, input = "date", step, }) {
     const onChange = (e) => {

package/ui/form/DateInput.tsx

@@ -10,6 +10,11 @@ const _DATE_TO_STRING: { [K in DateInputType]: (d: PossibleDate | undefined) =>
 	time: getTimeString, // HH:MM:SS
 };
 
+/**
+ * Props for `DateInput`, a date/time `<input>` that emits an ISO string value.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/DateInput/DateInputProps
+ */
 export interface DateInputProps extends ValueInputProps<string, PossibleDate> {
 	min?: PossibleDate | undefined;
 	max?: PossibleDate | undefined;
@@ -17,6 +22,15 @@ export interface DateInputProps extends ValueInputProps<string, PossibleDate> {
 	step?: number | undefined;
 }
 
+/**
+ * Date, time, or datetime input that accepts a `PossibleDate` and emits an ISO string value.
+ * - The `input` prop selects the underlying `<input type="date|time|datetime-local">` and matching string format.
+ *
+ * @param props Props including `value`, `onValue`, optional `min`/`max` bounds, `input` type, and `step`.
+ * @returns A native date/time `<input>` element.
+ * @example <DateInput name="dob" input="date" value={dob} onValue={setDob} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DateInput/DateInput
+ */
 export function DateInput({
 	name,
 	title = "",

package/ui/form/DictionaryInput.d.ts

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

package/ui/form/DictionaryInput.tsx

@@ -13,6 +13,11 @@ import type { ValueInputProps } from "./Input.js";
 import { SchemaInput } from "./SchemaInput.js";
 import { TextInput } from "./TextInput.js";
 
+/**
+ * Props for `DictionaryInput`, a repeating input that edits a dictionary of schema-validated items.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/DictionaryInput/DictionaryInputProps
+ */
 export interface DictionaryInputProps<T> extends ValueInputProps<ImmutableDictionary<T>> {
 	one?: string;
 	many?: string;
@@ -22,6 +27,16 @@ export interface DictionaryInputProps<T> extends ValueInputProps<ImmutableDictio
 	items: Schema<T>;
 }
 
+/**
+ * Repeating input that edits a dictionary, with an editable key and schema-validated value per entry.
+ * - Each value is validated and rendered using the supplied `items` schema.
+ * - Enforces `min`/`max` entry count and offers add, remove, and clear controls.
+ *
+ * @param props Props including `value`, `onValue`, the `items` schema, and `min`/`max` entry bounds.
+ * @returns Element rendering one key/value row per entry plus add/clear controls.
+ * @example <DictionaryInput name="meta" items={STRING} value={meta} onValue={setMeta} />
+ * @see https://dhoulb.github.io/shelving/ui/form/DictionaryInput/DictionaryInput
+ */
 export function DictionaryInput<T>(props: DictionaryInputProps<T>): ReactElement;
 export function DictionaryInput({
 	name,

package/ui/form/Field.d.ts

@@ -1,5 +1,10 @@
 import type { ReactElement, ReactNode } from "react";
 import type { ChildProps } from "../util/props.js";
+/**
+ * Props for `Field`, a labelled wrapper around a form control.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Field/FieldProps
+ */
 export interface FieldProps extends ChildProps {
     title?: ReactNode | undefined;
     description?: ReactNode | undefined;