nuxt-ui-tools 1.7.0 → 1.8.1

package/dist/runtime/form/types/field.d.ts

@@ -42,6 +42,7 @@ import type { FormTextField } from '../fields/text/types.js';
 import type { FormTextareaField } from '../fields/textarea/types.js';
 import type { FormTimeField } from '../fields/time/types.js';
 import type { FormUploadField } from '../fields/upload/types.js';
+import type { FormDependencyValues } from './callbacks.js';
 export type { FormContainerFieldBase, FormFieldType, FormStatefulFieldBase, FormStatelessFieldBase, } from './field-base.js';
 export type { FormArrayCollapseField } from '../fields/array-collapse/types.js';
 export type { FormArrayListField } from '../fields/array-list/types.js';
@@ -86,11 +87,11 @@ export type { FormTagField } from '../fields/tag/types.js';
 export type { FormTextField } from '../fields/text/types.js';
 export type { FormTextareaField } from '../fields/textarea/types.js';
 export type { FormTimeField } from '../fields/time/types.js';
-export type { FormUploadField } from '../fields/upload/types.js';
+export type { FormUploadCallbackParams, FormUploadDeleteParams, FormUploadField, FormUploadHandler, FormUploadOpenParams, FormUploadResolvedFile, FormUploadValue, FormUploadValueParams, } from '../fields/upload/types.js';
 /**
  * Union of authored form fields.
  *
  * Individual field schema contracts live beside their field implementation in
  * `src/runtime/form/fields/<kind>/types.ts`; this file only assembles the public union.
  */
-export type FormField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = FormTextField<TContext, TDeps> | FormPasswordField<TContext, TDeps> | FormTextareaField<TContext, TDeps> | FormNumberField<TContext, TDeps> | FormAutoCompleteField<TContext, TDeps> | FormCheckboxField<TContext, TDeps> | FormSwitchField<TContext, TDeps> | FormSwitchGroupField<TContext, TDeps> | FormRadioField<TContext, TDeps> | FormRadioCardField<TContext, TDeps> | FormCheckboxGroupField<TContext, TDeps> | FormCheckboxCardField<TContext, TDeps> | FormSelectField<TContext, TDeps> | FormDateField<TContext, TDeps> | FormDateTimeField<TContext, TDeps> | FormDateRangeField<TContext, TDeps> | FormMonthRangeField<TContext, TDeps> | FormDateTimeRangeField<TContext, TDeps> | FormMonthField<TContext, TDeps> | FormYearField<TContext, TDeps> | FormTimeField<TContext, TDeps> | FormTreeSelectField<TContext, TDeps> | FormCascaderField<TContext, TDeps> | FormTreeField<TContext, TDeps> | FormPhoneNumberField<TContext, TDeps> | FormHiddenField<TContext, TDeps> | FormInfoField<TContext, TDeps> | FormDividerField<TContext, TDeps> | FormSectionField<TContext, TDeps> | FormInputGroupField<TContext, TDeps> | FormTabsField<TContext, TDeps> | FormGroupField<TContext, TDeps> | FormObjectField<TContext, TDeps> | FormMatrixField<TContext, TDeps> | FormCustomComponentField<TContext, TDeps> | FormFileField<TContext, TDeps> | FormUploadField<TContext, TDeps> | FormArrayListField<TContext, TDeps> | FormArrayTableField<TContext, TDeps> | FormArrayTabsField<TContext, TDeps> | FormArrayVariantField<TContext, TDeps> | FormArrayCollapseField<TContext, TDeps> | FormArrayPrimitiveField<TContext, TDeps> | FormSliderField<TContext, TDeps> | FormColorPickerField<TContext, TDeps> | FormOneTimeCodeField<TContext, TDeps> | FormRatingField<TContext, TDeps> | FormTagField<TContext, TDeps> | FormButtonField<TContext, TDeps> | FormCardField<TContext, TDeps> | FormColumnField<TContext, TDeps>;
+export type FormField<TContext = NonNullable<unknown>, TDeps = FormDependencyValues> = FormTextField<TContext, TDeps> | FormPasswordField<TContext, TDeps> | FormTextareaField<TContext, TDeps> | FormNumberField<TContext, TDeps> | FormAutoCompleteField<TContext, TDeps> | FormCheckboxField<TContext, TDeps> | FormSwitchField<TContext, TDeps> | FormSwitchGroupField<TContext, TDeps> | FormRadioField<TContext, TDeps> | FormRadioCardField<TContext, TDeps> | FormCheckboxGroupField<TContext, TDeps> | FormCheckboxCardField<TContext, TDeps> | FormSelectField<TContext, TDeps> | FormDateField<TContext, TDeps> | FormDateTimeField<TContext, TDeps> | FormDateRangeField<TContext, TDeps> | FormMonthRangeField<TContext, TDeps> | FormDateTimeRangeField<TContext, TDeps> | FormMonthField<TContext, TDeps> | FormYearField<TContext, TDeps> | FormTimeField<TContext, TDeps> | FormTreeSelectField<TContext, TDeps> | FormCascaderField<TContext, TDeps> | FormTreeField<TContext, TDeps> | FormPhoneNumberField<TContext, TDeps> | FormHiddenField<TContext, TDeps> | FormInfoField<TContext, TDeps> | FormDividerField<TContext, TDeps> | FormSectionField<TContext, TDeps> | FormInputGroupField<TContext, TDeps> | FormTabsField<TContext, TDeps> | FormGroupField<TContext, TDeps> | FormObjectField<TContext, TDeps> | FormMatrixField<TContext, TDeps> | FormCustomComponentField<TContext, TDeps> | FormFileField<TContext, TDeps> | FormUploadField<TContext, TDeps> | FormArrayListField<TContext, TDeps> | FormArrayTableField<TContext, TDeps> | FormArrayTabsField<TContext, TDeps> | FormArrayVariantField<TContext, TDeps> | FormArrayCollapseField<TContext, TDeps> | FormArrayPrimitiveField<TContext, TDeps> | FormSliderField<TContext, TDeps> | FormColorPickerField<TContext, TDeps> | FormOneTimeCodeField<TContext, TDeps> | FormRatingField<TContext, TDeps> | FormTagField<TContext, TDeps> | FormButtonField<TContext, TDeps> | FormCardField<TContext, TDeps> | FormColumnField<TContext, TDeps>;

