shelving 1.236.0 → 1.236.2

package/ui/form/SchemaInput.d.ts

@@ -12,48 +12,179 @@ import { type Data } from "../../util/data.js";
 import type { ValidatorType } from "../../util/validate.js";
 import type { OptionalChildProps } from "../util/props.js";
 import type { ValueInputProps } from "./Input.js";
-/** A schema is required if it's not wrapped in an `OptionalSchema` or `NullableSchema` */
+/**
+ * Whether a schema is required, i.e. not wrapped in an `OptionalSchema` or `NullableSchema`.
+ *
+ * @param schema The schema to test.
+ * @returns `true` if the schema is required, `false` if it is optional or nullable.
+ * @example isSchemaRequired(STRING) // true
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/isSchemaRequired
+ */
 export declare function isSchemaRequired(schema: Schema): boolean;
+/**
+ * Props for `SchemaInput` and its variants: a `schema` plus the value input props it drives.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInputProps
+ */
 export interface SchemaInputProps<T extends Schema, I = never> extends ValueInputProps<ValidatorType<T>, I> {
     schema: T;
 }
 /**
- * Show the right control/input for a named property of a form.
+ * Show the appropriate input control for a schema, dispatching on the schema's concrete type.
+ * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
+ * - `required` defaults to whether the schema is required.
  *
- * @example <FormControl name="email" /> // Outputs a `<StringInput>` for the "email" property.
- * @example <FormControl name="age" /> // Outputs a `<NumberInput>` for the "age" property.
+ * @param props Props including the `schema` plus value input props.
+ * @returns The matching input element for the schema.
+ * @throws `UnexpectedError` if no input matches the schema type.
+ * @example <SchemaInput name="email" schema={EMAIL} /> // Outputs a `<TextInput>` for the "email" property.
+ * @example <SchemaInput name="age" schema={AGE} /> // Outputs a `<NumberInput>` for the "age" property.
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInput
  */
 export declare function SchemaInput<T extends Schema>(props: SchemaInputProps<T>): ReactElement;
+/**
+ * Props for `DateSchemaInput`, the `DateSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DateSchemaInputProps
+ */
 export interface DateSchemaInputProps extends SchemaInputProps<DateSchema, unknown> {
 }
+/**
+ * Show a `DateInput` for a `DateSchema`.
+ *
+ * @param props Props including the `DateSchema` and value input props.
+ * @returns A `DateInput` element bound to the schema.
+ * @example <DateSchemaInput name="dob" schema={DATE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DateSchemaInput
+ */
 export declare function DateSchemaInput({ schema, value, ...props }: DateSchemaInputProps): ReactElement;
+/**
+ * Props for `NumberSchemaInput`, the `NumberSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/NumberSchemaInputProps
+ */
 export interface NumberSchemaInputProps extends SchemaInputProps<NumberSchema, unknown> {
 }
+/**
+ * Show a `NumberInput` for a `NumberSchema`, formatting values with the schema's `format()`.
+ *
+ * @param props Props including the `NumberSchema` and value input props.
+ * @returns A `NumberInput` element bound to the schema.
+ * @example <NumberSchemaInput name="age" schema={NUMBER} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/NumberSchemaInput
+ */
 export declare function NumberSchemaInput({ schema, value, ...props }: NumberSchemaInputProps): ReactElement;
+/**
+ * Props for `ChoiceSchemaInput`, the `ChoiceSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ChoiceSchemaInputProps
+ */
 export interface ChoiceSchemaInputProps extends SchemaInputProps<ChoiceSchema<string>, unknown> {
 }
+/**
+ * Show a choice input for a `ChoiceSchema` — radio inputs for up to 8 options, otherwise a select.
+ *
+ * @param props Props including the `ChoiceSchema` and value input props.
+ * @returns A `ChoiceRadioInputs` or `SelectInput` element bound to the schema.
+ * @example <ChoiceSchemaInput name="role" schema={ROLE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ChoiceSchemaInput
+ */
 export declare function ChoiceSchemaInput({ schema, value, ...props }: ChoiceSchemaInputProps): ReactElement;
+/**
+ * Props for `BooleanSchemaInput`, the `BooleanSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/BooleanSchemaInputProps
+ */
 export interface BooleanSchemaInputProps extends SchemaInputProps<BooleanSchema, unknown> {
 }
