shelving 1.236.0 → 1.236.2

package/ui/form/FormInput.tsx

@@ -3,15 +3,34 @@ import { requireForm, useField } from "./FormContext.js";
 import type { InputProps } from "./Input.js";
 import { SchemaInput } from "./SchemaInput.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 function FormInput({ name, ...props }: FormInputProps): ReactElement {
 	const field = useField(name);
 	return <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(): ReactElement {
 	return (
 		<>

package/ui/form/FormMessage.d.ts

@@ -1,4 +1,11 @@
 import type { ReactElement } from "react";
 import { type MessageProps } from "../notice/Message.js";
-/** Show the "main" message for the form as a `<Message>` */
+/**
+ * Show the current form's "main" (unnamed) message as a `<Message>`, or render nothing when there is no message.
+ *
+ * @param props Message props (excluding `children`) forwarded to the underlying `<Message>`.
+ * @returns A `<Message status="error">` containing the message, or `null` when empty.
+ * @example <FormMessage />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormMessage/FormMessage
+ */
 export declare function FormMessage(props: Omit<MessageProps, "children">): ReactElement | null;

package/ui/form/FormMessage.js

@@ -2,7 +2,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useStore } from "../../react/useStore.js";
 import { Message } from "../notice/Message.js";
 import { requireForm } from "./FormContext.js";
-/** Show the "main" message for the form as a `<Message>` */
+/**
+ * Show the current form's "main" (unnamed) message as a `<Message>`, or render nothing when there is no message.
+ *
+ * @param props Message props (excluding `children`) forwarded to the underlying `<Message>`.
+ * @returns A `<Message status="error">` containing the message, or `null` when empty.
+ * @example <FormMessage />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormMessage/FormMessage
+ */
 export function FormMessage(props) {
     const message = useStore(requireForm().messages).get("");
     if (!message)

package/ui/form/FormMessage.tsx

@@ -3,8 +3,14 @@ import { useStore } from "../../react/useStore.js";
 import { Message, type MessageProps } from "../notice/Message.js";
 import { requireForm } from "./FormContext.js";
 
-/** Show the "main" message for the form as a `<Message>` */
-
+/**
+ * Show the current form's "main" (unnamed) message as a `<Message>`, or render nothing when there is no message.
+ *
+ * @param props Message props (excluding `children`) forwarded to the underlying `<Message>`.
+ * @returns A `<Message status="error">` containing the message, or `null` when empty.
+ * @example <FormMessage />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormMessage/FormMessage
+ */
 export function FormMessage(props: Omit<MessageProps, "children">): ReactElement | null {
 	const message = useStore(requireForm().messages).get("");
 	if (!message) return null;

package/ui/form/FormNotice.d.ts

@@ -1,4 +1,11 @@
 import type { ReactElement } from "react";
 import { type NoticeProps } from "../notice/Notice.js";
-/** Show the "main" message for the form as a `<Notice>` */
+/**
+ * Show the current form's "main" (unnamed) message as a `<Notice>`, or render nothing when there is no message.
+ *
+ * @param props Notice props (excluding `children`) forwarded to the underlying `<Notice>`.
+ * @returns A `<Notice status="error">` containing the message, or `null` when empty.
+ * @example <FormNotice />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotice/FormNotice
+ */
 export declare function FormNotice(props: Omit<NoticeProps, "children">): ReactElement | null;

package/ui/form/FormNotice.js

@@ -2,7 +2,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useStore } from "../../react/useStore.js";
 import { Notice } from "../notice/Notice.js";
 import { requireForm } from "./FormContext.js";
-/** Show the "main" message for the form as a `<Notice>` */
+/**
+ * Show the current form's "main" (unnamed) message as a `<Notice>`, or render nothing when there is no message.
+ *
+ * @param props Notice props (excluding `children`) forwarded to the underlying `<Notice>`.
+ * @returns A `<Notice status="error">` containing the message, or `null` when empty.
+ * @example <FormNotice />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotice/FormNotice
+ */
 export function FormNotice(props) {
     const message = useStore(requireForm().messages).get("");
     if (!message)

package/ui/form/FormNotice.tsx

@@ -3,8 +3,14 @@ import { useStore } from "../../react/useStore.js";
 import { Notice, type NoticeProps } from "../notice/Notice.js";
 import { requireForm } from "./FormContext.js";
 
-/** Show the "main" message for the form as a `<Notice>` */
-
+/**
+ * Show the current form's "main" (unnamed) message as a `<Notice>`, or render nothing when there is no message.
+ *
+ * @param props Notice props (excluding `children`) forwarded to the underlying `<Notice>`.
+ * @returns A `<Notice status="error">` containing the message, or `null` when empty.
+ * @example <FormNotice />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotice/FormNotice
+ */
 export function FormNotice(props: Omit<NoticeProps, "children">): ReactElement | null {
 	const message = useStore(requireForm().messages).get("");
 	if (!message) return null;

package/ui/form/FormNotify.d.ts

@@ -1,2 +1,9 @@
-/** Publish the "main" message of a form as a global notice. */
+/**
+ * Publish the current form's "main" (unnamed) message as a global success notice whenever it changes.
+ * - Renders nothing; mount it inside a `Form` to surface the message globally.
+ *
+ * @returns Nothing — this component only triggers a side effect.
+ * @example <FormNotify />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotify/FormNotify
+ */
 export declare function FormNotify(): void;

package/ui/form/FormNotify.js

@@ -2,7 +2,14 @@ import { useEffect } from "react";
 import { useStore } from "../../react/useStore.js";
 import { notifySuccess } from "../util/notice.js";
 import { requireForm } from "./FormContext.js";
-/** Publish the "main" message of a form as a global notice. */
+/**
+ * Publish the current form's "main" (unnamed) message as a global success notice whenever it changes.
+ * - Renders nothing; mount it inside a `Form` to surface the message globally.
+ *
+ * @returns Nothing — this component only triggers a side effect.
+ * @example <FormNotify />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotify/FormNotify
+ */
 export function FormNotify() {
     const message = useStore(requireForm().messages).get("");
     useEffect(() => {

package/ui/form/FormNotify.tsx

@@ -3,8 +3,14 @@ import { useStore } from "../../react/useStore.js";
 import { notifySuccess } from "../util/notice.js";
 import { requireForm } from "./FormContext.js";
 
-/** Publish the "main" message of a form as a global notice. */
-
+/**
+ * Publish the current form's "main" (unnamed) message as a global success notice whenever it changes.
+ * - Renders nothing; mount it inside a `Form` to surface the message globally.
+ *
+ * @returns Nothing — this component only triggers a side effect.
+ * @example <FormNotify />
+ * @see https://dhoulb.github.io/shelving/ui/form/FormNotify/FormNotify
+ */
 export function FormNotify(): void {
 	const message = useStore(requireForm().messages).get("");
 	useEffect(() => {

package/ui/form/FormStore.d.ts

@@ -5,7 +5,14 @@ import { DictionaryStore } from "../../store/DictionaryStore.js";
 import type { Data, DataKey } from "../../util/data.js";
 import type { ImmutableDictionary } from "../../util/dictionary.js";
 import type { Arguments } from "../../util/function.js";
-/** Store the current value of a form. */
+/**
+ * Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
+ * - Extends `DataStore` with the form's `schema`, per-field error `messages`, and validate/submit helpers.
+ * - Assigning a string `reason` splits it into per-field messages rather than a global failure.
+ *
+ * @example const store = new FormStore(USER_SCHEMA, { name: "Dave" });
+ * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore
+ */
 export declare class FormStore<T extends Data> extends DataStore<Partial<T>> implements AsyncDisposable {
     /** Unique ID for the form. */
     readonly id: string;
@@ -20,19 +27,56 @@ export declare class FormStore<T extends Data> extends DataStore<Partial<T>> imp
      * - See `splitMessages()` in `shelving` for more information.
      */
     readonly messages: DictionaryStore<string>;
-    /** Get the current valid value for this form (throws string for invalid values). */
+    /**
+     * The current value validated against the schema, also written back to `this.value`.
+     *
+     * @throws A `string` validation message if the current value is invalid.
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/validated
+     */
     get validated(): T;
     get reason(): unknown;
     set reason(reason: unknown);
+    /**
+     * Create a new `FormStore` for a schema, with optional initial data and messages.
+     *
+     * @param schema Schema describing the form's fields.
+     * @param partialData Initial (possibly partial) data for the form.
+     * @param messages Initial messages as a dictionary, or a string with `fieldName:` style lines.
+     * @example new FormStore(USER_SCHEMA, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/constructor
+     */
     constructor(schema: DataSchema<T>, partialData?: Partial<T>, messages?: ImmutableDictionary<string> | string | undefined);
-    /** Get a named schema for a field of this form. */
+    /**
+     * Get the `Schema` for a named field of this form.
+     *
+     * @param name Name of the field to look up.
+     * @returns The `Schema` for that field.
+     * @throws `RequiredError` if no schema exists for the named field.
+     * @example store.requireSchema("email")
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/requireSchema
+     */
     requireSchema<K extends DataKey<T>>(name: K): Schema<T[K]>;
-    /** Publish a value for a field of this form. */
+    /**
+     * Validate and set a value for a named field of this form.
+     * - Clears the main and field messages, then validates and stores the value.
+     * - On a string validation error the message is recorded and the raw value is still persisted.
+     *
+     * @param name Name of the field to update.
+     * @param unsafeValue The unvalidated value to store for the field.
+     * @returns Nothing.
+     * @example store.publish("email", "dave@shax.com")
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/publish
+     */
     publish<K extends DataKey<T>>(name: K, unsafeValue: T[K]): void;
     /**
-     * Validate and submit the current values of the form.
+     * Validate the current form value and run an optional submit callback with it.
+     * - On a validation failure the error is stored as the `reason` and `false` is returned.
      *
-     * @param callback Optional callback that takes the current (validated) value of the form, processes it (possibly asynchronously) and returns any new values.
+     * @param callback Optional callback that takes the validated value, processes it (possibly asynchronously) and returns any new values.
+     * @param args Additional arguments forwarded to the callback.
+     * @returns `true` on success, `false` on validation failure (or a `Promise` resolving to one).
+     * @example store.submit(saveUser)
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/submit
      */
     submit<A extends Arguments>(callback?: ((value: T, ...args: A) => void) | undefined, ...args: A): boolean | Promise<boolean>;
     [Symbol.asyncDispose](): Promise<void>;

package/ui/form/FormStore.js

@@ -5,7 +5,14 @@ import { DictionaryStore } from "../../store/DictionaryStore.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { splitMessage } from "../../util/error.js";
 import { getRandomKey } from "../../util/random.js";
-/** Store the current value of a form. */
+/**
+ * Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
+ * - Extends `DataStore` with the form's `schema`, per-field error `messages`, and validate/submit helpers.
+ * - Assigning a string `reason` splits it into per-field messages rather than a global failure.
+ *
+ * @example const store = new FormStore(USER_SCHEMA, { name: "Dave" });
+ * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore
+ */
 export class FormStore extends DataStore {
     /** Unique ID for the form. */
     id = getRandomKey();
@@ -20,7 +27,12 @@ export class FormStore extends DataStore {
      * - See `splitMessages()` in `shelving` for more information.
      */
     messages = new DictionaryStore();
-    /** Get the current valid value for this form (throws string for invalid values). */
+    /**
+     * The current value validated against the schema, also written back to `this.value`.
+     *
+     * @throws A `string` validation message if the current value is invalid.
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/validated
+     */
     get validated() {
         return (this.value = this.schema.validate(this.value));
     }
@@ -36,6 +48,15 @@ export class FormStore extends DataStore {
             super.reason = reason;
         }
     }
+    /**
+     * Create a new `FormStore` for a schema, with optional initial data and messages.
+     *
+     * @param schema Schema describing the form's fields.
+     * @param partialData Initial (possibly partial) data for the form.
+     * @param messages Initial messages as a dictionary, or a string with `fieldName:` style lines.
+     * @example new FormStore(USER_SCHEMA, { name: "Dave" })
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/constructor
+     */
     constructor(schema, partialData = {}, messages) {
         super(partialData);
         this.key = `${this.id}:${JSON.stringify(partialData)}`;
@@ -43,14 +64,32 @@ export class FormStore extends DataStore {
         if (messages)
             this.messages.value = typeof messages === "string" ? splitMessage(messages) : messages;
     }
-    /** Get a named schema for a field of this form. */
+    /**
+     * Get the `Schema` for a named field of this form.
+     *
+     * @param name Name of the field to look up.
+     * @returns The `Schema` for that field.
+     * @throws `RequiredError` if no schema exists for the named field.
+     * @example store.requireSchema("email")
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/requireSchema
+     */
     requireSchema(name) {
         const schema = this.schema.props[name];
         if (schema instanceof Schema)
             return schema;
         throw new RequiredError(`Schema "${name}" does not exist in form`, { received: name, caller: this.requireSchema });
     }
-    /** Publish a value for a field of this form. */
+    /**
+     * Validate and set a value for a named field of this form.
+     * - Clears the main and field messages, then validates and stores the value.
+     * - On a string validation error the message is recorded and the raw value is still persisted.
+     *
+     * @param name Name of the field to update.
+     * @param unsafeValue The unvalidated value to store for the field.
+     * @returns Nothing.
+     * @example store.publish("email", "dave@shax.com")
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/publish
+     */
     publish(name, unsafeValue) {
         this.abort();
         // Clear main message and this named message.
@@ -71,9 +110,14 @@ export class FormStore extends DataStore {
         }
     }
     /**
-     * Validate and submit the current values of the form.
+     * Validate the current form value and run an optional submit callback with it.
+     * - On a validation failure the error is stored as the `reason` and `false` is returned.
      *
-     * @param callback Optional callback that takes the current (validated) value of the form, processes it (possibly asynchronously) and returns any new values.
+     * @param callback Optional callback that takes the validated value, processes it (possibly asynchronously) and returns any new values.
+     * @param args Additional arguments forwarded to the callback.
+     * @returns `true` on success, `false` on validation failure (or a `Promise` resolving to one).
+     * @example store.submit(saveUser)
+     * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/submit
      */
     submit(callback, ...args) {
         try {

package/ui/form/FormStore.tsx

@@ -10,7 +10,14 @@ import { splitMessage } from "../../util/error.js";
 import type { Arguments } from "../../util/function.js";
 import { getRandomKey } from "../../util/random.js";
 
-/** Store the current value of a form. */
+/**
+ * Reactive store holding the current (possibly partial and invalid) value of a form, plus its field messages.
+ * - Extends `DataStore` with the form's `schema`, per-field error `messages`, and validate/submit helpers.
+ * - Assigning a string `reason` splits it into per-field messages rather than a global failure.
+ *
+ * @example const store = new FormStore(USER_SCHEMA, { name: "Dave" });
+ * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore
+ */
 export class FormStore<T extends Data> extends DataStore<Partial<T>> implements AsyncDisposable {
 	/** Unique ID for the form. */
 	readonly id = getRandomKey();
@@ -29,7 +36,12 @@ export class FormStore<T extends Data> extends DataStore<Partial<T>> implements
 	 */
 	readonly messages = new DictionaryStore<string>();
 
-	/** Get the current valid value for this form (throws string for invalid values). */
+	/**
+	 * The current value validated against the schema, also written back to `this.value`.
+	 *
+	 * @throws A `string` validation message if the current value is invalid.
+	 * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/validated
+	 */
 	get validated(): T {
 		return (this.value = this.schema.validate(this.value));
 	}
@@ -46,6 +58,15 @@ export class FormStore<T extends Data> extends DataStore<Partial<T>> implements
 		}
 	}
 
+	/**
+	 * Create a new `FormStore` for a schema, with optional initial data and messages.
+	 *
+	 * @param schema Schema describing the form's fields.
+	 * @param partialData Initial (possibly partial) data for the form.
+	 * @param messages Initial messages as a dictionary, or a string with `fieldName:` style lines.
+	 * @example new FormStore(USER_SCHEMA, { name: "Dave" })
+	 * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/constructor
+	 */
 	constructor(schema: DataSchema<T>, partialData: Partial<T> = {}, messages?: ImmutableDictionary<string> | string | undefined) {
 		super(partialData);
 		this.key = `${this.id}:${JSON.stringify(partialData)}`;
@@ -53,14 +74,32 @@ export class FormStore<T extends Data> extends DataStore<Partial<T>> implements
 		if (messages) this.messages.value = typeof messages === "string" ? splitMessage(messages) : messages;
 	}
 
-	/** Get a named schema for a field of this form. */
+	/**
+	 * Get the `Schema` for a named field of this form.
+	 *
+	 * @param name Name of the field to look up.
+	 * @returns The `Schema` for that field.
+	 * @throws `RequiredError` if no schema exists for the named field.
+	 * @example store.requireSchema("email")
+	 * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/requireSchema
+	 */
 	requireSchema<K extends DataKey<T>>(name: K): Schema<T[K]> {
 		const schema = this.schema.props[name];
 		if (schema instanceof Schema) return schema as Schema<T[K]>;
 		throw new RequiredError(`Schema "${name}" does not exist in form`, { received: name, caller: this.requireSchema });
 	}
 
-	/** Publish a value for a field of this form. */
+	/**
+	 * Validate and set a value for a named field of this form.
+	 * - Clears the main and field messages, then validates and stores the value.
+	 * - On a string validation error the message is recorded and the raw value is still persisted.
+	 *
+	 * @param name Name of the field to update.
+	 * @param unsafeValue The unvalidated value to store for the field.
+	 * @returns Nothing.
+	 * @example store.publish("email", "dave@shax.com")
+	 * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/publish
+	 */
 	publish<K extends DataKey<T>>(name: K, unsafeValue: T[K]): void {
 		this.abort();
 
@@ -82,9 +121,14 @@ export class FormStore<T extends Data> extends DataStore<Partial<T>> implements
 	}
 
 	/**
-	 * Validate and submit the current values of the form.
+	 * Validate the current form value and run an optional submit callback with it.
+	 * - On a validation failure the error is stored as the `reason` and `false` is returned.
 	 *
-	 * @param callback Optional callback that takes the current (validated) value of the form, processes it (possibly asynchronously) and returns any new values.
+	 * @param callback Optional callback that takes the validated value, processes it (possibly asynchronously) and returns any new values.
+	 * @param args Additional arguments forwarded to the callback.
+	 * @returns `true` on success, `false` on validation failure (or a `Promise` resolving to one).
+	 * @example store.submit(saveUser)
+	 * @see https://dhoulb.github.io/shelving/ui/form/FormStore/FormStore/submit
 	 */
 	submit<A extends Arguments>(callback?: ((value: T, ...args: A) => void) | undefined, ...args: A): boolean | Promise<boolean> {
 		try {

package/ui/form/Input.d.ts

@@ -1,18 +1,82 @@
 import type { ReactElement } from "react";
 import type { ChildProps } from "../util/props.js";
+/**
+ * `className` for a `<input type="radio">` element.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/RADIO_CLASS
+ */
 export declare const RADIO_CLASS: any;
+/**
+ * `className` for a `<input type="checkbox">` element.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/CHECKBOX_CLASS
+ */
 export declare const CHECKBOX_CLASS: any;
+/**
+ * Base `className` shared by all input elements.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/INPUT_CLASS
+ */
 export declare const INPUT_CLASS: any;
+/**
+ * `className` applied to an input when it's showing placeholder content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/PLACEHOLDER_CLASS
+ */
 export declare const PLACEHOLDER_CLASS: any;
+/**
+ * `className` for the empty/placeholder `<option>` of a `<select>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/EMPTY_OPTION_CLASS
+ */
 export declare const EMPTY_OPTION_CLASS: any;
+/**
+ * `className` for a value-bearing `<option>` of a `<select>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/VALUE_OPTION_CLASS
+ */
 export declare const VALUE_OPTION_CLASS: any;
+/**
+ * Precomposed `className` for a single-line text `<input>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/TEXT_INPUT_CLASS
+ */
 export declare const TEXT_INPUT_CLASS: string;
+/**
+ * Precomposed `className` for a multiline `<textarea>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/MULTILINE_TEXT_INPUT_CLASS
+ */
 export declare const MULTILINE_TEXT_INPUT_CLASS: string;
+/**
+ * Precomposed `className` for an input wrapper that hosts `data-slot` icon elements.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/WRAPPER_INPUT_CLASS
+ */
 export declare const WRAPPER_INPUT_CLASS: string;
+/**
+ * Precomposed `className` for a `<select>` input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/SELECT_INPUT_CLASS
+ */
 export declare const SELECT_INPUT_CLASS: string;
+/**
+ * Precomposed `className` for a button styled as an input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/BUTTON_INPUT_CLASS
+ */
 export declare const BUTTON_INPUT_CLASS: string;
+/**
+ * Precomposed `className` for a `<label>` styled as an input (e.g. checkbox/radio wrappers).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/LABEL_INPUT_CLASS
+ */
 export declare const LABEL_INPUT_CLASS: string;
-/** Props all inputs allow. */
+/**
+ * Base props shared by every form input (name, title, placeholder, required/disabled state, and error message).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/InputProps
+ */
 export interface InputProps {
     /** The `name=""` prop of the input. */
     name: string;

package/ui/form/Input.js

@@ -4,18 +4,78 @@ import { getFlexClass } from "../style/Flex.js";
 import { getClass } from "../util/css.js";
 import INPUT_CSS from "./Input.module.css";
 // Classes.
+/**
+ * `className` for a `<input type="radio">` element.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/RADIO_CLASS
+ */
 export const RADIO_CLASS = INPUT_CSS.radio;
+/**
+ * `className` for a `<input type="checkbox">` element.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/CHECKBOX_CLASS
+ */
 export const CHECKBOX_CLASS = INPUT_CSS.radio;
+/**
+ * Base `className` shared by all input elements.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/INPUT_CLASS
+ */
 export const INPUT_CLASS = INPUT_CSS.input;
+/**
+ * `className` applied to an input when it's showing placeholder content.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/PLACEHOLDER_CLASS
+ */
 export const PLACEHOLDER_CLASS = INPUT_CSS.placeholder;
+/**
+ * `className` for the empty/placeholder `<option>` of a `<select>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/EMPTY_OPTION_CLASS
+ */
 export const EMPTY_OPTION_CLASS = INPUT_CSS.empty;
+/**
+ * `className` for a value-bearing `<option>` of a `<select>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/VALUE_OPTION_CLASS
+ */
 export const VALUE_OPTION_CLASS = INPUT_CSS.value;
 // Precomposed classes.
+/**
+ * Precomposed `className` for a single-line text `<input>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/TEXT_INPUT_CLASS
+ */
 export const TEXT_INPUT_CLASS = getClass(INPUT_CSS.input, INPUT_CSS.text);
+/**
+ * Precomposed `className` for a multiline `<textarea>`.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/MULTILINE_TEXT_INPUT_CLASS
+ */
 export const MULTILINE_TEXT_INPUT_CLASS = getClass(TEXT_INPUT_CLASS, INPUT_CSS.multiline);
+/**
+ * Precomposed `className` for an input wrapper that hosts `data-slot` icon elements.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/WRAPPER_INPUT_CLASS
+ */
 export const WRAPPER_INPUT_CLASS = getClass(INPUT_CSS.input, INPUT_CSS.wrapper);
+/**
+ * Precomposed `className` for a `<select>` input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/SELECT_INPUT_CLASS
+ */
 export const SELECT_INPUT_CLASS = getClass(INPUT_CSS.input, INPUT_CSS.select);
+/**
+ * Precomposed `className` for a button styled as an input.
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/BUTTON_INPUT_CLASS
+ */
 export const BUTTON_INPUT_CLASS = getClass(INPUT_CSS.input, INPUT_CSS.button);
+/**
+ * Precomposed `className` for a `<label>` styled as an input (e.g. checkbox/radio wrappers).
+ *
+ * @see https://dhoulb.github.io/shelving/ui/form/Input/LABEL_INPUT_CLASS
+ */
 export const LABEL_INPUT_CLASS = getClass(INPUT_CSS.input, INPUT_CSS.label);
 /** Input that is loading. */
 export const LOADING_INPUT = _jsx("div", { className: getClass(INPUT_CLASS, getFlexClass({})), children: LOADING });