shelving 1.236.0 → 1.236.2

package/ui/form/Field.tsx

@@ -4,6 +4,11 @@ import { getClass } from "../util/css.js";
 import type { ChildProps } from "../util/props.js";
 import styles from "./Field.module.css";
 
+/**
+ * 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;

package/ui/form/FileInput.d.ts

@@ -1,7 +1,21 @@
 import type { ReactElement } from "react";
 import type { FileTypes } from "../../util/file.js";
 import { type ValueInputProps } from "./Input.js";
+/**
+ * Props for `FileInput`, an `<input type="file">` that emits the selected `File`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FileInput/FileInputProps
+ */
 export interface FileInputProps extends ValueInputProps<string | File> {
     types?: FileTypes | undefined;
 }
+/**
+ * File picker input that emits the selected `File` through `onValue`.
+ * - The optional `types` dictionary restricts the picker's accepted file types.
+ *
+ * @param props Props including `onValue`, accepted `types`, and standard input flags.
+ * @returns A native `<input type="file">` element.
+ * @example <FileInput name="avatar" types={{ png: "image/png" }} onValue={setFile} />
+ * @see https://dhoulb.github.io/shelving/ui/form/FileInput/FileInput
+ */
 export declare function FileInput({ name, title, placeholder, required, disabled, message, onValue, types, }: FileInputProps): ReactElement;

package/ui/form/FileInput.js