+/**
+ * Show a `CheckboxInput` for a `BooleanSchema`.
+ *
+ * @param props Props including the `BooleanSchema` and value input props.
+ * @returns A `CheckboxInput` element bound to the schema.
+ * @example <BooleanSchemaInput name="agree" schema={BOOLEAN} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/BooleanSchemaInput
+ */
 export declare function BooleanSchemaInput({ schema, value, ...props }: BooleanSchemaInputProps): ReactElement;
+/**
+ * Props for `StringSchemaInput`, the `StringSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/StringSchemaInputProps
+ */
 export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, unknown> {
 }
+/**
+ * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ *
+ * @param props Props including the `StringSchema` and value input props.
+ * @returns A `TextInput` element bound to the schema.
+ * @example <StringSchemaInput name="email" schema={EMAIL} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/StringSchemaInput
+ */
 export declare function StringSchemaInput({ schema, value, ...props }: StringSchemaInputProps): ReactElement;
+/**
+ * Props for `ArraySchemaInput`, the `ArraySchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ArraySchemaInputProps
+ */
 export interface ArraySchemaInputProps extends SchemaInputProps<ArraySchema<unknown>, unknown> {
 }
+/**
+ * Show an `ArrayInput` for an `ArraySchema`.
+ *
+ * @param props Props including the `ArraySchema` and value input props.
+ * @returns An `ArrayInput` element bound to the schema.
+ * @example <ArraySchemaInput name="tags" schema={TAGS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ArraySchemaInput
+ */
 export declare function ArraySchemaInput({ schema, value, ...props }: ArraySchemaInputProps): ReactElement;
+/**
+ * Props for `DictionarySchemaInput`, the `DictionarySchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DictionarySchemaInputProps
+ */
 export interface DictionarySchemaInputProps extends SchemaInputProps<DictionarySchema<unknown>, unknown> {
 }
+/**
+ * Show a `DictionaryInput` for a `DictionarySchema`.
+ *
+ * @param props Props including the `DictionarySchema` and value input props.
+ * @returns A `DictionaryInput` element bound to the schema.
+ * @example <DictionarySchemaInput name="meta" schema={META} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DictionarySchemaInput
+ */
 export declare function DictionarySchemaInput({ schema, value, ...props }: DictionarySchemaInputProps): ReactElement;
+/**
+ * Props for `DataSchemaInput`, the `DataSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DataSchemaInputProps
+ */
 export interface DataSchemaInputProps extends SchemaInputProps<DataSchema<Data>, unknown> {
 }
+/**
+ * Show a `DataInput` for a nested `DataSchema`.
+ *
+ * @param props Props including the `DataSchema` and value input props.
+ * @returns A `DataInput` element bound to the schema.
+ * @example <DataSchemaInput name="address" schema={ADDRESS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DataSchemaInput
+ */
 export declare function DataSchemaInput({ schema, value, ...props }: DataSchemaInputProps): ReactElement;
+/**
+ * Props for `SchemaField`: `SchemaInput` props plus optional `children` to override the input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaFieldProps
+ */
 export interface SchemaFieldProps extends SchemaInputProps<Schema, unknown>, OptionalChildProps {
 }
 /**
- * Show the right control/input for a named property of a form, wrapped in a `<Field>`
+ * Show the appropriate input for a schema, wrapped in a `<Field>` with its label and message.
+ * - Renders custom `children` inside the field, or a `SchemaInput` when none are provided.
  *
- * @example <FormControl name="email" /> // Outputs a `<Field><StringInput></Field>` for the "email" property.
- * @example <FormControl name="age" /> // Outputs a `<Field><NumberInput></Field>` for the "age" property.
+ * @param props Props including the `schema`, optional `children`, and value input props.
+ * @returns A `<Field>` wrapping the schema's input.
+ * @example <SchemaField name="email" schema={EMAIL} /> // Outputs a `<Field>` wrapping a `<TextInput>`.
+ * @example <SchemaField name="age" schema={AGE} /> // Outputs a `<Field>` wrapping a `<NumberInput>`.
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaField
  */
 export declare function SchemaField({ schema, children, ...props }: SchemaFieldProps): ReactElement;

package/ui/form/SchemaInput.js

@@ -27,7 +27,14 @@ import { Field } from "./Field.js";
 import { NumberInput } from "./NumberInput.js";
 import { SelectInput } from "./SelectInput.js";
 import { TextInput } from "./TextInput.js";
