@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/compositions/form-kit/form-fields.js

@@ -0,0 +1,233 @@
+import { Checkbox } from "../../components/ui/checkbox.js";
+import { Input } from "../../components/ui/input.js";
+import { Textarea } from "../../components/ui/textarea.js";
+import { Field, FieldContent, FieldDescription, FieldError, FieldLabel } from "../../components/ui/field.js";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../../components/ui/select.js";
+import { Switch } from "../../components/ui/switch.js";
+import { useFieldContext } from "./form-context.js";
+import { useId } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { useStore } from "@tanstack/react-form";
+//#region src/compositions/form-kit/form-fields.tsx
+/**
+* Normalizes TanStack Form's `field.state.meta.errors` into the messages
+* shadcn's `FieldError` renders. Validators return strings (function
+* validators) or Standard Schema issues such as Zod's (`{ message }`);
+* anything without a non-empty message is dropped.
+*/
+function toFieldErrors(errors) {
+	const messages = [];
+	for (const error of errors) if (Array.isArray(error)) messages.push(...toFieldErrors(error));
+	else if (typeof error === "string") {
+		if (error) messages.push({ message: error });
+	} else if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string" && error.message) messages.push({ message: error.message });
+	return messages;
+}
+/**
+* Binds the field in the surrounding `form.AppField` to shadcn's `field`
+* markup: the control, description and error ids, the invalid state, and the
+* control's ARIA wiring. The kit's field components use it; an app uses it to
+* write a field component of its own with the same error association.
+*
+* A field is invalid once it is touched and has errors, as in shadcn's
+* TanStack Form guide. Submitting touches every field.
+*/
+function useFormField({ hasDescription }) {
+	const field = useFieldContext();
+	const value = useStore(field.store, (state) => state.value);
+	const meta = useStore(field.store, (state) => state.meta);
+	const baseId = useId();
+	const controlId = `${baseId}-control`;
+	const descriptionId = `${baseId}-description`;
+	const errorId = `${baseId}-error`;
+	const isInvalid = meta.isTouched && !meta.isValid;
+	const errors = isInvalid ? toFieldErrors(meta.errors) : [];
+	const describedBy = [hasDescription ? descriptionId : null, errors.length > 0 ? errorId : null].filter(Boolean).join(" ");
+	return {
+		field,
+		value,
+		isInvalid,
+		errors,
+		controlId,
+		descriptionId,
+		errorId,
+		controlProps: {
+			id: controlId,
+			name: field.name,
+			"aria-invalid": isInvalid,
+			"aria-describedby": describedBy || void 0
+		}
+	};
+}
+function FieldMessages({ description, descriptionId, errors, errorId }) {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [description ? /* @__PURE__ */ jsx(FieldDescription, {
+		id: descriptionId,
+		children: description
+	}) : null, /* @__PURE__ */ jsx(FieldError, {
+		id: errorId,
+		errors
+	})] });
+}
+/** A string field rendered as a shadcn `Input`. Use inside `form.AppField`. */
+function TextField({ label, description, className, type = "text", ...inputProps }) {
+	const { field, value, isInvalid, errors, descriptionId, errorId, controlProps } = useFormField({ hasDescription: Boolean(description) });
+	return /* @__PURE__ */ jsxs(Field, {
+		"data-invalid": isInvalid,
+		"data-disabled": inputProps.disabled,
+		className,
+		children: [
+			/* @__PURE__ */ jsx(FieldLabel, {
+				htmlFor: controlProps.id,
+				children: label
+			}),
+			/* @__PURE__ */ jsx(Input, {
+				...inputProps,
+				...controlProps,
+				type,
+				value,
+				onBlur: field.handleBlur,
+				onChange: (event) => field.handleChange(event.target.value)
+			}),
+			/* @__PURE__ */ jsx(FieldMessages, {
+				description,
+				descriptionId,
+				errors,
+				errorId
+			})
+		]
+	});
+}
+/** A string field rendered as a shadcn `Textarea`. Use inside `form.AppField`. */
+function TextareaField({ label, description, className, ...textareaProps }) {
+	const { field, value, isInvalid, errors, descriptionId, errorId, controlProps } = useFormField({ hasDescription: Boolean(description) });
+	return /* @__PURE__ */ jsxs(Field, {
+		"data-invalid": isInvalid,
+		"data-disabled": textareaProps.disabled,
+		className,
+		children: [
+			/* @__PURE__ */ jsx(FieldLabel, {
+				htmlFor: controlProps.id,
+				children: label
+			}),
+			/* @__PURE__ */ jsx(Textarea, {
+				...textareaProps,
+				...controlProps,
+				value,
+				onBlur: field.handleBlur,
+				onChange: (event) => field.handleChange(event.target.value)
+			}),
+			/* @__PURE__ */ jsx(FieldMessages, {
+				description,
+				descriptionId,
+				errors,
+				errorId
+			})
+		]
+	});
+}
+/**
+* A string field rendered as a shadcn `Select`. The empty string means "no
+* choice", so a schema rejects it to make the field required. The field
+* counts as blurred when its popup closes. Use inside `form.AppField`.
+*/
+function SelectField({ label, description, className, options, placeholder, disabled }) {
+	const { field, value, isInvalid, errors, descriptionId, errorId, controlProps } = useFormField({ hasDescription: Boolean(description) });
+	const { name, ...triggerProps } = controlProps;
+	return /* @__PURE__ */ jsxs(Field, {
+		"data-invalid": isInvalid,
+		"data-disabled": disabled,
+		className,
+		children: [
+			/* @__PURE__ */ jsx(FieldLabel, {
+				htmlFor: controlProps.id,
+				children: label
+			}),
+			/* @__PURE__ */ jsxs(Select, {
+				name,
+				items: options,
+				value: value === "" ? null : value,
+				onValueChange: (next) => field.handleChange(next ?? ""),
+				onOpenChange: (open) => {
+					if (!open) field.handleBlur();
+				},
+				disabled,
+				children: [/* @__PURE__ */ jsx(SelectTrigger, {
+					...triggerProps,
+					className: "w-full",
+					children: /* @__PURE__ */ jsx(SelectValue, { placeholder })
+				}), /* @__PURE__ */ jsx(SelectContent, {
+					alignItemWithTrigger: false,
+					children: options.map((option) => /* @__PURE__ */ jsx(SelectItem, {
+						value: option.value,
+						disabled: option.disabled,
+						children: option.label
+					}, option.value))
+				})]
+			}),
+			/* @__PURE__ */ jsx(FieldMessages, {
+				description,
+				descriptionId,
+				errors,
+				errorId
+			})
+		]
+	});
+}
+/**
+* A boolean field rendered as a shadcn `Checkbox`, with the label, description
+* and error beside it. Use inside `form.AppField`.
+*/
+function CheckboxField({ label, description, className, disabled }) {
+	const { field, value, isInvalid, errors, descriptionId, errorId, controlProps } = useFormField({ hasDescription: Boolean(description) });
+	return /* @__PURE__ */ jsxs(Field, {
+		orientation: "horizontal",
+		"data-invalid": isInvalid,
+		"data-disabled": disabled,
+		className,
+		children: [/* @__PURE__ */ jsx(Checkbox, {
+			...controlProps,
+			checked: value,
+			onCheckedChange: (checked) => field.handleChange(checked),
+			onBlur: field.handleBlur,
+			disabled
+		}), /* @__PURE__ */ jsxs(FieldContent, { children: [/* @__PURE__ */ jsx(FieldLabel, {
+			htmlFor: controlProps.id,
+			children: label
+		}), /* @__PURE__ */ jsx(FieldMessages, {
+			description,
+			descriptionId,
+			errors,
+			errorId
+		})] })]
+	});
+}
+/**
+* A boolean field rendered as a shadcn `Switch`, with the label, description
+* and error before it. Use inside `form.AppField`.
+*/
+function SwitchField({ label, description, className, disabled }) {
+	const { field, value, isInvalid, errors, descriptionId, errorId, controlProps } = useFormField({ hasDescription: Boolean(description) });
+	return /* @__PURE__ */ jsxs(Field, {
+		orientation: "horizontal",
+		"data-invalid": isInvalid,
+		"data-disabled": disabled,
+		className,
+		children: [/* @__PURE__ */ jsxs(FieldContent, { children: [/* @__PURE__ */ jsx(FieldLabel, {
+			htmlFor: controlProps.id,
+			children: label
+		}), /* @__PURE__ */ jsx(FieldMessages, {
+			description,
+			descriptionId,
+			errors,
+			errorId
+		})] }), /* @__PURE__ */ jsx(Switch, {
+			...controlProps,
+			checked: value,
+			onCheckedChange: (checked) => field.handleChange(checked),
+			onBlur: field.handleBlur,
+			disabled
+		})]
+	});
+}
+//#endregion
+export { CheckboxField, SelectField, SwitchField, TextField, TextareaField, toFieldErrors, useFormField };