@@ -1,5 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { INPUT_CLASS } from "./Input.js";
+/**
+ * File picker input that emits the selected `File` through `onValue`.
+ * - The optional `types` dictionary restricts the picker's accepted file types.
+ *
+ * @param props Props including `onValue`, accepted `types`, and standard input flags.
+ * @returns A native `<input type="file">` element.
+ * @example <FileInput name="avatar" types={{ png: "image/png" }} onValue={setFile} />
+ * @see https://dhoulb.github.io/shelving/ui/form/FileInput/FileInput
+ */
 export function FileInput({ name, title, placeholder = title, required = false, disabled = false, message, 
 // value,
 onValue, types = {}, }) {

package/ui/form/FileInput.tsx

@@ -2,10 +2,24 @@ import type { ReactElement, SyntheticEvent } from "react";
 import type { FileTypes } from "../../util/file.js";
 import { INPUT_CLASS, type ValueInputProps } from "./Input.js";
 
+/**
+ * Props for `FileInput`, an `<input type="file">` that emits the selected `File`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FileInput/FileInputProps
+ */
 export interface FileInputProps extends ValueInputProps<string | File> {
 	types?: FileTypes | undefined;
 }
 
+/**
+ * File picker input that emits the selected `File` through `onValue`.
+ * - The optional `types` dictionary restricts the picker's accepted file types.
+ *
+ * @param props Props including `onValue`, accepted `types`, and standard input flags.
+ * @returns A native `<input type="file">` element.
+ * @example <FileInput name="avatar" types={{ png: "image/png" }} onValue={setFile} />
+ * @see https://dhoulb.github.io/shelving/ui/form/FileInput/FileInput
+ */
 export function FileInput({
 	name,
 	title,

package/ui/form/Form.d.ts

@@ -7,11 +7,18 @@ import { type NoticeCallback } from "../util/notice.js";
 import type { OptionalChildProps } from "../util/props.js";
 import { FormStore } from "./FormStore.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()`
+ * Callback invoked when a `Form` is submitted with its validated data.
+ * - Returned value (if defined) is notified to the user using `notifySuccess()`.
+ * - Thrown value is notified to the user using `notifyError()`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/FormCallback
  */
 export type FormCallback<T extends Data> = (data: T, event: SubmitEvent<HTMLFormElement>) => ReactNode | void | PromiseLike<ReactNode | void>;
+/**
+ * Props for `Form`, the schema-driven form wrapper component.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/FormProps
+ */
 export interface FormProps<T extends Data> extends OptionalChildProps {
     /** Schema for the form. */
     schema: DataSchema<T>;
@@ -24,10 +31,52 @@ export interface FormProps<T extends Data> extends OptionalChildProps {
     /** Initial set of messages for the form as either a dictionary or a string with `fieldName:` style messages. */
     messages?: ImmutableDictionary<string> | string | undefined;
 }
+/**
+ * Schema-driven form that creates a `FormStore`, provides it via `FormContext`, and validates/submits on submit.
+ * - Renders its fields and footer by default, or custom `children` that read the form via hooks.
+ * - Closes a parent `<dialog>` automatically on successful submit.
+ *
+ * @param props Props including `schema`, initial `data`, `onSubmit`, `submit` content, and initial `messages`.
+ * @returns A `<form>` element wrapping the fields in a `FormContext` provider.
+ * @example <Form schema={USER_SCHEMA} onSubmit={save} />
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/Form
+ */
 export declare function Form<T extends Data>(props: FormProps<T>): ReactElement;
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a form submit callback and publish success/error notices based on its return or thrown value.
+ * - Strings returned are shown as success notices; thrown values are routed through `notifyThrownForm()`.
+ * - Async callbacks are awaited via `awaitNotifiedForm()`.
+ *
+ * @param value The validated form data passed to the callback.
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param callback Optional callback to run with the value and extra args.
+ * @param args Additional arguments forwarded to the callback.
+ * @returns `true` on success, `false` on failure (or a `Promise` resolving to one).
+ * @example callNotifiedForm(data, store, formEl, onSubmit, event)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/callNotifiedForm
+ */
 export declare function callNotifiedForm<T extends Data, A extends Arguments>(value: T, store: FormStore<T>, form: HTMLFormElement, callback?: NoticeCallback<[T, ...A]>, ...args: A): boolean | Promise<boolean>;
-/** Await a value that publishes "success" or "error" notices to a form */
+/**
+ * Await a pending submit result and publish a success or error notice to a form once it settles.
+ *
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param pending The pending result to await.
+ * @returns A `Promise` resolving to `true` on success or `false` on failure.
+ * @example await awaitNotifiedForm(store, formEl, pending)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/awaitNotifiedForm
+ */
 export declare function awaitNotifiedForm<T extends Data>(store: FormStore<T>, form: HTMLFormElement, pending: PromiseLike<ReactNode | undefined | void>): Promise<boolean>;
-/** Notify the user about a thrown value during a submit (if thrown value is a string then save it as messages instead. */
+/**
+ * Notify the user about a value thrown during submit, storing string errors as form field messages.
+ * - Assigning a string `reason` to the store splits it into per-field messages instead of a global notice.
+ *
+ * @param store The `FormStore` the thrown value is recorded on.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param thrown The value thrown during submit.
+ * @returns Always `false`, signalling the submit failed.
+ * @example notifyThrownForm(store, formEl, thrown)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/notifyThrownForm
+ */
 export declare function notifyThrownForm<T extends Data>(store: FormStore<T>, form: HTMLFormElement, thrown: unknown): false;

package/ui/form/Form.js

@@ -25,7 +25,20 @@ export function Form({ schema, data: initialData, onSubmit, submit, messages, ch
                 dialog?.close();
         }, className: styles.form, noValidate: true, children: _jsx("fieldset", { className: styles.fieldset, disabled: busy, children: _jsx(FormContext, { value: store, children: children }) }) }, store.key));
 }
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a form submit callback and publish success/error notices based on its return or thrown value.
+ * - Strings returned are shown as success notices; thrown values are routed through `notifyThrownForm()`.
+ * - Async callbacks are awaited via `awaitNotifiedForm()`.
+ *
+ * @param value The validated form data passed to the callback.
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param callback Optional callback to run with the value and extra args.
+ * @param args Additional arguments forwarded to the callback.
+ * @returns `true` on success, `false` on failure (or a `Promise` resolving to one).
+ * @example callNotifiedForm(data, store, formEl, onSubmit, event)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/callNotifiedForm
+ */
 export function callNotifiedForm(value, store, form, callback, ...args) {
     try {
         const result = callback?.(value, ...args);
@@ -39,7 +52,16 @@ export function callNotifiedForm(value, store, form, callback, ...args) {
         return notifyThrownForm(store, form, thrown);
     }
 }
-/** Await a value that publishes "success" or "error" notices to a form */
+/**
+ * Await a pending submit result and publish a success or error notice to a form once it settles.
+ *
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param pending The pending result to await.
+ * @returns A `Promise` resolving to `true` on success or `false` on failure.
+ * @example await awaitNotifiedForm(store, formEl, pending)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/awaitNotifiedForm
+ */
 export async function awaitNotifiedForm(store, form, pending) {
     try {
         const result = await pending;
@@ -51,7 +73,17 @@ export async function awaitNotifiedForm(store, form, pending) {
         return notifyThrownForm(store, form, thrown);
     }
 }
-/** Notify the user about a thrown value during a submit (if thrown value is a string then save it as messages instead. */
+/**
+ * Notify the user about a value thrown during submit, storing string errors as form field messages.
+ * - Assigning a string `reason` to the store splits it into per-field messages instead of a global notice.
+ *
+ * @param store The `FormStore` the thrown value is recorded on.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param thrown The value thrown during submit.
+ * @returns Always `false`, signalling the submit failed.
+ * @example notifyThrownForm(store, formEl, thrown)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/notifyThrownForm
+ */
 export function notifyThrownForm(store, form, thrown) {
     store.reason = thrown;
     const reason = store.reason;

package/ui/form/Form.tsx

@@ -15,15 +15,22 @@ import { FormFooter } from "./FormFooter.js";
 import { FormStore } from "./FormStore.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()`
+ * Callback invoked when a `Form` is submitted with its validated data.
+ * - Returned value (if defined) is notified to the user using `notifySuccess()`.
+ * - Thrown value is notified to the user using `notifyError()`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/FormCallback
  */
 export type FormCallback<T extends Data> = (
 	data: T,
 	event: SubmitEvent<HTMLFormElement>,
 ) => ReactNode | void | PromiseLike<ReactNode | void>;
 
+/**
+ * Props for `Form`, the schema-driven form wrapper component.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/FormProps
+ */
 export interface FormProps<T extends Data> extends OptionalChildProps {
 	/** Schema for the form. */
 	schema: DataSchema<T>;
@@ -37,6 +44,16 @@ export interface FormProps<T extends Data> extends OptionalChildProps {
 	messages?: ImmutableDictionary<string> | string | undefined;
 }
 
+/**
+ * Schema-driven form that creates a `FormStore`, provides it via `FormContext`, and validates/submits on submit.
+ * - Renders its fields and footer by default, or custom `children` that read the form via hooks.
+ * - Closes a parent `<dialog>` automatically on successful submit.
+ *
+ * @param props Props including `schema`, initial `data`, `onSubmit`, `submit` content, and initial `messages`.
+ * @returns A `<form>` element wrapping the fields in a `FormContext` provider.
+ * @example <Form schema={USER_SCHEMA} onSubmit={save} />
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/Form
+ */
 export function Form<T extends Data>(props: FormProps<T>): ReactElement;
 export function Form({
 	schema,
@@ -83,7 +100,20 @@ export function Form({
 	);
 }
 
-/** Callback that publishes notices to an element (defaults to the window) if it returns or throws "string" */
+/**
+ * Run a form submit callback and publish success/error notices based on its return or thrown value.
+ * - Strings returned are shown as success notices; thrown values are routed through `notifyThrownForm()`.
+ * - Async callbacks are awaited via `awaitNotifiedForm()`.
+ *
+ * @param value The validated form data passed to the callback.
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param callback Optional callback to run with the value and extra args.
+ * @param args Additional arguments forwarded to the callback.
+ * @returns `true` on success, `false` on failure (or a `Promise` resolving to one).
+ * @example callNotifiedForm(data, store, formEl, onSubmit, event)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/callNotifiedForm
+ */
 export function callNotifiedForm<T extends Data, A extends Arguments>(
 	value: T,
 	store: FormStore<T>,
@@ -101,7 +131,16 @@ export function callNotifiedForm<T extends Data, A extends Arguments>(
 	}
 }
 
-/** Await a value that publishes "success" or "error" notices to a form */
+/**
+ * Await a pending submit result and publish a success or error notice to a form once it settles.
+ *
+ * @param store The `FormStore` the form is bound to.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param pending The pending result to await.
+ * @returns A `Promise` resolving to `true` on success or `false` on failure.
+ * @example await awaitNotifiedForm(store, formEl, pending)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/awaitNotifiedForm
+ */
 export async function awaitNotifiedForm<T extends Data>(
 	store: FormStore<T>,
 	form: HTMLFormElement,
@@ -116,7 +155,17 @@ export async function awaitNotifiedForm<T extends Data>(
 	}
 }
 
-/** Notify the user about a thrown value during a submit (if thrown value is a string then save it as messages instead. */
+/**
+ * Notify the user about a value thrown during submit, storing string errors as form field messages.
+ * - Assigning a string `reason` to the store splits it into per-field messages instead of a global notice.
+ *
+ * @param store The `FormStore` the thrown value is recorded on.
+ * @param form The underlying `HTMLFormElement` notices are anchored to.
+ * @param thrown The value thrown during submit.
+ * @returns Always `false`, signalling the submit failed.
+ * @example notifyThrownForm(store, formEl, thrown)
+ * @see https://dhoulb.github.io/shelving/ui/form/Form/notifyThrownForm
+ */
 export function notifyThrownForm<T extends Data>(store: FormStore<T>, form: HTMLFormElement, thrown: unknown): false {
 	store.reason = thrown;
 	const reason = store.reason;

package/ui/form/FormContext.d.ts

@@ -3,11 +3,32 @@ import type { Data } from "../../util/data.js";
 import type { AnyCaller } from "../../util/function.js";
 import type { FormStore } from "./FormStore.js";
 import { type SchemaInputProps } from "./SchemaInput.js";
-/** Context for current form. */
+/**
+ * React context holding the current `FormStore`, provided by the `Form` component.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/FormContext
+ */
 export declare const FormContext: import("react").Context<FormStore<Data> | undefined>;
-/** Use the current form context. */
+/**
+ * Hook that returns the current form's `FormStore` from context.
+ *
+ * @param caller Function to attribute the error to if no form context is found.
+ * @returns The current `FormStore` instance.
+ * @throws `RequiredError` if called outside a `Form` component.
+ * @example const form = requireForm();
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/requireForm
+ */
 export declare function requireForm<T extends Data = Data>(caller?: AnyCaller): FormStore<T>;
-/** Use the props for a field of a form. */
+/**
+ * Hook that returns the input props for a single named field of a form.
+ * - Subscribes to the form store so the field re-renders when its value or message changes.
+ *
+ * @param name Name of the field to read props for.
+ * @param form Form store to read from, defaulting to the current form context.
+ * @returns Props (`name`, `schema`, `value`, `onValue`, `message`, `required`) ready to spread onto an input.
+ * @example const field = useField("email");
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/useField
+ */
 export declare function useField<T, I = never>(name: string, form?: FormStore<{
     [name: string]: T;
 }>): SchemaInputProps<Schema<T>, I>;

package/ui/form/FormContext.js

@@ -2,7 +2,11 @@ import { createContext } from "react";
 import { useStore } from "../../react/useStore.js";
 import { requireContext } from "../util/context.js";
 import { isSchemaRequired } from "./SchemaInput.js";
-/** Context for current form. */
+/**
+ * React context holding the current `FormStore`, provided by the `Form` component.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/FormContext
+ */
 export const FormContext = createContext(undefined);
 FormContext.displayName = "FormContext";
 export function requireForm() {

package/ui/form/FormContext.tsx

@@ -7,17 +7,38 @@ import { requireContext } from "../util/context.js";
 import type { FormStore } from "./FormStore.js";
 import { isSchemaRequired, type SchemaInputProps } from "./SchemaInput.js";
 
-/** Context for current form. */
+/**
+ * React context holding the current `FormStore`, provided by the `Form` component.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/FormContext
+ */
 export const FormContext = createContext<FormStore<Data> | undefined>(undefined);
 FormContext.displayName = "FormContext";
 
-/** Use the current form context. */
+/**
+ * Hook that returns the current form's `FormStore` from context.
+ *
+ * @param caller Function to attribute the error to if no form context is found.
+ * @returns The current `FormStore` instance.
+ * @throws `RequiredError` if called outside a `Form` component.
+ * @example const form = requireForm();
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/requireForm
+ */
 export function requireForm<T extends Data = Data>(caller?: AnyCaller): FormStore<T>;
 export function requireForm(): FormStore<Data> {
 	return requireContext(FormContext, requireForm);
 }
 
-/** Use the props for a field of a form. */
+/**
+ * Hook that returns the input props for a single named field of a form.
+ * - Subscribes to the form store so the field re-renders when its value or message changes.
+ *
+ * @param name Name of the field to read props for.
+ * @param form Form store to read from, defaulting to the current form context.
+ * @returns Props (`name`, `schema`, `value`, `onValue`, `message`, `required`) ready to spread onto an input.
+ * @example const field = useField("email");
+ * @see https://dhoulb.github.io/shelving/ui/form/FormContext/useField
+ */
 export function useField<T, I = never>(name: string, form?: FormStore<{ [name: string]: T }>): SchemaInputProps<Schema<T>, I>;
 export function useField(name: string, form: FormStore<Data> = requireForm(useField)): SchemaInputProps<Schema<unknown>> {
 	useStore(form);

package/ui/form/FormFields.d.ts

@@ -1,6 +1,19 @@
 import type { ReactElement } from "react";
 import type { InputProps } from "./Input.js";
-/** Show a `<Field>` for a named property in the current form. */
+/**
+ * Show a `<Field>` (label, input, and message) for a single named property of the current form.
+ *
+ * @param props Input props including the field `name`.
+ * @returns A `<Field>` wrapping a `SchemaInput` bound to the named field.
+ * @example <FormField name="email" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormField
+ */
 export declare function FormField({ name, ...props }: InputProps): ReactElement;
-/** List of `<Field>` elements for every schema property in the current form. */
+/**
+ * Show a `<Field>` for every property in the current form's schema.
+ *
+ * @returns A fragment of `FormField` elements, one per schema property.
+ * @example <FormFields />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormFields
+ */
 export declare function FormFields(): ReactElement;

package/ui/form/FormFields.js

@@ -3,13 +3,26 @@ import { useStore } from "../../react/useStore.js";
 import { Field } from "./Field.js";
 import { requireForm, useField } from "./FormContext.js";
 import { SchemaInput } from "./SchemaInput.js";
-/** Show a `<Field>` for a named property in the current form. */
+/**
+ * Show a `<Field>` (label, input, and message) for a single named property of the current form.
+ *
+ * @param props Input props including the field `name`.
+ * @returns A `<Field>` wrapping a `SchemaInput` bound to the named field.
+ * @example <FormField name="email" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormField
+ */
 export function FormField({ name, ...props }) {
     const field = useField(name);
     const { schema, message } = field;
     return (_jsx(Field, { ...schema, message: message, required: props.required, children: _jsx(SchemaInput, { ...field, ...props }) }));
 }
-/** List of `<Field>` elements for every schema property in the current form. */
+/**
+ * Show a `<Field>` for every property in the current form's schema.
+ *
+ * @returns A fragment of `FormField` elements, one per schema property.
+ * @example <FormFields />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormFields
+ */
 export function FormFields() {
     const form = useStore(requireForm());
     return (_jsx(_Fragment, { children: Object.keys(form.schema.props).map(name => (_jsx(FormField, { name: name }, name))) }));

package/ui/form/FormFields.tsx

@@ -5,7 +5,14 @@ import { requireForm, useField } from "./FormContext.js";
 import type { InputProps } from "./Input.js";
 import { SchemaInput } from "./SchemaInput.js";
 
-/** Show a `<Field>` for a named property in the current form. */
+/**
+ * Show a `<Field>` (label, input, and message) for a single named property of the current form.
+ *
+ * @param props Input props including the field `name`.
+ * @returns A `<Field>` wrapping a `SchemaInput` bound to the named field.
+ * @example <FormField name="email" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormField
+ */
 export function FormField({ name, ...props }: InputProps): ReactElement {
 	const field = useField(name);
 	const { schema, message } = field;
@@ -17,7 +24,13 @@ export function FormField({ name, ...props }: InputProps): ReactElement {
 	);
 }
 
-/** List of `<Field>` elements for every schema property in the current form. */
+/**
+ * Show a `<Field>` for every property in the current form's schema.
+ *
+ * @returns A fragment of `FormField` elements, one per schema property.
+ * @example <FormFields />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFields/FormFields
+ */
 export function FormFields(): ReactElement {
 	const form = useStore(requireForm());
 	return (

package/ui/form/FormFooter.d.ts

@@ -1,11 +1,21 @@
 import type { ReactElement, ReactNode } from "react";
 import type { OptionalChildProps } from "../util/props.js";
+/**
+ * Props for `FormFooter`, the submit-button-and-message footer for a form.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFooter/FormFooterProps
+ */
 export interface FormFooterProps extends OptionalChildProps {
     submit?: ReactNode | undefined;
 }
 /**
- * Show a form footer with custom submit text.
- * - Shows an elements row containing a submit button (and any additional buttons provided as `children`).
- * - Shows a `<FormMessage>` beneath the buttons that shows any error message set on the form.
+ * Show a form footer with a submit button and the form's error message.
+ * - Renders a row containing a `SubmitButton` (and any extra buttons passed as `children`).
+ * - Renders a `<FormMessage>` beneath the buttons showing any error set on the form.
+ *
+ * @param props Props including footer `children` and custom `submit` button content.
+ * @returns A footer element with the submit row and form message.
+ * @example <FormFooter submit="Save" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFooter/FormFooter
  */
 export declare function FormFooter({ children, submit }: FormFooterProps): ReactElement;

package/ui/form/FormFooter.js

@@ -4,9 +4,14 @@ import { Row } from "../style/Flex.js";
 import { FormMessage } from "./FormMessage.js";
 import { SubmitButton } from "./SubmitButton.js";
 /**
- * Show a form footer with custom submit text.
- * - Shows an elements row containing a submit button (and any additional buttons provided as `children`).
- * - Shows a `<FormMessage>` beneath the buttons that shows any error message set on the form.
+ * Show a form footer with a submit button and the form's error message.
+ * - Renders a row containing a `SubmitButton` (and any extra buttons passed as `children`).
+ * - Renders a `<FormMessage>` beneath the buttons showing any error set on the form.
+ *
+ * @param props Props including footer `children` and custom `submit` button content.
+ * @returns A footer element with the submit row and form message.
+ * @example <FormFooter submit="Save" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFooter/FormFooter
  */
 export function FormFooter({ children, submit }) {
     return (_jsxs(Footer, { children: [_jsxs(Row, { reverse: true, children: [_jsx(SubmitButton, { children: submit }), children] }), _jsx(FormMessage, {})] }));

package/ui/form/FormFooter.tsx

@@ -5,14 +5,24 @@ import type { OptionalChildProps } from "../util/props.js";
 import { FormMessage } from "./FormMessage.js";
 import { SubmitButton } from "./SubmitButton.js";
 
+/**
+ * Props for `FormFooter`, the submit-button-and-message footer for a form.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFooter/FormFooterProps
+ */
 export interface FormFooterProps extends OptionalChildProps {
 	submit?: ReactNode | undefined;
 }
 
 /**
- * Show a form footer with custom submit text.
- * - Shows an elements row containing a submit button (and any additional buttons provided as `children`).
- * - Shows a `<FormMessage>` beneath the buttons that shows any error message set on the form.
+ * Show a form footer with a submit button and the form's error message.
+ * - Renders a row containing a `SubmitButton` (and any extra buttons passed as `children`).
+ * - Renders a `<FormMessage>` beneath the buttons showing any error set on the form.
+ *
+ * @param props Props including footer `children` and custom `submit` button content.
+ * @returns A footer element with the submit row and form message.
+ * @example <FormFooter submit="Save" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormFooter/FormFooter
  */
 export function FormFooter({ children, submit }: FormFooterProps): ReactElement {
 	return (

package/ui/form/FormInput.d.ts

@@ -1,8 +1,27 @@
 import type { ReactElement } from "react";
 import type { InputProps } from "./Input.js";
+/**
+ * Props for `FormInput`, a bare `SchemaInput` bound to a named form field.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/FormInput/FormInputProps
+ */
 export interface FormInputProps extends InputProps {
 }
-/** Show a `SchemaInput` for each property in the current form. */
+/**
+ * Show a `SchemaInput` for a single named property of the current form.
+ * - Reads the field's value, schema, and message from the form context via `useField()`.
+ *
+ * @param props Input props including the field `name`.
+ * @returns A `SchemaInput` bound to the named field.
+ * @example <FormInput name="email" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormInput/FormInput
+ */
 export declare function FormInput({ name, ...props }: FormInputProps): ReactElement;
-/** Show a `SchemaInput` for a named property in the current form. */
+/**
+ * Show a `SchemaInput` for every property in the current form's schema.
+ *
+ * @returns A fragment of `FormInput` elements, one per schema property.
+ * @example <FormInputs />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormInput/FormInputs
+ */
 export declare function FormInputs(): ReactElement;

package/ui/form/FormInput.js

@@ -1,12 +1,26 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { requireForm, useField } from "./FormContext.js";
 import { SchemaInput } from "./SchemaInput.js";
-/** Show a `SchemaInput` for each property in the current form. */
+/**
+ * Show a `SchemaInput` for a single named property of the current form.
+ * - Reads the field's value, schema, and message from the form context via `useField()`.
+ *
+ * @param props Input props including the field `name`.
+ * @returns A `SchemaInput` bound to the named field.
+ * @example <FormInput name="email" />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormInput/FormInput
+ */
 export function FormInput({ name, ...props }) {
     const field = useField(name);
     return _jsx(SchemaInput, { ...field, ...props });
 }
-/** Show a `SchemaInput` for a named property in the current form. */
+/**
+ * Show a `SchemaInput` for every property in the current form's schema.
+ *
+ * @returns A fragment of `FormInput` elements, one per schema property.
+ * @example <FormInputs />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormInput/FormInputs
+ */
 export function FormInputs() {
     return (_jsx(_Fragment, { children: Object.keys(requireForm().schema.props).map(name => (_jsx(FormInput, { name: name }, name))) }));
 }