-/** A schema is required if it's not wrapped in an `OptionalSchema` or `NullableSchema` */
+/**
+ * Whether a schema is required, i.e. not wrapped in an `OptionalSchema` or `NullableSchema`.
+ *
+ * @param schema The schema to test.
+ * @returns `true` if the schema is required, `false` if it is optional or nullable.
+ * @example isSchemaRequired(STRING) // true
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/isSchemaRequired
+ */
 export function isSchemaRequired(schema) {
     return !(schema instanceof OptionalSchema || schema instanceof NullableSchema);
 }
@@ -64,38 +71,106 @@ required = isSchemaRequired(schema), ...props }) {
         return _jsx(DataSchemaInput, { name: name, schema: data, required: required, ...props });
     throw new UnexpectedError(`Schema "${name}" has no corresponding form field`, { name, schema });
 }
+/**
+ * Show a `DateInput` for a `DateSchema`.
+ *
+ * @param props Props including the `DateSchema` and value input props.
+ * @returns A `DateInput` element bound to the schema.
+ * @example <DateSchemaInput name="dob" schema={DATE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DateSchemaInput
+ */
 export function DateSchemaInput({ schema, value, ...props }) {
     return _jsx(DateInput, { ...schema, value: getString(value), ...props });
 }
+/**
+ * Show a `NumberInput` for a `NumberSchema`, formatting values with the schema's `format()`.
+ *
+ * @param props Props including the `NumberSchema` and value input props.
+ * @returns A `NumberInput` element bound to the schema.
+ * @example <NumberSchemaInput name="age" schema={NUMBER} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/NumberSchemaInput
+ */
 export function NumberSchemaInput({ schema, value, ...props }) {
     return _jsx(NumberInput, { ...schema, value: getNumber(value), formatter: num => schema.format(num), ...props });
 }
+/**
+ * Show a choice input for a `ChoiceSchema` — radio inputs for up to 8 options, otherwise a select.
+ *
+ * @param props Props including the `ChoiceSchema` and value input props.
+ * @returns A `ChoiceRadioInputs` or `SelectInput` element bound to the schema.
+ * @example <ChoiceSchemaInput name="role" schema={ROLE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ChoiceSchemaInput
+ */
 export function ChoiceSchemaInput({ schema, value, ...props }) {
     const { options } = requireSource(ChoiceSchema, schema);
     if (getKeys(options).length <= 8)
         return _jsx(ChoiceRadioInputs, { ...schema, value: getString(value), ...props });
     return _jsx(SelectInput, { ...schema, value: getString(value), ...props });
 }
+/**
+ * Show a `CheckboxInput` for a `BooleanSchema`.
+ *
+ * @param props Props including the `BooleanSchema` and value input props.
+ * @returns A `CheckboxInput` element bound to the schema.
+ * @example <BooleanSchemaInput name="agree" schema={BOOLEAN} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/BooleanSchemaInput
+ */
 export function BooleanSchemaInput({ schema, value, ...props }) {
     return _jsx(CheckboxInput, { ...schema, value: !!value, ...props });
 }
+/**
+ * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ *
+ * @param props Props including the `StringSchema` and value input props.
+ * @returns A `TextInput` element bound to the schema.
+ * @example <StringSchemaInput name="email" schema={EMAIL} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/StringSchemaInput
+ */
 export function StringSchemaInput({ schema, value, ...props }) {
     return _jsx(TextInput, { ...schema, value: getString(value), formatter: str => schema.format(schema.sanitize(str)), ...props });
 }
+/**
+ * Show an `ArrayInput` for an `ArraySchema`.
+ *
+ * @param props Props including the `ArraySchema` and value input props.
+ * @returns An `ArrayInput` element bound to the schema.
+ * @example <ArraySchemaInput name="tags" schema={TAGS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ArraySchemaInput
+ */
 export function ArraySchemaInput({ schema, value, ...props }) {
     return _jsx(ArrayInput, { ...schema, value: isArray(value) ? value : undefined, ...props });
 }
+/**
+ * Show a `DictionaryInput` for a `DictionarySchema`.
+ *
+ * @param props Props including the `DictionarySchema` and value input props.
+ * @returns A `DictionaryInput` element bound to the schema.
+ * @example <DictionarySchemaInput name="meta" schema={META} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DictionarySchemaInput
+ */
 export function DictionarySchemaInput({ schema, value, ...props }) {
     return _jsx(DictionaryInput, { ...schema, value: isDictionary(value) ? value : undefined, ...props });
 }