package/dist/compositions/form-kit/form-kit.d.ts

@@ -0,0 +1,128 @@
+import { Button } from "../../components/ui/button.js";
+import { Alert } from "../../components/ui/alert.js";
+import { CheckboxField, SelectField, SwitchField, TextField, TextareaField } from "./form-fields.js";
+import * as React from "react";
+//#region src/compositions/form-kit/form-kit.d.ts
+export type FormProps = Omit<React.ComponentProps<"form">, "onSubmit" | "noValidate">;
+/**
+ * The `<form>` element of an app form. It runs `form.handleSubmit()` on
+ * submit, skips native browser validation (the form's validators own it),
+ * and marks itself busy while the submit is pending. A submit started while
+ * one is pending is dropped, so a pressed Enter key cannot send twice.
+ *
+ * If `onSubmit` rejects, the rejection is caught and shown by `SubmitError`
+ * until the next submit. Nothing retries on its own.
+ *
+ * Use as `form.Form` inside `form.AppForm`.
+ */
+export declare function Form({ children, ...props }: FormProps): React.JSX.Element;
+export type SubmitButtonProps = Omit<React.ComponentProps<typeof Button>, "type"> & {
+  /** Label shown while the submit is pending. Defaults to the children. */
+  pendingLabel?: React.ReactNode;
+};
+/**
+ * The submit button of an app form. While the submit is pending it is
+ * disabled (it keeps focus) and shows a spinner. Use as `form.SubmitButton`
+ * inside `form.AppForm`.
+ */
+export declare function SubmitButton({ children, pendingLabel, disabled, ...props }: SubmitButtonProps): React.JSX.Element;
+export type SubmitErrorProps = Omit<React.ComponentProps<typeof Alert>, "children" | "variant" | "title"> & {
+  /**
+   * The app's error from the last submit, for example a mutation's message.
+   * When unset, the message of a rejected `onSubmit` is shown instead.
+   */
+  error?: React.ReactNode;
+  /** The alert title. */
+  title?: React.ReactNode;
+  /** Shown when `onSubmit` rejected with something that is not an `Error`. */
+  fallbackMessage?: React.ReactNode;
+};
+/**
+ * The submit failure of an app form, as a destructive alert announced to
+ * assistive technology. It renders nothing while there is no failure. Use as
+ * `form.SubmitError` inside `form.Form`, usually just above the actions.
+ */
+export declare function SubmitError({ error, title, fallbackMessage, ...props }: SubmitErrorProps): React.JSX.Element | null;
+/**
+ * The Form kit: TanStack Form's `createFormHook` bound to shadcn's `field`
+ * components, following shadcn's TanStack Form guide. App code writes one
+ * line per field:
+ *
+ * ```tsx
+ * const form = useAppForm({ defaultValues, validators: { onSubmit: schema }, onSubmit });
+ * <form.AppForm>
+ *   <form.Form>
+ *     <form.AppField name="subject">{(field) => <field.TextField label="Subject" />}</form.AppField>
+ *     <form.SubmitError />
+ *     <form.SubmitButton>Save</form.SubmitButton>
+ *   </form.Form>
+ * </form.AppForm>
+ * ```
+ */
+export declare const useAppForm: <TFormData, TOnMount extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChange extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TSubmitMeta>(props: import("@tanstack/react-form").FormOptions<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta>) => import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, {
+  readonly TextField: typeof TextField;
+  readonly TextareaField: typeof TextareaField;
+  readonly SelectField: typeof SelectField;
+  readonly CheckboxField: typeof CheckboxField;
+  readonly SwitchField: typeof SwitchField;
+}, {
+  readonly Form: typeof Form;
+  readonly SubmitButton: typeof SubmitButton;
+  readonly SubmitError: typeof SubmitError;
+}>, withForm: <TFormData, TOnMount extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChange extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TSubmitMeta, TRenderProps extends object = {}>({ render, props }: import("@tanstack/react-form").WithFormProps<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, {
+  readonly TextField: typeof TextField;
+  readonly TextareaField: typeof TextareaField;
+  readonly SelectField: typeof SelectField;
+  readonly CheckboxField: typeof CheckboxField;
+  readonly SwitchField: typeof SwitchField;
+}, {
+  readonly Form: typeof Form;
+  readonly SubmitButton: typeof SubmitButton;
+  readonly SubmitError: typeof SubmitError;
+}, TRenderProps>) => React.FunctionComponent<React.PropsWithChildren<NoInfer<[unknown] extends [TRenderProps] ? any : TRenderProps> & {
+  form: import("@tanstack/react-form").AppFieldExtendedReactFormApi<[unknown] extends [TFormData] ? any : TFormData, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnMount] ? [TOnMount] extends [TOnMount & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnMount : TOnMount, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnChange] ? [TOnChange] extends [TOnChange & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnChange : TOnChange, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnChangeAsync] ? [TOnChangeAsync] extends [TOnChangeAsync & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnChangeAsync : TOnChangeAsync, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnBlur] ? [TOnBlur] extends [TOnBlur & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlur : TOnBlur, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnBlurAsync] ? [TOnBlurAsync] extends [TOnBlurAsync & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlurAsync : TOnBlurAsync, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnSubmit] ? [TOnSubmit] extends [TOnSubmit & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmit : TOnSubmit, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnSubmitAsync] ? [TOnSubmitAsync] extends [TOnSubmitAsync & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmitAsync : TOnSubmitAsync, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnDynamic] ? [TOnDynamic] extends [TOnDynamic & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamic : TOnDynamic, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnDynamicAsync] ? [TOnDynamicAsync] extends [TOnDynamicAsync & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamicAsync : TOnDynamicAsync, [import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined] extends [TOnServer] ? [TOnServer] extends [TOnServer & (import("@tanstack/react-form").FormValidateOrFn<TFormData> | undefined)] ? any : TOnServer : TOnServer, [unknown] extends [TSubmitMeta] ? any : TSubmitMeta, {
+    readonly TextField: typeof TextField;
+    readonly TextareaField: typeof TextareaField;
+    readonly SelectField: typeof SelectField;
+    readonly CheckboxField: typeof CheckboxField;
+    readonly SwitchField: typeof SwitchField;
+  }, {
+    readonly Form: typeof Form;
+    readonly SubmitButton: typeof SubmitButton;
+    readonly SubmitError: typeof SubmitError;
+  }>;
+}>>, withFieldGroup: <TFieldGroupData, TSubmitMeta, TRenderProps extends object = {}>({ render, props, defaultValues }: import("@tanstack/react-form").WithFieldGroupProps<TFieldGroupData, {
+  readonly TextField: typeof TextField;
+  readonly TextareaField: typeof TextareaField;
+  readonly SelectField: typeof SelectField;
+  readonly CheckboxField: typeof CheckboxField;
+  readonly SwitchField: typeof SwitchField;
+}, {
+  readonly Form: typeof Form;
+  readonly SubmitButton: typeof SubmitButton;
+  readonly SubmitError: typeof SubmitError;
+}, TSubmitMeta, TRenderProps>) => <TFormData, TFields extends import("@tanstack/react-form").DeepKeysOfType<TFormData, TFieldGroupData | null | undefined> | import("@tanstack/react-form").FieldsMap<TFormData, TFieldGroupData>, TOnMount extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChange extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnChangeAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnBlur extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnBlurAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnSubmit extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnSubmitAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnDynamic extends undefined | import("@tanstack/react-form").FormValidateOrFn<TFormData>, TOnDynamicAsync extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TOnServer extends undefined | import("@tanstack/react-form").FormAsyncValidateOrFn<TFormData>, TFormSubmitMeta>(params: React.PropsWithChildren<NoInfer<TRenderProps> & {
+  form: import("@tanstack/react-form").AppFieldExtendedReactFieldGroupApi<unknown, TFormData, string | import("@tanstack/react-form").FieldsMap<unknown, TFormData>, any, any, any, any, any, any, any, any, any, any, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, {
+    readonly TextField: typeof TextField;
+    readonly TextareaField: typeof TextareaField;
+    readonly SelectField: typeof SelectField;
+    readonly CheckboxField: typeof CheckboxField;
+    readonly SwitchField: typeof SwitchField;
+  }, {
+    readonly Form: typeof Form;
+    readonly SubmitButton: typeof SubmitButton;
+    readonly SubmitError: typeof SubmitError;
+  }> | import("@tanstack/react-form").AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, {
+    readonly TextField: typeof TextField;
+    readonly TextareaField: typeof TextareaField;
+    readonly SelectField: typeof SelectField;
+    readonly CheckboxField: typeof CheckboxField;
+    readonly SwitchField: typeof SwitchField;
+  }, {
+    readonly Form: typeof Form;
+    readonly SubmitButton: typeof SubmitButton;
+    readonly SubmitError: typeof SubmitError;
+  }>;
+  fields: TFields;
+}>) => ReturnType<React.FunctionComponent>;
+//#endregion