package/dist/runtime/form/types/form-api.d.ts

@@ -2,7 +2,7 @@ import type { ComputedRef } from 'vue';
 import type { FormValue } from './/index.js';
 import type { FormSubmitHandler } from './api.js';
 import type { FormController } from './controller.js';
-import type { ExtractFormOutput } from './output.js';
+import type { ExtractFormInput, ExtractFormOutput } from './output.js';
 import type { FormObject } from './utils.js';
 export type FormApiDisplayMode = 'modal' | 'drawer' | 'fullscreen';
 export type FormApiDisplayModeInput = FormApiDisplayMode | string | (() => FormApiDisplayModeInput);
@@ -20,7 +20,9 @@ export interface FormResolvedCreateOptions {
     mode: FormApiDisplayModeInput;
     onSubmit?: FormSubmitHandler<FormObject, FormValue>;
 }
-export interface FormApiCreateOptions<TSchema, TSubmitData = FormValue> extends FormApiCreateBaseOptions {
+export interface FormApiCreateOptions<TSchema, TSubmitData = FormValue> extends Omit<FormApiCreateBaseOptions, 'input'> {
+    /** Initial value, typed from the schema as in `useForm`. */
+    input?: ExtractFormInput<TSchema>;
     /** Optional submit handler owned by the form overlay. Keeps submit buttons pending until it settles. */
     onSubmit?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>;
 }

package/dist/runtime/form/types/options-runtime.d.ts

@@ -1,11 +1,15 @@
-import type { QueryKey, UseQueryOptions } from '@tanstack/vue-query';
-import type { ComputedRef, Ref } from 'vue';
+import type { QueryKey, QueryObserverOptions } from '@tanstack/vue-query';
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
 import type { ResolvedFormOption } from '../utils/options.js';
 import type { FormValue } from './/index.js';
 /**
- * Query options accepted by option sources once they cross the runtime boundary.
+ * Query options accepted by option sources once they cross the runtime boundary: a plain options
+ * object whose `queryKey` is an array, which is what the runtime checks before using it. They reach
+ * Vue Query's `useQuery`, which reads `enabled` as a boolean, a ref, or a getter.
  */
-export type FormRuntimeQueryOptions = Exclude<UseQueryOptions<FormValue, Error, FormValue, FormValue, QueryKey>, Ref<FormValue> | ComputedRef<FormValue>>;
+export type FormRuntimeQueryOptions = Omit<QueryObserverOptions<FormValue, Error, FormValue, FormValue, QueryKey>, 'enabled'> & {
+    enabled?: MaybeRefOrGetter<boolean | undefined>;
+};
 /**
  * Option state registered by a mounted option field and read through the field API.
  */

package/dist/runtime/form/types/options.d.ts

@@ -1,7 +1,7 @@
 import type { QueryKey } from '@tanstack/vue-query';
 import type { RemoteOptionsLoader, RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { FormValue } from './/index.js';
-import type { FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
+import type { FormDependencyValues, FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
 import type { FormMaybePromise, FormText } from './utils.js';
 /**
@@ -28,15 +28,15 @@ export type FormOptionItem<TValue extends FormOptionValue = FormOptionValue> = T
 /**
  * A static, sync-derived, promise-backed, or TanStack Query-backed option source.
  */
-export type FormOptionsSource<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> = readonly TOption[] | FormQueryOptions<readonly TOption[]> | FormFieldCallback<readonly TOption[] | Promise<readonly TOption[]> | FormQueryOptions<readonly TOption[]>, TContext, TDeps, TValue, TOption>;
+export type FormOptionsSource<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> = readonly TOption[] | FormQueryOptions<readonly TOption[]> | FormFieldCallback<readonly TOption[] | Promise<readonly TOption[]> | FormQueryOptions<readonly TOption[]>, TContext, TDeps, TValue, TOption>;
 /**
  * Option creation hook for fields that can create a missing option from user input.
  */
-export interface FormCreateOptionParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormCreateOptionParams<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** User-entered label that should be converted into a concrete option. */
     label: string;
 }
-export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> {
+export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
     /** Label shown by the create affordance. */
     label?: FormText;
     /** Selects the newly-created option immediately. Defaults to `true`. */
@@ -46,14 +46,14 @@ export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDep
     /** Creates an option and returns it. Return `null` when creation was cancelled. */
     handler: (params: FormCreateOptionParams<TContext, TDeps, TValue, TOption>) => FormMaybePromise<TOption | null>;
 }
-export interface FormOptionsChangeParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormOptionsChangeParams<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Previously resolved normalized options. */
     previousOptions: readonly TOption[];
 }
 /**
  * Shared option configuration for option-based fields.
  */
-export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> {
+export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
     /** Local option configs never declare a mode; `mode: 'remote'` selects the remote config. */
     mode?: never;
     /** Static, sync-derived, promise-backed, or query-backed options. */
@@ -69,7 +69,7 @@ export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDep
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
-export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Current debounced search term. Empty when the menu lists unfiltered options. */
     search: string;
     /** Requested page. `cursor` is set for cursor pagination and `index` for page pagination. */
@@ -77,7 +77,7 @@ export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps
     /** Parent option whose direct children are requested. Undefined for root pages. */
     parent?: NoInfer<TOption>;
 }
-export interface FormRemoteSelectedRequest<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormRemoteSelectedRequest<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Selected values that are not present in the loaded pages. */
     values: readonly FormOptionValue[];
 }
@@ -85,7 +85,7 @@ export type FormRemoteSource<TResult> = FormQueryOptions<TResult> | Promise<TRes
 /**
  * Remote option configuration: server-side search, pagination, and selected-value hydration.
  */
-export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> {
+export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
     mode: 'remote';
     /** Loads one page of options for the current search, page, and optional parent. */
     source: (request: FormRemoteOptionsRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<RemoteOptionsResult<TOption>>;
@@ -114,7 +114,7 @@ export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>
     disableOnLoading?: boolean;
 }
 /** Reuses one remote loader while keeping field-specific refresh and creation behavior local. */
-export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> extends Omit<FormRemoteOptionConfig<TOption, TContext, TDeps, TValue>, 'source' | 'resolveSelected' | 'pagination' | 'search' | 'queryKeyFor' | 'selectedQueryKeyFor'> {
+export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> extends Omit<FormRemoteOptionConfig<TOption, TContext, TDeps, TValue>, 'source' | 'resolveSelected' | 'pagination' | 'search' | 'queryKeyFor' | 'selectedQueryKeyFor'> {
     loader: RemoteOptionsLoader<TOption>;
     source?: never;
     resolveSelected?: never;
@@ -123,4 +123,4 @@ export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<un
     queryKeyFor?: never;
     selectedQueryKeyFor?: never;
 }
-export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteLoaderOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;
+export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteLoaderOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;

package/dist/runtime/form/types/output.d.ts

@@ -1,7 +1,7 @@
 import type { DeepPrettify, DeepTransformNestedPaths, PathToObject, UnionToIntersection } from '../../shared/types/utils.js';
 import type { FormObject, FormValue } from './/index.js';
 import type { ArrayCollapseFieldOutput, ArrayListFieldOutput, ArrayPrimitiveFieldOutput, ArrayTableFieldOutput, ArrayTabsFieldOutput, ObjectFieldOutput, MatrixFieldOutput, ResolveFormFieldValue } from './field-output.js';
-import type { FormStateMode, TransformOutputValue } from './field-output-utils.js';
+import type { FormStateMode, NullableValue, TransformInputValue, TransformOutputValue } from './field-output-utils.js';
 export type { ExtractFormFieldInternalValue, NullableValue, ResolveFormFieldValue, } from './field-output.js';
 export type { FormStateMode } from './field-output-utils.js';
 export type ExtractFormFieldOutputValue<TField> = TransformOutputValue<TField, ResolveFormFieldValue<TField>>;
@@ -49,7 +49,9 @@ type ArrayFieldValue<TField, TMode extends FormStateMode> = TField extends {
 } ? ArrayVariantValue<TField, TMode> : TField extends {
     type: 'array-collapse';
 } ? ArrayCollapseFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : never;
-type ApplyOutputMode<TField, TMode extends FormStateMode, TValue> = TMode extends 'output' ? TransformOutputValue<TField, TValue> : TValue;
+type ApplyOutputMode<TField, TMode extends FormStateMode, TValue> = TMode extends 'output' ? TransformOutputValue<TField, TValue> : TMode extends 'input' ? TransformInputValue<TField, TValue | NullableValue> : TValue;
+/** Input leaves every key out and accepts `null`, since a form fills in defaults for what is missing. */
+type ModeFieldValueObject<TField, TMode extends FormStateMode, TValue> = TMode extends 'input' ? OptionalFieldValueObject<TField, TValue> : FieldValueObject<TField, TValue>;
 type ObjectFieldValue<TField, TMode extends FormStateMode> = ApplyOutputMode<TField, TMode, ObjectFieldOutput<FieldsValue<ChildFields<TField>, TMode>>>;
 type MatrixRows<TField> = TField extends {
     readonly rows: infer TRows;
@@ -57,7 +59,7 @@ type MatrixRows<TField> = TField extends {
     key: string;
 }[] ? TRows : readonly [] : readonly [];
 type MatrixFieldValue<TField, TMode extends FormStateMode> = ApplyOutputMode<TField, TMode, MatrixFieldOutput<MatrixRows<TField>, FieldsValue<ChildFields<TField>, TMode>>>;
-type StatefulFieldObject<TField, TMode extends FormStateMode> = TMode extends 'output' ? TField extends {
+type StatefulFieldObject<TField, TMode extends FormStateMode> = TMode extends 'input' ? OptionalFieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>> : TMode extends 'output' ? TField extends {
     submit: {
         omit: true;
     };
@@ -72,13 +74,13 @@ type FieldObject<TField, TMode extends FormStateMode> = TField extends {
     type: 'input-group' | 'card' | 'column';
 } ? FieldsValue<ChildFields<TField>, TMode> : TField extends {
     type: 'object' | 'group';
-} ? FieldValueObject<TField, ObjectFieldValue<TField, TMode>> : TField extends {
+} ? ModeFieldValueObject<TField, TMode, ObjectFieldValue<TField, TMode>> : TField extends {
     type: 'matrix';
-} ? FieldValueObject<TField, MatrixFieldValue<TField, TMode>> : TField extends {
+} ? ModeFieldValueObject<TField, TMode, MatrixFieldValue<TField, TMode>> : TField extends {
     type: 'array-list' | 'array-table' | 'array-tabs' | 'array-variant' | 'array-collapse';
-} ? FieldValueObject<TField, ArrayFieldValue<TField, TMode>> : TField extends {
+} ? ModeFieldValueObject<TField, TMode, ArrayFieldValue<TField, TMode>> : TField extends {
     type: 'array-primitive';
-} ? FieldValueObject<TField, ApplyOutputMode<TField, TMode, ArrayPrimitiveFieldOutput<TField>>> : StatefulFieldObject<TField, TMode>;
+} ? ModeFieldValueObject<TField, TMode, ApplyOutputMode<TField, TMode, ArrayPrimitiveFieldOutput<TField>>> : StatefulFieldObject<TField, TMode>;
 type StepFields<TStep> = TStep extends {
     readonly fields: infer TFields;
 } ? TFields : never;
@@ -95,10 +97,31 @@ export type ExtractFormInternalValue<TSchema> = TSchema extends {
     readonly steps: infer TSteps;
 } ? DeepPrettify<StepsValue<TSteps, 'internal'>> : NonNullable<unknown>;
 /**
- * Extracts the complete submitted output value from a raw authored schema.
+ * Extracts the value a form accepts as `input` from a raw authored schema: every key optional,
+ * `null` accepted, and a field with `transform.input` typed by the value that hook takes.
+ */
+export type ExtractFormInput<TSchema> = TSchema extends {
+    readonly fields: infer TFields;
+} ? FormInputValue<DeepPrettify<FieldsValue<TFields, 'input'>>> : TSchema extends {
+    readonly steps: infer TSteps;
+} ? FormInputValue<DeepPrettify<StepsValue<TSteps, 'input'>>> : FormObject;
+/** Makes every key of plain records optional, through arrays, leaving files and dates whole. */
+type FormInputValue<TValue> = TValue extends Date | Blob ? TValue : TValue extends readonly (infer TItem)[] ? readonly FormInputValue<TItem>[] : TValue extends FormObject ? {
+    [TKey in keyof TValue]?: FormInputValue<TValue[TKey]>;
+} : TValue;
+/**
+ * Extracts the complete submitted output value from a raw authored schema. Its arrays are mutable:
+ * the submitted value is a fresh object, and request bodies inferred from validators take mutable
+ * arrays, so `formData` passes to them as it is.
  */
 export type ExtractFormOutput<TSchema> = TSchema extends {
     readonly fields: infer TFields;
-} ? DeepPrettify<FieldsValue<TFields, 'output'>> : TSchema extends {
+} ? FormOutputValue<DeepPrettify<FieldsValue<TFields, 'output'>>> : TSchema extends {
     readonly steps: infer TSteps;
-} ? DeepPrettify<StepsValue<TSteps, 'output'>> : NonNullable<unknown>;
+} ? FormOutputValue<DeepPrettify<StepsValue<TSteps, 'output'>>> : NonNullable<unknown>;
+/** Drops `readonly` from arrays and tuples through plain records, leaving files and dates whole. */
+type FormOutputValue<TValue> = TValue extends Date | Blob ? TValue : TValue extends readonly unknown[] ? {
+    -readonly [TIndex in keyof TValue]: FormOutputValue<TValue[TIndex]>;
+} : TValue extends FormObject ? {
+    [TKey in keyof TValue]: FormOutputValue<TValue[TKey]>;
+} : TValue;

package/dist/runtime/form/types/page.d.ts

@@ -43,7 +43,8 @@ export interface FormPageSection<TContext = NonNullable<unknown>, TFields extend
     /**
      * Shows the section as optional and leaves it out of the sections left to complete. A section
      * without a required field is optional already; set this when its required fields are filled
-     * by their defaults and the user has nothing to do there.
+     * by their defaults and the user has nothing to do there. Set `false` to keep a section
+     * required when its only required fields are the cells of array rows.
      */
     optional?: boolean;
     /** Grid of the section's fields, merged over the schema `layout`. */
@@ -159,9 +160,12 @@ export interface FormPageSectionState {
     label: string;
     /** Resolved supporting copy. */
     description?: string;
-    /** True when the section is declared optional or has no required field. */
+    /**
+     * True when the section is declared optional, or declares nothing and has no required field
+     * outside array items.
+     */
     optional: boolean;
-    /** Number of required fields without a value. */
+    /** Number of required fields without a value, the fields of array items included. */
     missing: number;
     /** Summary of the section's requirements, see `FormPageSectionStatus`. */
     status: FormPageSectionStatus;

package/dist/runtime/form/types/transform.d.ts

@@ -2,10 +2,13 @@ import type { FormValue } from './/index.js';
 import type { FormFieldCallbackParams } from './callbacks.js';
 /**
  * Input/output transform hooks for a stateful field.
+ *
+ * The hooks are methods so a field can declare the value it accepts: `input(value: string)`
+ * types the field in `ExtractFormInput`, and `output` types it in `ExtractFormOutput`.
  */
 export interface FormTransformConfig<TInternal = FormValue, TExternal = TInternal, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> {
     /** Converts an incoming raw value into the internal form value. Replaces legacy `preformat`. */
-    input?: (value: TExternal, params: FormFieldCallbackParams<TContext, TDeps, TInternal>) => TInternal;
+    input?(value: TExternal, params: FormFieldCallbackParams<TContext, TDeps, TInternal>): TInternal;
     /** Converts the internal form value into the submitted output value. Replaces legacy `transform`. */
-    output?: (value: TInternal, params: FormFieldCallbackParams<TContext, TDeps, TInternal>) => TExternal;
+    output?(value: TInternal, params: FormFieldCallbackParams<TContext, TDeps, TInternal>): TExternal;
 }

package/dist/runtime/form/types/ui.d.ts

@@ -173,7 +173,9 @@ export interface FormArrayTableUi {
     cell?: FormUiClass;
     control?: FormUiClass;
     actionsCell?: FormUiClass;
+    /** Tooltip that shows the message of an invalid cell on hover and focus. */
     error?: FormUiClass;
+    /** Empty state, kept in view when the table scrolls sideways. */
     empty?: FormUiClass;
     addCell?: FormUiClass;
     add?: FormUiClass;
@@ -189,9 +191,11 @@ export interface FormOverlayUi {
  * (`complete`, `invalid`, `pending`) on entries and indicators, `data-dirty` on modified
  * sections and entries.
  *
- * Two CSS variables place sections under the pinned header: `--nut-form-page-header` (its
- * measured height, set by the page) and `--nut-form-page-gap` (the room below it, `24px` by
- * default). Set them on an element around the navigation and sections, such as the root.
+ * Sections and the navigation stay below the pinned header: the page gives each section its
+ * `scroll-margin-top` and the navigation the `--nut-form-page-header` variable (the header's
+ * measured height), rather than setting a variable every field inherits, so a header that
+ * resizes restyles only them. `--nut-form-page-gap` is the room below the header (`24px` by
+ * default); set it on an element around the navigation and sections, such as the root.
  */
 export interface FormPageUi {
     /** The `<form>` element, which scrolls on its own and is the container of the page queries. */

package/dist/runtime/form/types/upload-runtime.d.ts

@@ -4,4 +4,8 @@ export interface FormUploadRuntimeState {
     cancel: () => Promise<void>;
     retry: () => Promise<void>;
     remove: (value?: FormValue) => Promise<void>;
+    /** Resolves once every upload running for the field has finished or failed. */
+    settle: () => Promise<void>;
+    /** True while the field holds selected files that are not stored yet. */
+    pending: () => boolean;
 }

package/dist/runtime/form/utils/page.js

@@ -3,8 +3,10 @@ import { getPathValue, isRecord } from "./path.js";
 import { isBoolean, isFunction, isNumber, isString } from "./predicate.js";
 import {
   fieldPath,
+  getArrayItemFields,
   getChildFields,
   getSchemaFields,
+  isArrayField,
   isEmptyValue,
   isFlatPassthroughField,
   isObjectContainerField,
@@ -40,7 +42,7 @@ export function resolveFormPageSectionState(params) {
   const invalid = runtime.errors.value.some((error) => contains(error.path));
   const required = params.requiredEnforced ? leaves.filter((leaf) => isRequiredLeaf(leaf, runtime)) : [];
   const missing = required.filter((leaf) => isEmptyValue(runtime.getValue(leaf.path))).length;
-  const optional = entry.section.optional === true || required.length === 0;
+  const optional = entry.section.optional ?? required.every((leaf) => leaf.item);
   const filled = !optional || leaves.some((leaf) => isProvided(leaf, runtime, dirtyPaths, params.input));
   return {
     description: resolveFormText(entry.section.description),
@@ -54,7 +56,7 @@ export function resolveFormPageSectionState(params) {
     status: invalid ? "invalid" : missing === 0 && filled ? "complete" : "pending"
   };
 }
-function collectVisibleLeaves(fields, parentPath, runtime) {
+function collectVisibleLeaves(fields, parentPath, runtime, item = false) {
   return fields.flatMap((field) => {
     if (field.ignore === true) {
       return [];
@@ -67,14 +69,31 @@ function collectVisibleLeaves(fields, parentPath, runtime) {
       return [];
     }
     if (isFlatPassthroughField(field)) {
-      return collectVisibleLeaves(getChildFields(field), parentPath, runtime);
+      return collectVisibleLeaves(getChildFields(field), parentPath, runtime, item);
     }
     if (isObjectContainerField(field)) {
-      return collectVisibleLeaves(getChildFields(field), path, runtime);
+      return collectVisibleLeaves(getChildFields(field), path, runtime, item);
     }
-    return [{ field, path }];
+    if (isArrayField(field)) {
+      return [{ field, item, path }, ...collectArrayItemLeaves(field, path, runtime)];
+    }
+    return [{ field, item, path }];
   });
 }
+function collectArrayItemLeaves(field, path, runtime) {
+  const items = runtime.getValue(path);
+  if (!Array.isArray(items)) {
+    return [];
+  }
+  return items.flatMap(
+    (value, index) => isRecord(value) ? collectVisibleLeaves(
+      getArrayItemFields(field, value),
+      [...path, String(index)],
+      runtime,
+      true
+    ) : []
+  );
+}
 function isRequiredLeaf(leaf, runtime) {
   const required = Object.getOwnPropertyDescriptor(leaf.field, "required")?.value;
   if (isBoolean(required)) {

package/dist/runtime/form/utils/state.js

@@ -73,7 +73,7 @@ function applyInputTransforms(target, fields, ctx, parentPath, apiFactory) {
       continue;
     }
     const path = fieldPath(parentPath, field);
-    const value = getPathValue(target, path);
+    const value = transformFieldInput({ apiFactory, ctx, field, parentPath, path, target });
     if (isObjectContainerField(field)) {
       if (isRecord(value)) {
         applyInputTransforms(target, getChildFields(field), ctx, path, apiFactory);
@@ -109,18 +109,21 @@ function applyInputTransforms(target, fields, ctx, parentPath, apiFactory) {
       }
       continue;
     }
-    if (isUndefined(value)) {
-      continue;
-    }
-    const transform = Object.getOwnPropertyDescriptor(field, "transform")?.value;
-    if (!isRecord(transform) || !isFunction(transform.input)) {
-      continue;
-    }
-    const api = apiFactory?.(path, field);
-    const params = api ? callbackParams({ api, ctx, field, parentPath, state: target }) : void 0;
-    setPathValue(target, path, transform.input(value, params));
   }
 }
+function transformFieldInput(params) {
+  const { target, field, path } = params;
+  const value = getPathValue(target, path);
+  const transform = Object.getOwnPropertyDescriptor(field, "transform")?.value;
+  if (isUndefined(value) || !isRecord(transform) || !isFunction(transform.input)) {
+    return value;
+  }
+  const api = params.apiFactory?.(path, field);
+  const callback = api ? callbackParams({ api, ctx: params.ctx, field, parentPath: params.parentPath, state: target }) : void 0;
+  const transformed = transform.input(value, callback);
+  setPathValue(target, path, transformed);
+  return transformed;
+}
 export function buildInitialFormFieldsState(fields, ctx) {
   const state = {};
   mergeMissingFieldDefaults(state, fields, ctx, []);

package/dist/runtime/i18n/locales/en.js

@@ -97,6 +97,101 @@ export default defineUiToolsLocale({
         retry: "Retry"
       }
     },
+    filePreview: {
+      close: "Close",
+      converted: {
+        description: "The original is a {kind} file.",
+        download: "Download original",
+        title: "Converted preview"
+      },
+      counter: "{current} / {total}",
+      csv: {
+        bom: "UTF-8 with BOM",
+        columns: "{count} columns",
+        delimiter: "Delimiter \u201C{value}\u201D",
+        rows: "{count} rows",
+        tab: "tab"
+      },
+      details: "Details",
+      download: "Download",
+      errors: {
+        decodeDescription: "Download it to open it in another app.",
+        decodeTitle: "This browser can\u2019t display {extension} files",
+        open: "Open",
+        pdfDescription: "Open it in the system viewer or download it.",
+        pdfTitle: "This device can\u2019t show PDFs here",
+        sourceDescription: "The link may have expired. Retry asks for it again.",
+        sourceTitle: "Couldn\u2019t load this file"
+      },
+      expand: "Expand",
+      fallback: {
+        description: "{extension} files can\u2019t be shown here. Download it to open it in another app.",
+        descriptionUnnamed: "This file can\u2019t be shown here. Download it to open it in another app.",
+        title: "No preview available"
+      },
+      fields: {
+        columns: "Columns",
+        dimensions: "Dimensions",
+        duration: "Duration",
+        lines: "Lines",
+        modified: "Modified",
+        name: "Name",
+        rows: "Rows",
+        size: "Size",
+        type: "Type"
+      },
+      image: {
+        fit: "Fit to screen",
+        rotate: "Rotate",
+        zoomIn: "Zoom in",
+        zoomOut: "Zoom out"
+      },
+      kinds: {
+        archive: "Archive",
+        audio: "Audio",
+        csv: "CSV",
+        image: "Image",
+        markdown: "Markdown",
+        office: "Office document",
+        other: "File",
+        pdf: "PDF",
+        text: "Text",
+        video: "Video"
+      },
+      markdown: {
+        preview: "Preview",
+        source: "Source"
+      },
+      media: {
+        captions: "Captions",
+        exitFullscreen: "Exit full screen",
+        fullscreen: "Full screen",
+        mute: "Mute",
+        pause: "Pause",
+        pictureInPicture: "Picture in picture",
+        play: "Play",
+        seek: "Seek",
+        speed: "Playback speed",
+        unmute: "Unmute",
+        volume: "Volume"
+      },
+      moreActions: "More actions",
+      next: "Next",
+      openInNewTab: "Open in new tab",
+      position: "{current} of {total}: {name}",
+      previous: "Previous",
+      restore: "Restore",
+      retry: "Retry",
+      text: {
+        copied: "Copied",
+        copy: "Copy contents",
+        formatted: "Formatted JSON",
+        lines: "{count} lines",
+        wrap: "Wrap lines"
+      },
+      truncated: "Showing the first {size} of {total}.",
+      untitled: "Untitled file"
+    },
     form: {
       actions: {
         cancelButton: "Cancel",
@@ -144,7 +239,8 @@ export default defineUiToolsLocale({
           clear: "Clear value",
           confirm: "Confirm",
           end: "End",
-          start: "Start"
+          start: "Start",
+          tokens: { day: "dd", hour: "hh", minute: "mm", month: "mm", year: "yyyy" }
         },
         description: {
           close: "Close",
@@ -195,7 +291,14 @@ export default defineUiToolsLocale({
           minute: "Minute"
         },
         upload: {
+          cancel: "Cancel upload",
           failed: "Upload failed.",
+          open: "Open file",
+          pending: "Upload or remove the selected files before saving.",
+          queued: "Ready to upload",
+          replace: "Replace file",
+          retry: "Retry upload",
+          uploading: "Uploading\u2026",
           remove: "Remove",
           upload: "Upload"
         }