@fungi.computer/caps 0.0.0-stage → 0.0.1

package/docs/api/form.md

@@ -0,0 +1,1623 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/caps**](README.md)
+
+---
+
+[@fungi.computer/caps](README.md) / form
+
+# form
+
+## converting
+
+### effectValidator
+
+```ts
+const effectValidator: <S>(
+  self,
+  options?,
+) => StandardSchemaV1<S["Encoded"], S["Type"]> & S = Schema.toStandardSchemaV1;
+```
+
+Effect's maintained Standard Schema adapter, including nested issue paths.
+
+Returns a "Standard Schema" object conforming to the
+[Standard Schema v1](https://standardschema.dev/) specification.
+
+**Details**
+
+This function creates a schema whose `validate` method attempts to decode and
+validate the provided input synchronously. If the underlying `Schema` includes
+any asynchronous components (e.g., asynchronous message resolutions or checks),
+then validation will necessarily return a `Promise` instead.
+
+**Example** (Creating a standard schema from a regular schema)
+
+```ts import.meta.vitest
+import { Schema } from "effect";
+
+// Define custom hook functions for error formatting
+const leafHook = (issue: any) => {
+  switch (issue._tag) {
+    case "InvalidType":
+      return "Expected different type";
+    case "InvalidValue":
+      return "Invalid value provided";
+    case "MissingKey":
+      return "Required property missing";
+    case "UnexpectedKey":
+      return "Unexpected property found";
+    case "Forbidden":
+      return "Operation not allowed";
+    case "OneOf":
+      return "Multiple valid options available";
+    default:
+      return "Validation error";
+  }
+};
+
+// Create a standard schema from a regular schema
+const PersonSchema = Schema.Struct({
+  name: Schema.NonEmptyString,
+  age: Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 150 })),
+});
+
+const standardSchema = Schema.toStandardSchemaV1(PersonSchema, {
+  leafHook,
+});
+
+// The standard schema can be used with any Standard Schema v1 compatible library
+const validResult = standardSchema["~standard"].validate({
+  name: "Alice",
+  age: 30,
+});
+const invalidResult = standardSchema["~standard"].validate({
+  name: "",
+  age: 200,
+});
+
+if (validResult instanceof Promise || invalidResult instanceof Promise) {
+  throw new Error("Expected synchronous validation");
+}
+if ("value" in validResult) {
+  validResult.value; // => { name: "Alice", age: 30 }
+}
+invalidResult.issues?.map((issue) => issue.path); // => [["name"], ["age"]]
+```
+
+#### Type Parameters
+
+| Type Parameter                                          |
+| ------------------------------------------------------- |
+| `S` _extends_ `ConstraintDecoder`\<`unknown`, `never`\> |
+
+#### Parameters
+
+| Parameter  | Type  |
+| ---------- | ----- |
+| `self`     | `S`   |
+| `options?` | \{ \} |
+
+#### Returns
+
+`StandardSchemaV1`\<`S`\[`"Encoded"`\], `S`\[`"Type"`\]\> & `S`
+
+#### Stability
+
+stable
+
+#### Since
+
+4.0.0
+
+## Other
+
+### fieldError()
+
+```ts
+function fieldError(meta): string | undefined;
+```
+
+First readable TanStack string error or Standard Schema issue.
+
+#### Parameters
+
+| Parameter     | Type                                  |
+| ------------- | ------------------------------------- |
+| `meta`        | \{ `errors`: readonly `unknown`[]; \} |
+| `meta.errors` | readonly `unknown`[]                  |
+
+#### Returns
+
+`string` \| `undefined`
+
+---
+
+### FormFieldsProps
+
+```ts
+type FormFieldsProps<V> = object;
+```
+
+Props accepted by FormFields.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+
+#### Properties
+
+##### model
+
+```ts
+model: SchemaFormModel<V>;
+```
+
+##### names?
+
+```ts
+optional names?: readonly keyof V & string[];
+```
+
+Render only these fields, in this order, without section headings.
+
+##### disabled?
+
+```ts
+optional disabled?: boolean;
+```
+
+Disable every field, such as while an uncertain request is retried.
+
+---
+
+### FormFields()
+
+```ts
+function FormFields<V>(__namedParameters): (Element | null)[];
+```
+
+Render a schema form's fields from its schema: every section in order, or only
+`names` (for placing fields in Screen cells or custom layouts).
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+
+#### Parameters
+
+| Parameter           | Type                                         |
+| ------------------- | -------------------------------------------- |
+| `__namedParameters` | [`FormFieldsProps`](#formfieldsprops)\<`V`\> |
+
+#### Returns
+
+(`Element` \| `null`)[]
+
+---
+
+### FieldInput
+
+```ts
+type FieldInput =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | readonly string[]
+  | readonly File[];
+```
+
+The raw input one field holds: text, a number (or empty), a flag, or a set of
+chosen values or files. The schema turns it into the domain value at submit.
+
+---
+
+### FormValues
+
+```ts
+type FormValues = Readonly<Record<string, FieldInput>>;
+```
+
+The raw values a schema form holds: one entry per field name.
+
+---
+
+### FieldKind
+
+```ts
+type FieldKind =
+  | "text"
+  | "email"
+  | "url"
+  | "tel"
+  | "textarea"
+  | "secret"
+  | "money"
+  | "date"
+  | "number"
+  | "select"
+  | "combobox"
+  | "file"
+  | "radio"
+  | "icon-radio"
+  | "checkbox"
+  | "switch"
+  | "checkboxes"
+  | "icon-checkboxes";
+```
+
+Every control a schema field can render as.
+
+---
+
+### OptionAnnotation
+
+```ts
+type OptionAnnotation = object;
+```
+
+One choice's presentation, keyed by its value in `options`.
+
+#### Properties
+
+##### label?
+
+```ts
+readonly optional label?: string;
+```
+
+##### description?
+
+```ts
+readonly optional description?: string;
+```
+
+A sentence under the label; radio options with one render as cards.
+
+##### meta?
+
+```ts
+readonly optional meta?: string;
+```
+
+A short readout on a radio card's trailing edge, such as a price.
+
+##### icon?
+
+```ts
+readonly optional icon?: ReactNode;
+```
+
+A Sigil or App icon: choices with icons render as icon keys.
+
+##### caption?
+
+```ts
+readonly optional caption?: string;
+```
+
+The short legend on an icon key; `label` stays the accessible name.
+
+##### disabled?
+
+```ts
+readonly optional disabled?: boolean;
+```
+
+---
+
+### FieldRenderProps
+
+```ts
+type FieldRenderProps<T> = object;
+```
+
+What a `render` annotation receives: the same wiring every built-in kind gets.
+
+#### Type Parameters
+
+| Type Parameter                            | Default type                |
+| ----------------------------------------- | --------------------------- |
+| `T` _extends_ [`FieldInput`](#fieldinput) | [`FieldInput`](#fieldinput) |
+
+#### Properties
+
+##### name
+
+```ts
+readonly name: string;
+```
+
+##### label
+
+```ts
+readonly label: string;
+```
+
+##### help
+
+```ts
+readonly help: ReactNode;
+```
+
+##### value
+
+```ts
+readonly value: T;
+```
+
+##### onBlur
+
+```ts
+readonly onBlur: () => void;
+```
+
+Mark the field visited, so its error shows.
+
+###### Returns
+
+`void`
+
+##### error
+
+```ts
+readonly error: string | undefined;
+```
+
+The visible error, after the person leaves the field or submits.
+
+##### disabled
+
+```ts
+readonly disabled: boolean;
+```
+
+##### id
+
+```ts
+readonly id: string;
+```
+
+Put these on the control so the Field's label, help and error name it.
+
+##### aria-describedby
+
+```ts
+readonly aria-describedby: string | undefined;
+```
+
+##### aria-invalid
+
+```ts
+readonly aria-invalid: boolean;
+```
+
+#### Methods
+
+##### onChange()
+
+```ts
+onChange(value): void;
+```
+
+Set the field's raw value; validation runs as it would for a built-in kind.
+
+###### Parameters
+
+| Parameter | Type |
+| --------- | ---- |
+| `value`   | `T`  |
+
+###### Returns
+
+`void`
+
+---
+
+### FieldAnnotation
+
+```ts
+type FieldAnnotation<T> = object;
+```
+
+Presentation for one schema field. The schema stays the single source.
+
+#### Type Parameters
+
+| Type Parameter                            | Default type                |
+| ----------------------------------------- | --------------------------- |
+| `T` _extends_ [`FieldInput`](#fieldinput) | [`FieldInput`](#fieldinput) |
+
+#### Properties
+
+##### label?
+
+```ts
+readonly optional label?: string;
+```
+
+The visible label and accessible name; defaults to the humanized key.
+
+##### help?
+
+```ts
+readonly optional help?: string;
+```
+
+##### kind?
+
+```ts
+readonly optional kind?: FieldKind;
+```
+
+Overrides the kind inferred from the schema type.
+
+##### placeholder?
+
+```ts
+readonly optional placeholder?: string;
+```
+
+##### section?
+
+```ts
+readonly optional section?: string;
+```
+
+The `sections` key this field sits in; unsectioned fields come first.
+
+##### order?
+
+```ts
+readonly optional order?: number;
+```
+
+Sort position within its section; fields keep schema order otherwise.
+
+##### layout?
+
+```ts
+readonly optional layout?: "stacked" | "row";
+```
+
+`row` puts the control opposite its label (a settings row).
+
+##### required?
+
+```ts
+readonly optional required?: boolean;
+```
+
+##### optional?
+
+```ts
+readonly optional optional?: boolean;
+```
+
+Marks an optional field in a mostly required form.
+
+##### icon?
+
+```ts
+readonly optional icon?: ReactNode;
+```
+
+A decorative Sigil or App icon before the label.
+
+##### options?
+
+```ts
+readonly optional options?: Readonly<Record<string, string | OptionAnnotation>>;
+```
+
+Labels, help and icons for literal choices, keyed by value.
+
+##### currency?
+
+```ts
+readonly optional currency?: string;
+```
+
+##### unit?
+
+```ts
+readonly optional unit?: string;
+```
+
+##### min?
+
+```ts
+readonly optional min?: number;
+```
+
+##### max?
+
+```ts
+readonly optional max?: number;
+```
+
+##### step?
+
+```ts
+readonly optional step?: number;
+```
+
+##### wrap?
+
+```ts
+readonly optional wrap?: boolean;
+```
+
+##### rows?
+
+```ts
+readonly optional rows?: number;
+```
+
+##### maxLength?
+
+```ts
+readonly optional maxLength?: number;
+```
+
+##### autoComplete?
+
+```ts
+readonly optional autoComplete?: string;
+```
+
+##### accept?
+
+```ts
+readonly optional accept?: string;
+```
+
+Native file-picker filter; the schema owns file-type validation.
+
+##### multiple?
+
+```ts
+readonly optional multiple?: boolean;
+```
+
+##### maxBytes?
+
+```ts
+readonly optional maxBytes?: number;
+```
+
+Per-file byte limit, enforced by the field's schema check.
+
+##### readOnly?
+
+```ts
+readonly optional readOnly?: boolean;
+```
+
+#### Methods
+
+##### when()?
+
+```ts
+optional when(values): boolean;
+```
+
+Show the field only while this holds for the current raw values.
+
+###### Parameters
+
+| Parameter | Type                        |
+| --------- | --------------------------- |
+| `values`  | [`FormValues`](#formvalues) |
+
+###### Returns
+
+`boolean`
+
+##### render()?
+
+```ts
+optional render(field): ReactNode;
+```
+
+The bailout: draw this field's control yourself. Caps still owns the label,
+help, error, layout, validation and save bar.
+
+###### Parameters
+
+| Parameter | Type                                           |
+| --------- | ---------------------------------------------- |
+| `field`   | [`FieldRenderProps`](#fieldrenderprops)\<`T`\> |
+
+###### Returns
+
+`ReactNode`
+
+---
+
+### SectionAnnotation
+
+```ts
+type SectionAnnotation = object;
+```
+
+A titled group of fields, declared on the struct.
+
+#### Properties
+
+##### title
+
+```ts
+readonly title: string;
+```
+
+##### description?
+
+```ts
+readonly optional description?: string;
+```
+
+---
+
+### FieldMeta
+
+Holds a field annotation inside schema annotations (Effect or Zod).
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new FieldMeta(annotation): FieldMeta;
+```
+
+###### Parameters
+
+| Parameter    | Type                                  |
+| ------------ | ------------------------------------- |
+| `annotation` | [`FieldAnnotation`](#fieldannotation) |
+
+###### Returns
+
+[`FieldMeta`](#fieldmeta)
+
+#### Properties
+
+##### annotation
+
+```ts
+readonly annotation: FieldAnnotation;
+```
+
+---
+
+### SectionsMeta
+
+Holds the section list inside a struct's annotations.
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new SectionsMeta(sections): SectionsMeta;
+```
+
+###### Parameters
+
+| Parameter  | Type                                                                          |
+| ---------- | ----------------------------------------------------------------------------- |
+| `sections` | `Readonly`\<`Record`\<`string`, [`SectionAnnotation`](#sectionannotation)\>\> |
+
+###### Returns
+
+[`SectionsMeta`](#sectionsmeta)
+
+#### Properties
+
+##### sections
+
+```ts
+readonly sections: Readonly<Record<string, SectionAnnotation>>;
+```
+
+---
+
+### FieldAnnotations
+
+```ts
+type FieldAnnotations = Record<`caps/form:${number}`, FieldMeta> & object;
+```
+
+Schema annotations for one field: Effect `.annotate()` or Zod `.meta()`.
+
+#### Type Declaration
+
+| Name           | Type     |
+| -------------- | -------- |
+| `title?`       | `string` |
+| `description?` | `string` |
+
+---
+
+### SectionAnnotations
+
+```ts
+type SectionAnnotations = object;
+```
+
+Schema annotations for a struct's sections.
+
+#### Properties
+
+##### caps/form
+
+```ts
+readonly caps/form: SectionsMeta;
+```
+
+---
+
+### field()
+
+```ts
+function field<T>(annotation): FieldAnnotations;
+```
+
+Annotate a schema field for forms. Works with Effect
+(`Schema.String.annotate(field({ … }))`) and Zod
+(`z.string().meta(field({ … }))`). `label` and `help` also become the schema's
+`title` and `description`.
+
+#### Type Parameters
+
+| Type Parameter                            | Default type                |
+| ----------------------------------------- | --------------------------- |
+| `T` _extends_ [`FieldInput`](#fieldinput) | [`FieldInput`](#fieldinput) |
+
+#### Parameters
+
+| Parameter    | Type                                         |
+| ------------ | -------------------------------------------- |
+| `annotation` | [`FieldAnnotation`](#fieldannotation)\<`T`\> |
+
+#### Returns
+
+[`FieldAnnotations`](#fieldannotations)
+
+---
+
+### sections()
+
+```ts
+function sections(list): SectionAnnotations;
+```
+
+Annotate a struct with its sections, in display order.
+
+#### Parameters
+
+| Parameter | Type                                                                          |
+| --------- | ----------------------------------------------------------------------------- |
+| `list`    | `Readonly`\<`Record`\<`string`, [`SectionAnnotation`](#sectionannotation)\>\> |
+
+#### Returns
+
+[`SectionAnnotations`](#sectionannotations)
+
+---
+
+### Secret
+
+```ts
+const Secret: brand<String, "Secret">;
+```
+
+A key or token: masked, never autofilled, with a reveal key.
+
+---
+
+### ResolvedOption
+
+```ts
+type ResolvedOption = object;
+```
+
+One choice, resolved for rendering.
+
+#### Properties
+
+##### value
+
+```ts
+readonly value: string;
+```
+
+##### label
+
+```ts
+readonly label: string;
+```
+
+##### description
+
+```ts
+readonly description: string | undefined;
+```
+
+##### meta
+
+```ts
+readonly meta: string | undefined;
+```
+
+##### icon
+
+```ts
+readonly icon: ReactNode;
+```
+
+##### caption
+
+```ts
+readonly caption: string | undefined;
+```
+
+##### disabled
+
+```ts
+readonly disabled: boolean;
+```
+
+---
+
+### ResolvedField
+
+```ts
+type ResolvedField = Omit<FieldAnnotation, "options" | "kind" | "help"> &
+  object;
+```
+
+One field, resolved from the schema for rendering.
+
+#### Type Declaration
+
+| Name               | Type                                           |
+| ------------------ | ---------------------------------------------- |
+| `help`             | `string` \| `undefined`                        |
+| `name`             | `string`                                       |
+| `label`            | `string`                                       |
+| `kind`             | [`FieldKind`](#fieldkind)                      |
+| `options`          | readonly [`ResolvedOption`](#resolvedoption)[] |
+| `optionalInSchema` | `boolean`                                      |
+| `index`            | `number`                                       |
+
+---
+
+### ResolvedSection
+
+```ts
+type ResolvedSection = object;
+```
+
+A section and its fields, in display order.
+
+#### Properties
+
+##### id
+
+```ts
+readonly id: string | null;
+```
+
+##### title
+
+```ts
+readonly title: string | undefined;
+```
+
+##### description
+
+```ts
+readonly description: string | undefined;
+```
+
+##### fields
+
+```ts
+readonly fields: readonly ResolvedField[];
+```
+
+---
+
+### FormDescription
+
+```ts
+type FormDescription = object;
+```
+
+Everything a form needs from its schema.
+
+#### Properties
+
+##### sections
+
+```ts
+readonly sections: readonly ResolvedSection[];
+```
+
+##### fields
+
+```ts
+readonly fields: readonly ResolvedField[];
+```
+
+##### defaults
+
+```ts
+readonly defaults: FormValues;
+```
+
+---
+
+### describeSchema()
+
+```ts
+function describeSchema(schema): FormDescription;
+```
+
+Read a form's fields, sections and empty defaults from its schema.
+
+#### Parameters
+
+| Parameter | Type                                                                                       |
+| --------- | ------------------------------------------------------------------------------------------ |
+| `schema`  | \| `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> \| `Top` |
+
+#### Returns
+
+[`FormDescription`](#formdescription)
+
+---
+
+### FormSchema
+
+```ts
+type FormSchema<V, Out> = Schema.Codec<Out, V> | z.ZodType<Out, V>;
+```
+
+A form schema: an Effect `Schema.Struct` (the house path) or a Zod object. `V`
+is the raw input the controls hold; `Out` is what the submit receives.
+
+#### Type Parameters
+
+| Type Parameter                            | Default type                |
+| ----------------------------------------- | --------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) | [`FormValues`](#formvalues) |
+| `Out`                                     | `unknown`                   |
+
+---
+
+### standardSchema()
+
+```ts
+function standardSchema<V, Out>(schema): StandardSchemaV1<V, Out>;
+```
+
+The schema as a Standard Schema validator for TanStack Form.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+| `Out`                                                                         |
+
+#### Parameters
+
+| Parameter | Type                                      |
+| --------- | ----------------------------------------- |
+| `schema`  | [`FormSchema`](#formschema)\<`V`, `Out`\> |
+
+#### Returns
+
+`StandardSchemaV1`\<`V`, `Out`\>
+
+---
+
+### FormField()
+
+```ts
+function FormField<
+  TParentData,
+  TName,
+  TData,
+  TOnMount,
+  TOnChange,
+  TOnChangeAsync,
+  TOnBlur,
+  TOnBlurAsync,
+  TOnSubmit,
+  TOnSubmitAsync,
+  TOnDynamic,
+  TOnDynamicAsync,
+  TFormOnMount,
+  TFormOnChange,
+  TFormOnChangeAsync,
+  TFormOnBlur,
+  TFormOnBlurAsync,
+  TFormOnSubmit,
+  TFormOnSubmitAsync,
+  TFormOnDynamic,
+  TFormOnDynamicAsync,
+  TFormOnServer,
+  TSubmitMeta,
+>(__namedParameters): Element;
+```
+
+TanStack field binding with Caps labels, descriptions, errors, and control ARIA.
+
+#### Type Parameters
+
+| Type Parameter                                                                                         |
+| ------------------------------------------------------------------------------------------------------ |
+| `TParentData`                                                                                          |
+| `TName` _extends_ `string`                                                                             |
+| `TData`                                                                                                |
+| `TOnMount` _extends_ `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`             |
+| `TOnChange` _extends_ `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`            |
+| `TOnChangeAsync` _extends_ `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`  |
+| `TOnBlur` _extends_ `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`              |
+| `TOnBlurAsync` _extends_ `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`    |
+| `TOnSubmit` _extends_ `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`            |
+| `TOnSubmitAsync` _extends_ `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`  |
+| `TOnDynamic` _extends_ `FieldValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined`           |
+| `TOnDynamicAsync` _extends_ `FieldAsyncValidateOrFn`\<`TParentData`, `TName`, `TData`\> \| `undefined` |
+| `TFormOnMount` _extends_ `FormValidateOrFn`\<`TParentData`\> \| `undefined`                            |
+| `TFormOnChange` _extends_ `FormValidateOrFn`\<`TParentData`\> \| `undefined`                           |
+| `TFormOnChangeAsync` _extends_ `FormAsyncValidateOrFn`\<`TParentData`\> \| `undefined`                 |
+| `TFormOnBlur` _extends_ `FormValidateOrFn`\<`TParentData`\> \| `undefined`                             |
+| `TFormOnBlurAsync` _extends_ `FormAsyncValidateOrFn`\<`TParentData`\> \| `undefined`                   |
+| `TFormOnSubmit` _extends_ `FormValidateOrFn`\<`TParentData`\> \| `undefined`                           |
+| `TFormOnSubmitAsync` _extends_ `FormAsyncValidateOrFn`\<`TParentData`\> \| `undefined`                 |
+| `TFormOnDynamic` _extends_ `FormValidateOrFn`\<`TParentData`\> \| `undefined`                          |
+| `TFormOnDynamicAsync` _extends_ `FormAsyncValidateOrFn`\<`TParentData`\> \| `undefined`                |
+| `TFormOnServer` _extends_ `FormAsyncValidateOrFn`\<`TParentData`\> \| `undefined`                      |
+| `TSubmitMeta`                                                                                          |
+
+#### Parameters
+
+| Parameter           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `__namedParameters` | `FieldComponentProps`\<`TParentData`, `TName`, `TData`, `TOnMount`, `TOnChange`, `TOnChangeAsync`, `TOnBlur`, `TOnBlurAsync`, `TOnSubmit`, `TOnSubmitAsync`, `TOnDynamic`, `TOnDynamicAsync`, `TFormOnMount`, `TFormOnChange`, `TFormOnChangeAsync`, `TFormOnBlur`, `TFormOnBlurAsync`, `TFormOnSubmit`, `TFormOnSubmitAsync`, `TFormOnDynamic`, `TFormOnDynamicAsync`, `TFormOnServer`, `TSubmitMeta`, \{ \}\> & `Pick`\<[`FieldProps`](components/field.md#fieldprops), \| `"required"` \| `"optional"` \| `"orientation"` \| `"className"` \| `"label"` \| `"description"`\> |
+
+#### Returns
+
+`Element`
+
+---
+
+### SubmissionState
+
+```ts
+type SubmissionState = object;
+```
+
+Values read by the submit action from TanStack’s form store.
+
+#### Properties
+
+##### canSubmit
+
+```ts
+canSubmit: boolean;
+```
+
+##### isSubmitting
+
+```ts
+isSubmitting: boolean;
+```
+
+---
+
+### SubmitFooterProps
+
+```ts
+type SubmitFooterProps = Omit<FormFooterProps, "children"> & object;
+```
+
+Footer presentation plus the submit action; TanStack owns availability and busy
+state.
+
+#### Type Declaration
+
+| Name               | Type                                                                                                                                               | Description                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `form`             | `object`                                                                                                                                           | -                                       |
+| `form.Subscribe()` | (`props`) => `ReactNode`                                                                                                                           | TanStack’s reactive selector component. |
+| `label`            | `ReactNode`                                                                                                                                        | -                                       |
+| `disabled?`        | `boolean`                                                                                                                                          | -                                       |
+| `buttonProps?`     | `Omit`\<[`ButtonProps`](components/button.md#buttonprops), `"type"` \| `"disabled"` \| `"loading"` \| `"children"` \| `"onClick"` \| `"asChild"`\> | -                                       |
+
+---
+
+### SubmitFooter()
+
+```ts
+function SubmitFooter(__namedParameters): Element;
+```
+
+Submit button subscribed to TanStack's canSubmit/isSubmitting store state.
+
+#### Parameters
+
+| Parameter           | Type                                      |
+| ------------------- | ----------------------------------------- |
+| `__namedParameters` | [`SubmitFooterProps`](#submitfooterprops) |
+
+#### Returns
+
+`Element`
+
+---
+
+### SubmitResult
+
+```ts
+type SubmitResult<V> =
+  | {
+      kind: "saved";
+      values?: V;
+      message?: string;
+    }
+  | {
+      kind: "refused";
+      error?: string;
+      fields?: Partial<Readonly<Record<keyof V & string, string>>>;
+    };
+```
+
+What a submit handler reports. Return nothing (or `saved`) when the change
+landed; return `refused` with a form-level `error` and/or per-field `fields`
+messages when the server said no. Field messages clear when that field changes;
+the form message clears on the next change anywhere.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+
+#### Union Members
+
+##### Type Literal
+
+```ts
+{
+  kind: "saved";
+  values?: V;
+  message?: string;
+}
+```
+
+| Name       | Type      | Description                                                             |
+| ---------- | --------- | ----------------------------------------------------------------------- |
+| `kind`     | `"saved"` | -                                                                       |
+| `values?`  | `V`       | The new baseline; defaults to the submitted values. Clear secrets here. |
+| `message?` | `string`  | Replaces the default "Saved" readout.                                   |
+
+---
+
+##### Type Literal
+
+```ts
+{
+  kind: "refused";
+  error?: string;
+  fields?: Partial<Readonly<Record<keyof V & string, string>>>;
+}
+```
+
+---
+
+### SchemaFormOptions
+
+```ts
+type SchemaFormOptions<V, Out> = object;
+```
+
+Options accepted by useSchemaForm and an unbound SchemaForm.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+| `Out`                                     |
+
+#### Properties
+
+##### schema
+
+```ts
+schema: FormSchema<V, Out>;
+```
+
+The single source: an Effect `Schema.Struct` (house path) or a Zod object. It
+validates raw input, parses the submitted value, and its annotations (`field`,
+`sections`) give labels, kinds, help, options, order and grouping.
+
+##### defaultValues
+
+```ts
+defaultValues: V;
+```
+
+The raw values to start from, such as the saved settings.
+
+##### onSubmit
+
+```ts
+onSubmit: (value, raw) =>
+  | Promise<SubmitResult<V> | undefined>
+  | Promise<void>
+  | SubmitResult<V>
+  | undefined;
+```
+
+Receives the parsed value, never the raw input.
+
+###### Parameters
+
+| Parameter | Type  |
+| --------- | ----- |
+| `value`   | `Out` |
+| `raw`     | `V`   |
+
+###### Returns
+
+\| `Promise`\<[`SubmitResult`](#submitresult)\<`V`\> \| `undefined`\> \|
+`Promise`\<`void`\> \| [`SubmitResult`](#submitresult)\<`V`\> \| `undefined`
+
+---
+
+### Validator
+
+```ts
+type Validator<V> = StandardSchemaV1<V, unknown>;
+```
+
+The schema as TanStack validates it: raw values in, any output.
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `V`            |
+
+---
+
+### SchemaFormApi
+
+```ts
+type SchemaFormApi<V> = ReactFormExtendedApi<
+  V,
+  undefined,
+  Validator<V>,
+  undefined,
+  undefined,
+  undefined,
+  Validator<V>,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  unknown
+>;
+```
+
+The TanStack form a schema form owns: typed values, schema validators.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+
+---
+
+### SchemaFormModel
+
+```ts
+type SchemaFormModel<V> = object;
+```
+
+The model returned by useSchemaForm and read by SchemaForm, FormFields and
+SaveBar.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+
+#### Properties
+
+##### description
+
+```ts
+readonly description: FormDescription;
+```
+
+The fields, kinds and sections read from the schema.
+
+##### form
+
+```ts
+readonly form: SchemaFormApi<V>;
+```
+
+TanStack's typed form: read values with `useSelector(model.form.store, …)`.
+
+##### error
+
+```ts
+readonly error: string | null;
+```
+
+The last refused submit's form-level message.
+
+##### saved
+
+```ts
+readonly saved: string | null;
+```
+
+The last landed submit's readout, until the next change.
+
+##### discard
+
+```ts
+readonly discard: () => void;
+```
+
+Restore the baseline values and clear every message.
+
+###### Returns
+
+`void`
+
+##### submit
+
+```ts
+readonly submit: () => Promise<void>;
+```
+
+Submit through the schema; the same path as the native submit event.
+
+###### Returns
+
+`Promise`\<`void`\>
+
+---
+
+### useSchemaForm()
+
+```ts
+function useSchemaForm<V, Out>(options): SchemaFormModel<V>;
+```
+
+One form, declared by its schema. TanStack owns field state and timing; the
+schema owns validation and parses the submitted value; the handler only sees
+parsed data and reports `saved` or `refused`.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+| `Out`                                                                         |
+
+#### Parameters
+
+| Parameter | Type                                                    |
+| --------- | ------------------------------------------------------- |
+| `options` | [`SchemaFormOptions`](#schemaformoptions)\<`V`, `Out`\> |
+
+#### Returns
+
+[`SchemaFormModel`](#schemaformmodel)\<`V`\>
+
+---
+
+### SchemaFormStatus
+
+```ts
+type SchemaFormStatus = object;
+```
+
+Live status for leave guards and save bars.
+
+#### Properties
+
+##### dirty
+
+```ts
+dirty: boolean;
+```
+
+Values differ from the baseline.
+
+##### submitting
+
+```ts
+submitting: boolean;
+```
+
+##### canSubmit
+
+```ts
+canSubmit: boolean;
+```
+
+Validation allows a submit right now.
+
+---
+
+### useSchemaFormStatus()
+
+```ts
+function useSchemaFormStatus<V>(model): SchemaFormStatus;
+```
+
+Subscribe to a schema form's dirty and submitting state.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+
+#### Parameters
+
+| Parameter | Type                                         |
+| --------- | -------------------------------------------- |
+| `model`   | [`SchemaFormModel`](#schemaformmodel)\<`V`\> |
+
+#### Returns
+
+[`SchemaFormStatus`](#schemaformstatus)
+
+---
+
+### SchemaFormPresentation
+
+```ts
+type SchemaFormPresentation = object &
+  Omit<FormProps, "busy" | "onSubmit" | "noValidate" | "children">;
+```
+
+How a SchemaForm presents its actions and state.
+
+#### Type Declaration
+
+| Name            | Type        | Description                                                                                                                       |
+| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `submitLabel?`  | `ReactNode` | The primary action's label; defaults to "Save changes".                                                                           |
+| `discardLabel?` | `ReactNode` | Show a Discard action while there are unsaved changes.                                                                            |
+| `allowClean?`   | `boolean`   | Keep the primary action available on a clean form (create forms).                                                                 |
+| `footer?`       | `ReactNode` | Replaces the SaveBar, such as a footer with a retry key; `null` drops it.                                                         |
+| `children?`     | `ReactNode` | Replaces the generated field list, for custom layouts such as Screen cells: place fields with `<FormFields model names={[…]} />`. |
+| `disabled?`     | `boolean`   | Disable every field, such as while an uncertain request is retried.                                                               |
+
+---
+
+### SchemaFormProps
+
+```ts
+type SchemaFormProps<V, Out> = SchemaFormPresentation &
+  | {
+  model: SchemaFormModel<V>;
+}
+| SchemaFormOptions<V, Out>;
+```
+
+Props accepted by SchemaForm: a model from useSchemaForm, or its options.
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+| `Out`                                     |
+
+---
+
+### SchemaForm()
+
+```ts
+function SchemaForm<V, Out>(props): Element;
+```
+
+A whole form from its schema: fields, sections, validation, busy state and the
+SaveBar. Pass `schema`, `defaultValues` and `onSubmit`, or a `model` from
+useSchemaForm when the page needs its status or a custom layout.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+| `Out`                                                                         |
+
+#### Parameters
+
+| Parameter | Type                                                |
+| --------- | --------------------------------------------------- |
+| `props`   | [`SchemaFormProps`](#schemaformprops)\<`V`, `Out`\> |
+
+#### Returns
+
+`Element`
+
+---
+
+### SaveBarProps
+
+```ts
+type SaveBarProps<V> = object &
+  Omit<FormFooterProps, "children" | "error" | "status">;
+```
+
+Props accepted by SaveBar.
+
+#### Type Declaration
+
+| Name            | Type                                                                                                                                               | Description                                                                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`         | [`SchemaFormModel`](#schemaformmodel)\<`V`\>                                                                                                       | -                                                                                                                                             |
+| `label`         | `ReactNode`                                                                                                                                        | The primary action, such as "Save changes" or "Create Team".                                                                                  |
+| `discardLabel?` | `ReactNode`                                                                                                                                        | Show a Discard action while there are unsaved changes.                                                                                        |
+| `allowClean?`   | `boolean`                                                                                                                                          | Keep the primary action available on a clean form (create forms that may submit their defaults). By default a clean form has nothing to save. |
+| `dirtyLabel?`   | `ReactNode`                                                                                                                                        | The quiet readout while there are unsaved changes.                                                                                            |
+| `buttonProps?`  | `Omit`\<[`ButtonProps`](components/button.md#buttonprops), `"type"` \| `"disabled"` \| `"loading"` \| `"children"` \| `"onClick"` \| `"asChild"`\> | -                                                                                                                                             |
+
+#### Type Parameters
+
+| Type Parameter                            |
+| ----------------------------------------- |
+| `V` _extends_ [`FormValues`](#formvalues) |
+
+---
+
+### SaveBar()
+
+```ts
+function SaveBar<V>(__namedParameters): Element;
+```
+
+The form's action row: the refused-submit error, a quiet "Unsaved changes" or
+"Saved" readout, an optional Discard, and the one primary submit.
+
+#### Type Parameters
+
+| Type Parameter                                                                |
+| ----------------------------------------------------------------------------- |
+| `V` _extends_ `Readonly`\<`Record`\<`string`, [`FieldInput`](#fieldinput)\>\> |
+
+#### Parameters
+
+| Parameter           | Type                                   |
+| ------------------- | -------------------------------------- |
+| `__namedParameters` | [`SaveBarProps`](#savebarprops)\<`V`\> |
+
+#### Returns
+
+`Element`