package/dist/compositions/form-kit/form-kit.js

@@ -0,0 +1,119 @@
+import { Alert, AlertDescription, AlertTitle } from "../../components/ui/alert.js";
+import { Spinner } from "../../components/ui/spinner.js";
+import { Button } from "../../components/ui/button.js";
+import { fieldContext, formContext, useFormContext } from "./form-context.js";
+import { CheckboxField, SelectField, SwitchField, TextField, TextareaField } from "./form-fields.js";
+import { createContext, useContext, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CircleAlertIcon } from "lucide-react";
+import { createFormHook, useStore } from "@tanstack/react-form";
+//#region src/compositions/form-kit/form-kit.tsx
+const SubmitFailureContext = createContext(null);
+/**
+* The `<form>` element of an app form. It runs `form.handleSubmit()` on
+* submit, skips native browser validation (the form's validators own it),
+* and marks itself busy while the submit is pending. A submit started while
+* one is pending is dropped, so a pressed Enter key cannot send twice.
+*
+* If `onSubmit` rejects, the rejection is caught and shown by `SubmitError`
+* until the next submit. Nothing retries on its own.
+*
+* Use as `form.Form` inside `form.AppForm`.
+*/
+function Form({ children, ...props }) {
+	const form = useFormContext();
+	const isSubmitting = useStore(form.store, (state) => state.isSubmitting);
+	const [failure, setFailure] = useState(null);
+	const handleSubmit = (event) => {
+		event.preventDefault();
+		event.stopPropagation();
+		if (form.state.isSubmitting) return;
+		setFailure(null);
+		form.handleSubmit().catch((error) => setFailure({ error }));
+	};
+	return /* @__PURE__ */ jsx(SubmitFailureContext, {
+		value: failure,
+		children: /* @__PURE__ */ jsx("form", {
+			...props,
+			"data-slot": "form-kit-form",
+			noValidate: true,
+			"aria-busy": isSubmitting || void 0,
+			onSubmit: handleSubmit,
+			children
+		})
+	});
+}
+/**
+* The submit button of an app form. While the submit is pending it is
+* disabled (it keeps focus) and shows a spinner. Use as `form.SubmitButton`
+* inside `form.AppForm`.
+*/
+function SubmitButton({ children, pendingLabel, disabled, ...props }) {
+	const form = useFormContext();
+	const isSubmitting = useStore(form.store, (state) => state.isSubmitting);
+	return /* @__PURE__ */ jsxs(Button, {
+		...props,
+		type: "submit",
+		disabled: disabled || isSubmitting,
+		focusableWhenDisabled: true,
+		children: [isSubmitting ? /* @__PURE__ */ jsx(Spinner, {
+			"data-icon": "inline-start",
+			"aria-hidden": "true"
+		}) : null, isSubmitting && pendingLabel ? pendingLabel : children]
+	});
+}
+/**
+* The submit failure of an app form, as a destructive alert announced to
+* assistive technology. It renders nothing while there is no failure. Use as
+* `form.SubmitError` inside `form.Form`, usually just above the actions.
+*/
+function SubmitError({ error, title = "Could not submit", fallbackMessage = "Something went wrong. Try again.", ...props }) {
+	const failure = useContext(SubmitFailureContext);
+	const caught = failure ? failure.error instanceof Error && failure.error.message ? failure.error.message : fallbackMessage : null;
+	const message = error ?? caught;
+	if (!message) return null;
+	return /* @__PURE__ */ jsxs(Alert, {
+		...props,
+		"data-slot": "form-kit-submit-error",
+		variant: "destructive",
+		children: [
+			/* @__PURE__ */ jsx(CircleAlertIcon, { "aria-hidden": "true" }),
+			/* @__PURE__ */ jsx(AlertTitle, { children: title }),
+			/* @__PURE__ */ jsx(AlertDescription, { children: message })
+		]
+	});
+}
+/**
+* The Form kit: TanStack Form's `createFormHook` bound to shadcn's `field`
+* components, following shadcn's TanStack Form guide. App code writes one
+* line per field:
+*
+* ```tsx
+* const form = useAppForm({ defaultValues, validators: { onSubmit: schema }, onSubmit });
+* <form.AppForm>
+*   <form.Form>
+*     <form.AppField name="subject">{(field) => <field.TextField label="Subject" />}</form.AppField>
+*     <form.SubmitError />
+*     <form.SubmitButton>Save</form.SubmitButton>
+*   </form.Form>
+* </form.AppForm>
+* ```
+*/
+const { useAppForm, withForm, withFieldGroup } = createFormHook({
+	fieldContext,
+	formContext,
+	fieldComponents: {
+		TextField,
+		TextareaField,
+		SelectField,
+		CheckboxField,
+		SwitchField
+	},
+	formComponents: {
+		Form,
+		SubmitButton,
+		SubmitError
+	}
+});
+//#endregion
+export { Form, SubmitButton, SubmitError, useAppForm, withFieldGroup, withForm };