+/**
+ * Show a `DataInput` for a nested `DataSchema`.
+ *
+ * @param props Props including the `DataSchema` and value input props.
+ * @returns A `DataInput` element bound to the schema.
+ * @example <DataSchemaInput name="address" schema={ADDRESS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DataSchemaInput
+ */
 export function DataSchemaInput({ schema, value, ...props }) {
     return _jsx(DataInput, { ...schema, value: isData(value) ? value : undefined, ...props });
 }
 /**
- * Show the right control/input for a named property of a form, wrapped in a `<Field>`
+ * Show the appropriate input for a schema, wrapped in a `<Field>` with its label and message.
+ * - Renders custom `children` inside the field, or a `SchemaInput` when none are provided.
  *
- * @example <FormControl name="email" /> // Outputs a `<Field><StringInput></Field>` for the "email" property.
- * @example <FormControl name="age" /> // Outputs a `<Field><NumberInput></Field>` for the "age" property.
+ * @param props Props including the `schema`, optional `children`, and value input props.
+ * @returns A `<Field>` wrapping the schema's input.
+ * @example <SchemaField name="email" schema={EMAIL} /> // Outputs a `<Field>` wrapping a `<TextInput>`.
+ * @example <SchemaField name="age" schema={AGE} /> // Outputs a `<Field>` wrapping a `<NumberInput>`.
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaField
  */
 export function SchemaField({ schema, children, ...props }) {
     return (_jsx(Field, { ...props, ...schema, children: children ?? _jsx(SchemaInput, { schema: schema, ...props }) }));

package/ui/form/SchemaInput.tsx

@@ -32,20 +32,38 @@ import { NumberInput } from "./NumberInput.js";
 import { SelectInput } from "./SelectInput.js";
 import { TextInput } from "./TextInput.js";
 
-/** A schema is required if it's not wrapped in an `OptionalSchema` or `NullableSchema` */
+/**
+ * Whether a schema is required, i.e. not wrapped in an `OptionalSchema` or `NullableSchema`.
+ *
+ * @param schema The schema to test.
+ * @returns `true` if the schema is required, `false` if it is optional or nullable.
+ * @example isSchemaRequired(STRING) // true
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/isSchemaRequired
+ */
 export function isSchemaRequired(schema: Schema): boolean {
 	return !(schema instanceof OptionalSchema || schema instanceof NullableSchema);
 }
 
+/**
+ * Props for `SchemaInput` and its variants: a `schema` plus the value input props it drives.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInputProps
+ */
 export interface SchemaInputProps<T extends Schema, I = never> extends ValueInputProps<ValidatorType<T>, I> {
 	schema: T;
 }
 
 /**
- * Show the right control/input for a named property of a form.
+ * Show the appropriate input control for a schema, dispatching on the schema's concrete type.
+ * - Picks `DateInput`, `NumberInput`, choice radios/select, `CheckboxInput`, `TextInput`, `ArrayInput`, `DictionaryInput`, or `DataInput`.
+ * - `required` defaults to whether the schema is required.
  *
- * @example <FormControl name="email" /> // Outputs a `<StringInput>` for the "email" property.
- * @example <FormControl name="age" /> // Outputs a `<NumberInput>` for the "age" property.
+ * @param props Props including the `schema` plus value input props.
+ * @returns The matching input element for the schema.
+ * @throws `UnexpectedError` if no input matches the schema type.
+ * @example <SchemaInput name="email" schema={EMAIL} /> // Outputs a `<TextInput>` for the "email" property.
+ * @example <SchemaInput name="age" schema={AGE} /> // Outputs a `<NumberInput>` for the "age" property.
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaInput
  */
 export function SchemaInput<T extends Schema>(props: SchemaInputProps<T>): ReactElement;
 export function SchemaInput({
@@ -86,63 +104,176 @@ export function SchemaInput({
 	throw new UnexpectedError(`Schema "${name}" has no corresponding form field`, { name, schema });
 }
 
+/**
+ * Props for `DateSchemaInput`, the `DateSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DateSchemaInputProps
+ */
 export interface DateSchemaInputProps extends SchemaInputProps<DateSchema, unknown> {}
 
+/**
+ * Show a `DateInput` for a `DateSchema`.
+ *
+ * @param props Props including the `DateSchema` and value input props.
+ * @returns A `DateInput` element bound to the schema.
+ * @example <DateSchemaInput name="dob" schema={DATE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DateSchemaInput
+ */
 export function DateSchemaInput({ schema, value, ...props }: DateSchemaInputProps): ReactElement {
 	return <DateInput {...schema} value={getString(value)} {...props} />;
 }
 
+/**
+ * Props for `NumberSchemaInput`, the `NumberSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/NumberSchemaInputProps
+ */
 export interface NumberSchemaInputProps extends SchemaInputProps<NumberSchema, unknown> {}
 
+/**
+ * Show a `NumberInput` for a `NumberSchema`, formatting values with the schema's `format()`.
+ *
+ * @param props Props including the `NumberSchema` and value input props.
+ * @returns A `NumberInput` element bound to the schema.
+ * @example <NumberSchemaInput name="age" schema={NUMBER} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/NumberSchemaInput
+ */
 export function NumberSchemaInput({ schema, value, ...props }: NumberSchemaInputProps): ReactElement {
 	return <NumberInput {...schema} value={getNumber(value)} formatter={num => schema.format(num)} {...props} />;
 }
 
+/**
+ * Props for `ChoiceSchemaInput`, the `ChoiceSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ChoiceSchemaInputProps
+ */
 export interface ChoiceSchemaInputProps extends SchemaInputProps<ChoiceSchema<string>, unknown> {}
 
+/**
+ * Show a choice input for a `ChoiceSchema` — radio inputs for up to 8 options, otherwise a select.
+ *
+ * @param props Props including the `ChoiceSchema` and value input props.
+ * @returns A `ChoiceRadioInputs` or `SelectInput` element bound to the schema.
+ * @example <ChoiceSchemaInput name="role" schema={ROLE} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ChoiceSchemaInput
+ */
 export function ChoiceSchemaInput({ schema, value, ...props }: ChoiceSchemaInputProps): ReactElement {
 	const { options } = requireSource(ChoiceSchema, schema);
 	if (getKeys(options).length <= 8) return <ChoiceRadioInputs {...schema} value={getString(value)} {...props} />;
 	return <SelectInput {...schema} value={getString(value)} {...props} />;
 }
 
+/**
+ * Props for `BooleanSchemaInput`, the `BooleanSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/BooleanSchemaInputProps
+ */
 export interface BooleanSchemaInputProps extends SchemaInputProps<BooleanSchema, unknown> {}
 
+/**
+ * Show a `CheckboxInput` for a `BooleanSchema`.
+ *
+ * @param props Props including the `BooleanSchema` and value input props.
+ * @returns A `CheckboxInput` element bound to the schema.
+ * @example <BooleanSchemaInput name="agree" schema={BOOLEAN} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/BooleanSchemaInput
+ */
 export function BooleanSchemaInput({ schema, value, ...props }: BooleanSchemaInputProps): ReactElement {
 	return <CheckboxInput {...schema} value={!!value} {...props} />;
 }
 
+/**
+ * Props for `StringSchemaInput`, the `StringSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/StringSchemaInputProps
+ */
 export interface StringSchemaInputProps extends SchemaInputProps<StringSchema, unknown> {}
 
+/**
+ * Show a `TextInput` for a `StringSchema`, sanitising and formatting values with the schema.
+ *
+ * @param props Props including the `StringSchema` and value input props.
+ * @returns A `TextInput` element bound to the schema.
+ * @example <StringSchemaInput name="email" schema={EMAIL} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/StringSchemaInput
+ */
 export function StringSchemaInput({ schema, value, ...props }: StringSchemaInputProps): ReactElement {
 	return <TextInput {...schema} value={getString(value)} formatter={str => schema.format(schema.sanitize(str))} {...props} />;
 }
 
+/**
+ * Props for `ArraySchemaInput`, the `ArraySchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ArraySchemaInputProps
+ */
 export interface ArraySchemaInputProps extends SchemaInputProps<ArraySchema<unknown>, unknown> {}
 
+/**
+ * Show an `ArrayInput` for an `ArraySchema`.
+ *
+ * @param props Props including the `ArraySchema` and value input props.
+ * @returns An `ArrayInput` element bound to the schema.
+ * @example <ArraySchemaInput name="tags" schema={TAGS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/ArraySchemaInput
+ */
 export function ArraySchemaInput({ schema, value, ...props }: ArraySchemaInputProps): ReactElement {
 	return <ArrayInput {...schema} value={isArray(value) ? value : undefined} {...props} />;
 }
 
+/**
+ * Props for `DictionarySchemaInput`, the `DictionarySchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DictionarySchemaInputProps
+ */
 export interface DictionarySchemaInputProps extends SchemaInputProps<DictionarySchema<unknown>, unknown> {}
 
+/**
+ * Show a `DictionaryInput` for a `DictionarySchema`.
+ *
+ * @param props Props including the `DictionarySchema` and value input props.
+ * @returns A `DictionaryInput` element bound to the schema.
+ * @example <DictionarySchemaInput name="meta" schema={META} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DictionarySchemaInput
+ */
 export function DictionarySchemaInput({ schema, value, ...props }: DictionarySchemaInputProps): ReactElement {
 	return <DictionaryInput {...schema} value={isDictionary(value) ? value : undefined} {...props} />;
 }
 
+/**
+ * Props for `DataSchemaInput`, the `DataSchema` input variant.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DataSchemaInputProps
+ */
 export interface DataSchemaInputProps extends SchemaInputProps<DataSchema<Data>, unknown> {}
 
+/**
+ * Show a `DataInput` for a nested `DataSchema`.
+ *
+ * @param props Props including the `DataSchema` and value input props.
+ * @returns A `DataInput` element bound to the schema.
+ * @example <DataSchemaInput name="address" schema={ADDRESS} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/DataSchemaInput
+ */
 export function DataSchemaInput({ schema, value, ...props }: DataSchemaInputProps): ReactElement {
 	return <DataInput {...schema} value={isData(value) ? value : undefined} {...props} />;
 }
 
+/**
+ * Props for `SchemaField`: `SchemaInput` props plus optional `children` to override the input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaFieldProps
+ */
 export interface SchemaFieldProps extends SchemaInputProps<Schema, unknown>, OptionalChildProps {}
 
 /**
- * Show the right control/input for a named property of a form, wrapped in a `<Field>`
+ * Show the appropriate input for a schema, wrapped in a `<Field>` with its label and message.
+ * - Renders custom `children` inside the field, or a `SchemaInput` when none are provided.
  *
- * @example <FormControl name="email" /> // Outputs a `<Field><StringInput></Field>` for the "email" property.
- * @example <FormControl name="age" /> // Outputs a `<Field><NumberInput></Field>` for the "age" property.
+ * @param props Props including the `schema`, optional `children`, and value input props.
+ * @returns A `<Field>` wrapping the schema's input.
+ * @example <SchemaField name="email" schema={EMAIL} /> // Outputs a `<Field>` wrapping a `<TextInput>`.
+ * @example <SchemaField name="age" schema={AGE} /> // Outputs a `<Field>` wrapping a `<NumberInput>`.
+ * @see https://dhoulb.github.io/shelving/ui/form/SchemaInput/SchemaField
  */
 export function SchemaField({ schema, children, ...props }: SchemaFieldProps): ReactElement {
 	return (

package/ui/form/SelectInput.d.ts

@@ -1,8 +1,22 @@
 import type { ReactElement } from "react";
 import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
 import { type ValueInputProps } from "./Input.js";
+/**
+ * Props for `SelectInput`, a dropdown `<select>` bound to a string value.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SelectInput/SelectProps
+ */
 export interface SelectProps<T extends string> extends ValueInputProps<T> {
     /** The options for the select. */
     options: ChoiceOptions<T>;
 }
+/**
+ * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
+ * - Shows a placeholder empty option unless the field is required and already has a value.
+ *
+ * @param props Props including `options`, `value`, `onValue`, and `placeholder`.
+ * @returns A `<select>` element.
+ * @example <SelectInput name="role" options={ROLES} value={role} onValue={setRole} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SelectInput/SelectInput
+ */
 export declare function SelectInput<T extends string>(props: SelectProps<T>): ReactElement;

package/ui/form/SelectInput.tsx

@@ -3,11 +3,25 @@ import type { ChoiceOptions } from "../../schema/ChoiceSchema.js";
 import { getProps } from "../../util/object.js";
 import { EMPTY_OPTION_CLASS, SELECT_INPUT_CLASS, VALUE_OPTION_CLASS, type ValueInputProps } from "./Input.js";
 
+/**
+ * Props for `SelectInput`, a dropdown `<select>` bound to a string value.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SelectInput/SelectProps
+ */
 export interface SelectProps<T extends string> extends ValueInputProps<T> {
 	/** The options for the select. */
 	options: ChoiceOptions<T>;
 }
 
+/**
+ * Dropdown input bound to a string value, rendered as a `<select>` of the provided `options`.
+ * - Shows a placeholder empty option unless the field is required and already has a value.
+ *
+ * @param props Props including `options`, `value`, `onValue`, and `placeholder`.
+ * @returns A `<select>` element.
+ * @example <SelectInput name="role" options={ROLES} value={role} onValue={setRole} />
+ * @see https://dhoulb.github.io/shelving/ui/form/SelectInput/SelectInput
+ */
 export function SelectInput<T extends string>(props: SelectProps<T>): ReactElement;
 export function SelectInput({
 	name,

package/ui/form/SubmitButton.d.ts

@@ -1,7 +1,20 @@
 import type { ReactElement } from "react";
 import type { OptionalChildProps } from "../util/props.js";
 import { type ButtonVariants } from "./Button.js";
-/** `<button>` element that does an asynchronous form action (defaults to strong, full-width, primary styling). */
+/**
+ * Submit button for a form that disables itself and shows a spinner while the form is busy.
+ * - Defaults to strong, full-width, primary styling and a "Save" label.
+ *
+ * @param props Button variants and optional `children` label content.
+ * @returns A `<button type="submit">` element bound to the current form.
+ * @example <SubmitButton>Save changes</SubmitButton>
+ * @see https://dhoulb.github.io/shelving/ui/form/SubmitButton/SubmitButton
+ */
 export declare function SubmitButton({ children, strong, color, full, ...variants }: SubmitButtonProps): ReactElement;
+/**
+ * Props for `SubmitButton`, a form submit button.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SubmitButton/SubmitButtonProps
+ */
 export interface SubmitButtonProps extends ButtonVariants, OptionalChildProps {
 }

package/ui/form/SubmitButton.js

@@ -4,7 +4,15 @@ import { useStore } from "../../react/useStore.js";
 import { Loading } from "../misc/Loading.js";
 import { getButtonClass } from "./Button.js";
 import { requireForm } from "./FormContext.js";
-/** `<button>` element that does an asynchronous form action (defaults to strong, full-width, primary styling). */
+/**
+ * Submit button for a form that disables itself and shows a spinner while the form is busy.
+ * - Defaults to strong, full-width, primary styling and a "Save" label.
+ *
+ * @param props Button variants and optional `children` label content.
+ * @returns A `<button type="submit">` element bound to the current form.
+ * @example <SubmitButton>Save changes</SubmitButton>
+ * @see https://dhoulb.github.io/shelving/ui/form/SubmitButton/SubmitButton
+ */
 export function SubmitButton({ children = SUBMIT_CHILDREN, strong = true, color = "primary", full = true, ...variants }) {
     const form = requireForm();
     const busy = useStore(form.busy).value;

package/ui/form/SubmitButton.tsx

@@ -6,7 +6,15 @@ import type { OptionalChildProps } from "../util/props.js";
 import { type ButtonVariants, getButtonClass } from "./Button.js";
 import { requireForm } from "./FormContext.js";
 
-/** `<button>` element that does an asynchronous form action (defaults to strong, full-width, primary styling). */
+/**
+ * Submit button for a form that disables itself and shows a spinner while the form is busy.
+ * - Defaults to strong, full-width, primary styling and a "Save" label.
+ *
+ * @param props Button variants and optional `children` label content.
+ * @returns A `<button type="submit">` element bound to the current form.
+ * @example <SubmitButton>Save changes</SubmitButton>
+ * @see https://dhoulb.github.io/shelving/ui/form/SubmitButton/SubmitButton
+ */
 export function SubmitButton({
 	children = SUBMIT_CHILDREN,
 	strong = true,
@@ -23,6 +31,11 @@ export function SubmitButton({
 	);
 }
 
+/**
+ * Props for `SubmitButton`, a form submit button.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/SubmitButton/SubmitButtonProps
+ */
 export interface SubmitButtonProps extends ButtonVariants, OptionalChildProps {}
 
 const SUBMIT_CHILDREN = (