package/dist/compositions/inspector/inspector.d.ts

@@ -0,0 +1,53 @@
+import { SheetContent } from "../../components/ui/sheet.js";
+import * as React from "react";
+//#region src/compositions/inspector/inspector.d.ts
+export interface InspectorSection {
+  /** Stable key. Defaults to `label`. */
+  id?: string;
+  /** The section's heading. */
+  label: string;
+  content: React.ReactNode;
+}
+export interface InspectorProps {
+  /** Whether the sheet is open. The app owns this state. */
+  open: boolean;
+  /** Called when the sheet asks to close (Escape, the close button, the backdrop). */
+  onOpenChange: (open: boolean) => void;
+  /** What is being inspected, for example the row's subject. It names the sheet. */
+  title: React.ReactNode;
+  /** A supporting line under the title. */
+  description?: React.ReactNode;
+  /** The details, one headed section each, in display order. */
+  sections: readonly InspectorSection[];
+  /** Actions pinned to the bottom of the sheet, for example buttons. */
+  footer?: React.ReactNode;
+  /** Which edge the sheet slides in from. */
+  side?: "left" | "right";
+  /** Show placeholder lines while the details load. */
+  isLoading?: boolean;
+  /** Plain-text load error, shown in place of the sections. */
+  error?: string;
+  /** Offer a retry next to `error`. Retrying is the owner's action. */
+  onRetry?: () => void;
+  /** Text shown when there are no sections. */
+  emptyLabel?: string;
+  /**
+   * Where focus goes when the sheet opens. Defaults to the sheet itself, so a
+   * screen reader announces the title and the first Tab reaches the first
+   * control, instead of focus landing in a field the owner did not choose.
+   */
+  initialFocus?: React.ComponentProps<typeof SheetContent>["initialFocus"];
+  /**
+   * Where focus goes once the sheet closes. Defaults to the element focused
+   * before it opened, such as the row that opened it.
+   */
+  finalFocus?: React.ComponentProps<typeof SheetContent>["finalFocus"];
+  className?: string;
+}
+/**
+ * A side sheet with the details of one row: a title, headed sections and
+ * footer actions. While open it is modal: focus stays inside it, and Escape
+ * closes it and returns focus to where it was.
+ */
+export declare function Inspector({ open, onOpenChange, title, description, sections, footer, side, isLoading, error, onRetry, emptyLabel, initialFocus, finalFocus, className }: InspectorProps): React.JSX.Element;
+//#endregion

package/dist/compositions/inspector/inspector.js

@@ -0,0 +1,80 @@
+import { Separator } from "../../components/ui/separator.js";
+import { ScrollArea } from "../../components/ui/scroll-area.js";
+import { Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from "../../components/ui/sheet.js";
+import { EmptyState, ErrorState, Loading } from "../state-blocks/state-blocks.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "cn";
+//#region src/compositions/inspector/inspector.tsx
+/**
+* A side sheet with the details of one row: a title, headed sections and
+* footer actions. While open it is modal: focus stays inside it, and Escape
+* closes it and returns focus to where it was.
+*/
+function Inspector({ open, onOpenChange, title, description, sections, footer, side = "right", isLoading = false, error, onRetry, emptyLabel = "No details", initialFocus, finalFocus, className }) {
+	const baseId = React.useId();
+	const popupRef = React.useRef(null);
+	const showSections = !isLoading && !error && sections.length > 0;
+	return /* @__PURE__ */ jsx(Sheet, {
+		open,
+		onOpenChange,
+		children: /* @__PURE__ */ jsxs(SheetContent, {
+			side,
+			"data-slot": "inspector",
+			"aria-busy": isLoading || void 0,
+			ref: popupRef,
+			initialFocus: initialFocus ?? popupRef,
+			finalFocus,
+			className: cn("gap-0 outline-none data-[side=left]:w-full data-[side=right]:w-full data-[side=left]:sm:max-w-md data-[side=right]:sm:max-w-md", className),
+			children: [
+				/* @__PURE__ */ jsxs(SheetHeader, {
+					className: "border-b p-4 pr-12",
+					children: [/* @__PURE__ */ jsx(SheetTitle, { children: title }), description ? /* @__PURE__ */ jsx(SheetDescription, { children: description }) : null]
+				}),
+				/* @__PURE__ */ jsx(ScrollArea, {
+					"data-slot": "inspector-body",
+					className: "min-h-0 flex-1",
+					children: /* @__PURE__ */ jsxs("div", {
+						className: "flex flex-col gap-4 p-4",
+						children: [
+							isLoading ? /* @__PURE__ */ jsx(Loading, {
+								label: "Loading details",
+								variant: "text",
+								rows: 6
+							}) : null,
+							!isLoading && error ? /* @__PURE__ */ jsx(ErrorState, {
+								title: error,
+								onRetry
+							}) : null,
+							!isLoading && !error && sections.length === 0 ? /* @__PURE__ */ jsx(EmptyState, { title: emptyLabel }) : null,
+							showSections ? sections.map((section, index) => {
+								const key = section.id ?? section.label;
+								const headingId = `${baseId}-section-${index}`;
+								return /* @__PURE__ */ jsxs(React.Fragment, { children: [index > 0 ? /* @__PURE__ */ jsx(Separator, {}) : null, /* @__PURE__ */ jsxs("section", {
+									"aria-labelledby": headingId,
+									"data-slot": "inspector-section",
+									className: "flex flex-col gap-2",
+									children: [/* @__PURE__ */ jsx("h3", {
+										id: headingId,
+										className: "font-heading text-xs font-medium text-muted-foreground",
+										children: section.label
+									}), /* @__PURE__ */ jsx("div", {
+										className: "text-xs/relaxed text-foreground",
+										children: section.content
+									})]
+								})] }, key);
+							}) : null
+						]
+					})
+				}),
+				footer ? /* @__PURE__ */ jsx(SheetFooter, {
+					"data-slot": "inspector-footer",
+					className: "mt-0 flex-row flex-wrap justify-end border-t p-4",
+					children: footer
+				}) : null
+			]
+		})
+	});
+}
+//#endregion
+export { Inspector };

package/dist/compositions/layout.d.ts

@@ -0,0 +1,36 @@
+import { ComponentProps, ReactElement, ReactNode } from "react";
+//#region src/compositions/layout.d.ts
+export interface PageProps extends Omit<ComponentProps<"main">, "title"> {
+  readonly actions?: ReactNode;
+  readonly backLink?: {
+    readonly href: string;
+    readonly label: string;
+    readonly onClick?: ComponentProps<"a">["onClick"];
+  };
+  readonly subtitle?: ReactNode;
+  readonly title: ReactNode;
+  readonly titleMetadata?: ReactNode;
+}
+export declare function Page({ actions, backLink, children, className, subtitle, title, titleMetadata, ...props }: PageProps): ReactElement;
+export interface SectionProps extends Omit<ComponentProps<"section">, "title"> {
+  readonly actions?: ReactNode;
+  readonly title?: ReactNode;
+}
+export declare function Section({ actions, children, className, title, ...props }: SectionProps): ReactElement;
+export type LayoutGap = "none" | "small" | "default" | "large";
+export interface StackProps extends ComponentProps<"div"> {
+  readonly align?: "start" | "center" | "end" | "stretch";
+  readonly direction?: "horizontal" | "vertical";
+  readonly gap?: LayoutGap;
+  readonly justify?: "start" | "center" | "end" | "between";
+  readonly wrap?: boolean;
+}
+export declare function Stack({ align, className, direction, gap, justify, style, wrap, ...props }: StackProps): ReactElement;
+export interface GridProps extends ComponentProps<"div"> {
+  readonly columns?: 1 | 2 | 3 | 4;
+  readonly gap?: LayoutGap;
+}
+export declare function Grid({ className, columns, gap, style, ...props }: GridProps): ReactElement;
+export interface LinkProps extends ComponentProps<"a"> {}
+export declare function Link({ className, ...props }: LinkProps): ReactElement;
+//#endregion