nuxt-ui-tools 0.1.0

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

@@ -0,0 +1,42 @@
+import type { QueryKey, UseQueryOptions } from '@tanstack/vue-query';
+import type { ComputedRef, Ref } from 'vue';
+import type { ResolvedFormOption } from '../utils/options.js';
+/** Complete TanStack Query options retained by form-owned observers. */
+export type FormRuntimeQueryOptions = Exclude<UseQueryOptions<unknown, Error, unknown, unknown, QueryKey>, Ref<unknown> | ComputedRef<unknown>>;
+/**
+ * Runtime state registered by option-capable fields.
+ *
+ * The form runtime keeps this state field-local and lazy: an option source only exists once
+ * the field is mounted, which lets query-backed fields depend on mounted field context while
+ * still exposing loader state through field APIs.
+ */
+export interface FormOptionRuntimeState {
+    /** Current normalized options, including locally-created options. */
+    items: ComputedRef<readonly ResolvedFormOption[]>;
+    /** True while the first usable option payload is loading. */
+    pending: ComputedRef<boolean>;
+    /** True while options are refreshing after a usable payload already exists. */
+    fetching: ComputedRef<boolean>;
+    /** True when controls should show a blocking loader. */
+    loading: ComputedRef<boolean>;
+    /** True while an option creation handler is pending. */
+    creating: ComputedRef<boolean>;
+    /** True when the field has an option creation handler. */
+    creatable: ComputedRef<boolean>;
+    /** Optional label for the explicit create affordance. */
+    createLabel: ComputedRef<string | undefined>;
+    /** Last option-source error, if any. */
+    error: ComputedRef<unknown | null>;
+    /** True when the field should disable interactions while `loading` is true. */
+    disableOnLoading: ComputedRef<boolean>;
+    /** True when the field should render a refresh affordance. */
+    refreshable: ComputedRef<boolean>;
+    /** True when created options should be selected immediately. */
+    selectCreatedOption: ComputedRef<boolean>;
+    /** Re-runs the field option source. */
+    refresh: () => Promise<void>;
+    /** Appends a local option to the field option list without calling the async create handler. */
+    add: (option: unknown) => void;
+    /** Creates and appends a local option when configured by the field. */
+    create: (label: string) => Promise<ResolvedFormOption | null>;
+}

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

@@ -0,0 +1,66 @@
+import type { FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
+import type { FormQueryOptions } from './context.js';
+import type { FormMaybePromise, FormText } from './utils.js';
+/**
+ * Primitive value accepted by option-based fields.
+ */
+export type FormOptionValue = string | number | boolean;
+/**
+ * Standard option shape used by select, radio, checkbox group, and autocomplete fields.
+ */
+export interface FormOption<TValue extends FormOptionValue = FormOptionValue> {
+    /** Value written to the field when this option is selected. */
+    value: TValue;
+    /** User-facing option label. */
+    label?: FormText;
+    /** Optional option description for richer Nuxt UI item renderers. */
+    description?: FormText;
+    /** Disables the option without removing it from the list. */
+    disabled?: boolean;
+}
+/**
+ * Authored option item accepted by option-based fields.
+ */
+export type FormOptionItem<TValue extends FormOptionValue = FormOptionValue> = TValue | FormOption<TValue>;
+/**
+ * A static, sync-derived, promise-backed, or TanStack Query-backed option source.
+ */
+export type FormOptionsSource<TOption, TContext = {}, TDeps = {}, TValue = unknown> = 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 = {}, TDeps = {}, TValue = unknown, TOption = unknown> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+    /** User-entered label that should be converted into a concrete option. */
+    label: string;
+}
+export interface FormCreateOption<TOption, TContext = {}, TDeps = {}, TValue = unknown> {
+    /** Label shown by the create affordance. */
+    label?: FormText;
+    /** Selects the newly-created option immediately. Defaults to `true`. */
+    selectOnCreation?: boolean;
+    /** Option field paths to refresh after creation. Supports `$parent` relative paths. */
+    revalidateFieldOptions?: readonly string[];
+    /** 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 = {}, TDeps = {}, TValue = unknown, TOption = unknown> 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 = {}, TDeps = {}, TValue = unknown> {
+    /** Static, sync-derived, promise-backed, or query-backed options. */
+    source: FormOptionsSource<TOption, TContext, TDeps, TValue>;
+    /** Optional creation behavior for missing options. */
+    create?: FormCreateOption<TOption, TContext, TDeps, TValue>;
+    /** Enables the field-level refresh affordance. Matches shared-ui `allowOptionsRefresh`. */
+    allowOptionsRefresh?: boolean;
+    /** Clears current values that no longer exist in resolved options. Defaults to `true`. */
+    clearOnInvalid?: boolean;
+    /** Runs when resolved source options change, excluding locally-created options. */
+    onOptionsChange?: (options: readonly TOption[], params: FormOptionsChangeParams<TContext, TDeps, TValue, TOption>) => void;
+    /** Disable the field while its option source has no usable data yet. */
+    disableOnLoading?: boolean;
+}

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

@@ -0,0 +1,91 @@
+import type { DeepPrettify, DeepTransformNestedPaths, PathToObject, UnionToIntersection } from '../../shared/types/utils.js';
+import type { ArrayListFieldOutput, ArrayTableFieldOutput, ArrayTabsFieldOutput, ObjectFieldOutput, MatrixFieldOutput, ResolveFormFieldValue } from './field-output.js';
+import type { FormStateMode, 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>>;
+type FieldKey<TField> = TField extends {
+    key: infer TKey;
+} ? TKey extends string ? TKey : never : never;
+type FieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? {} : PathToObject<TKey, TValue> : {} : {};
+type OptionalPathToObject<Path extends string, Output> = Path extends `${infer First}.${infer Rest}` ? {
+    [K in First]: OptionalPathToObject<Rest, Output>;
+} : {
+    [K in Path]?: Output;
+};
+type OptionalFieldValueObject<TField, TValue> = FieldKey<TField> extends infer TKey ? TKey extends string ? string extends TKey ? {} : OptionalPathToObject<TKey, TValue> : {} : {};
+type ChildFields<TField> = TField extends {
+    readonly fields: infer TFields;
+} ? TFields extends readonly unknown[] ? number extends TFields['length'] ? readonly [] : TFields : never : never;
+type FieldsValue<TFields, TMode extends FormStateMode> = TFields extends readonly unknown[] ? DeepTransformNestedPaths<UnionToIntersection<FieldObject<TFields[number], TMode>>> : {};
+type VariantValue<TVariant, TVariantKey extends string, TMode extends FormStateMode> = TVariant extends {
+    readonly key: infer TKey;
+    readonly fields: infer TFields;
+} ? FieldsValue<TFields, TMode> & Record<TVariantKey, TKey> & VirtualFieldsValue<TVariant> : never;
+type VirtualFieldsValue<TField> = TField extends {
+    readonly virtualFields: infer TVirtualFields;
+} ? {
+    [TKey in keyof TVirtualFields]: TVirtualFields[TKey] extends (...args: never[]) => infer TValue ? TValue : never;
+} : {};
+type ArrayVariantValue<TField, TMode extends FormStateMode> = TField extends {
+    readonly variantKey: infer TVariantKey extends string;
+    readonly variants: readonly (infer TVariant)[];
+} ? readonly VariantValue<TVariant, TVariantKey, TMode>[] : readonly unknown[];
+type ArrayFieldValue<TField, TMode extends FormStateMode> = TField extends {
+    type: 'array-list';
+} ? ArrayListFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : TField extends {
+    type: 'array-table';
+} ? ArrayTableFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : TField extends {
+    type: 'array-tabs';
+} ? ArrayTabsFieldOutput<FieldsValue<ChildFields<TField>, TMode> & VirtualFieldsValue<TField>> : TField extends {
+    type: 'array-variant';
+} ? ArrayVariantValue<TField, TMode> : never;
+type ApplyOutputMode<TField, TMode extends FormStateMode, TValue> = TMode extends 'output' ? TransformOutputValue<TField, TValue> : TValue;
+type ObjectFieldValue<TField, TMode extends FormStateMode> = ApplyOutputMode<TField, TMode, ObjectFieldOutput<FieldsValue<ChildFields<TField>, TMode>>>;
+type MatrixRows<TField> = TField extends {
+    readonly rows: infer TRows;
+} ? TRows extends readonly {
+    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 {
+    submit: {
+        omit: true;
+    };
+} ? {} : TField extends {
+    condition: infer _TCondition;
+} ? OptionalFieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>> : FieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>> : FieldValueObject<TField, ApplyOutputMode<TField, TMode, ResolveFormFieldValue<TField>>>;
+type FieldObject<TField, TMode extends FormStateMode> = TField extends {
+    type: 'info' | 'divider' | 'button';
+} ? {} : TField extends {
+    type: 'input-group' | 'card' | 'column';
+} ? FieldsValue<ChildFields<TField>, TMode> : TField extends {
+    type: 'object' | 'group';
+} ? FieldValueObject<TField, ObjectFieldValue<TField, TMode>> : TField extends {
+    type: 'matrix';
+} ? FieldValueObject<TField, MatrixFieldValue<TField, TMode>> : TField extends {
+    type: 'array-list' | 'array-table' | 'array-tabs' | 'array-variant';
+} ? FieldValueObject<TField, ArrayFieldValue<TField, TMode>> : StatefulFieldObject<TField, TMode>;
+type StepFields<TStep> = TStep extends {
+    readonly fields: infer TFields;
+} ? TFields : never;
+type StepObject<TStep, TMode extends FormStateMode> = TStep extends unknown ? TStep extends {
+    readonly root: infer TRoot;
+} ? TRoot extends string ? string extends TRoot ? FieldsValue<StepFields<TStep>, TMode> : PathToObject<TRoot, FieldsValue<StepFields<TStep>, TMode>> : FieldsValue<StepFields<TStep>, TMode> : FieldsValue<StepFields<TStep>, TMode> : never;
+type StepsValue<TSteps, TMode extends FormStateMode> = TSteps extends readonly unknown[] ? DeepTransformNestedPaths<UnionToIntersection<StepObject<TSteps[number], TMode>>> : {};
+/**
+ * Extracts the complete internal form value from a raw authored schema.
+ */
+export type ExtractFormInternalValue<TSchema> = TSchema extends {
+    readonly fields: infer TFields;
+} ? DeepPrettify<FieldsValue<TFields, 'internal'>> : TSchema extends {
+    readonly steps: infer TSteps;
+} ? DeepPrettify<StepsValue<TSteps, 'internal'>> : {};
+/**
+ * Extracts the complete submitted output value from a raw authored schema.
+ */
+export type ExtractFormOutput<TSchema> = TSchema extends {
+    readonly fields: infer TFields;
+} ? DeepPrettify<FieldsValue<TFields, 'output'>> : TSchema extends {
+    readonly steps: infer TSteps;
+} ? DeepPrettify<StepsValue<TSteps, 'output'>> : {};

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

@@ -0,0 +1,44 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { FormSubmitHandlerResult } from './api.js';
+import type { FormRendererController } from './controller.js';
+import type { FormDrawerConfig, FormFullscreenConfig, FormModalConfig } from './schema.js';
+import type { FormOverlayUi } from './ui.js';
+import type { FormObject } from './utils.js';
+export interface FormOverlayLayoutProps {
+    open: boolean;
+    title?: string;
+    description?: string;
+    dismissible: boolean;
+    ui?: FormOverlayUi;
+}
+export interface FormModalLayoutProps extends FormOverlayLayoutProps {
+    config?: FormModalConfig;
+}
+export interface FormDrawerLayoutProps extends FormOverlayLayoutProps {
+    config?: FormDrawerConfig;
+}
+export interface FormFullscreenLayoutProps extends FormOverlayLayoutProps {
+    config?: FormFullscreenConfig;
+}
+export interface FormOverlayLayoutEmits {
+    'update:open': [value: boolean];
+    'after-close': [];
+}
+export type FormOverlayResolution = {
+    type: 'complete';
+    formData: FormObject;
+    submitData?: unknown;
+} | {
+    type: 'cancel';
+    formData: FormObject;
+};
+export interface FormOverlayController {
+    form: FormRendererController;
+    open: Ref<boolean>;
+    title: ComputedRef<string | undefined>;
+    description: ComputedRef<string | undefined>;
+    dismissible: ComputedRef<boolean>;
+    handleOpenUpdate: (value: boolean) => void;
+    handleSubmitted: (formData: FormObject, result: FormSubmitHandlerResult<unknown>) => void;
+    resolveAfterClose: () => void;
+}

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

@@ -0,0 +1,90 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { FormFieldApi } from './api.js';
+import type { FormSubmitAction, FormSubmitHandler, FormSubmitHandlerResult } from './api.js';
+import type { FormFieldCallbackParams } from './callbacks.js';
+import type { FormRuntimeContext } from './context.js';
+import type { FormField } from './field.js';
+import type { FormFocusRequest } from './focus.js';
+import type { FormLayoutConfig } from './layout.js';
+import type { FormOptionRuntimeState } from './options-runtime.js';
+import type { FormUploadRuntimeState } from './upload-runtime.js';
+import type { FormObject } from './utils.js';
+import type { FormValidationError, FormValidationMode, FormValidationOptions } from './validation.js';
+/**
+ * Parameters used to create the internal form runtime consumed by `<NutForm>`.
+ */
+export interface UseFormRuntimeParams {
+    /** Authored schema currently rendered by the form. */
+    schema: ComputedRef<unknown>;
+    /** Optional initial internal state provided by a controller or direct form usage. */
+    input?: ComputedRef<FormObject | undefined>;
+    syncInput?: ComputedRef<boolean | readonly string[]>;
+    validationMode?: ComputedRef<FormValidationMode>;
+}
+/**
+ * Normalized step summary exposed by runtime and controller navigation APIs.
+ */
+export interface FormRuntimeStep {
+    /** Stable step key, falling back to its 1-based index. */
+    key: string;
+    /** Resolved label rendered by step controls. */
+    label: string;
+    /** True when this step is the current rendered step. */
+    active: boolean;
+    /** Zero-based step index. */
+    index: number;
+    /** Optional root path applied to fields inside this step. */
+    root?: string;
+}
+/**
+ * Internal runtime object provided to form renderers and field components.
+ *
+ * This is intentionally broader than the public `useForm` controller: renderers need field
+ * registration, touched-state, option registry, and callback factories that should not be
+ * exposed as top-level consumer API without deliberate design.
+ */
+export interface FormRuntime {
+    schema: ComputedRef<unknown>;
+    state: FormObject;
+    output: ComputedRef<FormObject>;
+    dirtyPaths: ComputedRef<readonly string[]>;
+    isDirty: ComputedRef<boolean>;
+    errors: ComputedRef<readonly FormValidationError[]>;
+    context: FormRuntimeContext;
+    actionPending: ComputedRef<FormSubmitAction | null>;
+    currentStepIndex: Ref<number>;
+    currentFields: ComputedRef<readonly FormField[]>;
+    currentStepRoot: ComputedRef<string | undefined>;
+    currentLayout: ComputedRef<FormLayoutConfig>;
+    currentStep: ComputedRef<FormRuntimeStep | null>;
+    steps: ComputedRef<readonly FormRuntimeStep[]>;
+    isStepped: ComputedRef<boolean>;
+    isFirstStep: ComputedRef<boolean>;
+    isLastStep: ComputedRef<boolean>;
+    canGoPrevious: ComputedRef<boolean>;
+    canGoNext: ComputedRef<boolean>;
+    getValue: (path: string | readonly string[]) => unknown;
+    setValue: (path: string | readonly string[], value: unknown) => void;
+    getFieldApi: (path: readonly string[], field?: FormField) => FormFieldApi;
+    getFieldCallbackParams: (path: readonly string[], field: FormField) => FormFieldCallbackParams;
+    registerFieldOptions: (path: readonly string[], state: FormOptionRuntimeState) => () => void;
+    registerFieldUpload: (path: readonly string[], state: FormUploadRuntimeState) => () => void;
+    refreshFieldOptions: (paths: readonly (string | readonly string[])[]) => Promise<void>;
+    getFieldError: (path: readonly string[]) => string | undefined;
+    markFieldTouched: (path: readonly string[]) => void;
+    isFieldTouched: (path: readonly string[]) => boolean;
+    shouldRender: (field: FormField, path: readonly string[]) => boolean;
+    validate: (options?: FormValidationOptions) => Promise<boolean>;
+    validateCurrentStep: (options?: FormValidationOptions) => Promise<boolean>;
+    focusRequest: Ref<FormFocusRequest | null>;
+    registerFieldElement: (path: string | readonly string[], element: HTMLElement) => () => void;
+    focusField: (path: string | readonly string[]) => Promise<boolean>;
+    focusFirstInvalid: () => Promise<boolean>;
+    clearErrors: () => void;
+    submitHandler: (submitHandler?: FormSubmitHandler<FormObject>) => Promise<FormSubmitHandlerResult>;
+    submit: () => Promise<boolean>;
+    reset: () => void;
+    nextStep: () => Promise<boolean>;
+    previousStep: () => Promise<boolean>;
+    goToStep: (index: number) => Promise<boolean>;
+}

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

@@ -0,0 +1,163 @@
+import type { FormAction } from './actions.js';
+import type { FormApi, FormSubmitHandler } from './api.js';
+import type { FormContextData, FormContextDefinition } from './context.js';
+import type { FormField, FormFieldType } from './field.js';
+import type { FormLayoutConfig } from './layout.js';
+import type { FormUiConfig } from './ui.js';
+import type { FormMaybePromise, FormObject, FormText } from './utils.js';
+import type { FormValidationMode } from './validation.js';
+export interface FormDirtyNavigationConfig {
+    message?: FormText;
+    ignorePaths?: readonly string[];
+}
+export interface FormControlsConfig {
+    /** Enables dirty metadata and field reset affordances. */
+    dirtyCheck?: boolean;
+    /** Focuses the first field after mount, or a specific raw field path. */
+    autoFocus?: boolean | string;
+    /** Warns before an inline dirty form is closed or navigated away from. */
+    confirmNavOnDirty?: boolean | FormDirtyNavigationConfig;
+    /** Keeps external input changes synchronized after the initial mount. */
+    syncInput?: boolean | readonly string[];
+    /** Selects required, custom-rule, all, or no validation. */
+    validate?: FormValidationMode;
+}
+export interface FormModalConfig {
+    maxWidth?: number | string;
+    maxHeight?: number | string;
+    allowOutsideClick?: boolean;
+    showCloseButton?: boolean;
+}
+export interface FormDrawerConfig {
+    placement?: 'left' | 'right' | 'top' | 'bottom';
+    allowOutsideClick?: boolean;
+    showCloseButton?: boolean;
+    resizable?: boolean;
+    width?: number | string;
+    height?: number | string;
+}
+export interface FormFullscreenConfig {
+    allowOutsideClick?: boolean;
+    showCloseButton?: boolean;
+}
+export interface FormStepLifecycleParams<TOutput = FormObject> {
+    /** Step summary targeted by the lifecycle callback. */
+    step: FormStep;
+    /** Zero-based step index targeted by the lifecycle callback. */
+    stepIndex: number;
+    /** Current submitted output. */
+    formData: TOutput;
+    /** Current submitted output, kept for shared-ui parity and future step-scoped narrowing. */
+    stepData: TOutput;
+    /** Public form API for validation, focus, state, submit, and reset. */
+    api: FormApi;
+}
+/**
+ * Step in a multi-step form schema.
+ */
+export interface FormStep<TContext = {}, TFields extends readonly FormField<TContext>[] = readonly FormField<TContext>[]> {
+    /** Stable step key used by navigation state and test selectors. */
+    key?: string;
+    /** Optional title rendered by stepper-aware layouts. */
+    title?: FormText;
+    /** Optional supporting copy rendered by stepper-aware layouts. */
+    description?: FormText;
+    /** Optional icon name rendered by stepper-aware layouts. */
+    icon?: string;
+    /** Optional output root. Fields inside the step are submitted below this path. */
+    root?: string;
+    /** Step-level layout override. */
+    layout?: FormLayoutConfig;
+    /** Step-level action override. Falls back to schema actions, then built-in actions. */
+    actions?: readonly FormAction[];
+    /** Fields rendered for this step. */
+    fields: TFields;
+}
+/**
+ * Schema accepted by `defineFormSchema`.
+ */
+export interface FormSchema<TContext extends FormContextDefinition | undefined = FormContextDefinition | undefined, TFields extends readonly FormField<FormContextData<TContext>>[] = readonly FormField<FormContextData<TContext>>[], TSteps extends readonly FormStep<FormContextData<TContext>>[] = readonly FormStep<FormContextData<TContext>>[]> {
+    /** Stable key used by persistence, diagnostics, and test selectors. */
+    formKey?: string;
+    /** Optional user-facing title for full-form renderers. */
+    title?: FormText;
+    /** Form-scoped data sources exposed to fields as `ctx`. */
+    context?: TContext;
+    /** Form-level field grid layout. */
+    layout?: FormLayoutConfig;
+    /** Form-scoped presentation overrides, merged after app defaults. */
+    ui?: FormUiConfig;
+    /** Fields rendered and managed by the form runtime. */
+    fields?: TFields;
+    /** Steps rendered and managed by stepper-aware form layouts. */
+    steps?: TSteps;
+    /** Controls whether the default stepper chrome is rendered for stepped schemas. */
+    showStepper?: boolean;
+    /** Runtime lifecycle and validation controls. */
+    controls?: FormControlsConfig;
+    /** Modal-shell sizing and dismissal behavior. */
+    modal?: FormModalConfig;
+    /** Drawer-shell placement, sizing, and dismissal behavior. */
+    drawer?: FormDrawerConfig;
+    /** Fullscreen-shell dismissal behavior. */
+    fullscreen?: FormFullscreenConfig;
+    /** Form action configuration. Omit to use built-in reset/submit or previous/next/submit actions. */
+    actions?: readonly FormAction[];
+    /** Runs after validation and before the external submit handler. Return `false` to cancel submit. */
+    onBeforeSubmit?: FormSubmitHandler<unknown, never>;
+    /** Submit lifecycle hook. */
+    submit?: (params: {
+        value: unknown;
+        api: FormApi;
+        ctx: FormContextData<TContext>;
+    }) => Promise<void> | void;
+    /** Runs after current-step validation and before advancing to the next step. Return `false` to stop navigation. */
+    onBeforeNext?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<boolean | void>;
+    /** Runs before moving to the previous step. */
+    onBeforePrevious?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<void>;
+    /** Returns true when a step should be skipped during previous/next navigation. */
+    skipStep?: (params: FormStepLifecycleParams<unknown>) => boolean;
+    /** Runs when `skipStep` skips a step. */
+    onStepSkipped?: (params: Omit<FormStepLifecycleParams<unknown>, 'stepData'>) => void;
+}
+/**
+ * Extracts the typed context object exposed by a form schema.
+ */
+export type ExtractFormContext<TSchema> = TSchema extends {
+    readonly context?: infer TContext extends FormContextDefinition | undefined;
+} ? FormContextData<TContext> : {};
+/**
+ * Extracts the authored fields from a form schema.
+ */
+export type ExtractFormFields<TSchema> = TSchema extends {
+    readonly fields: infer TFields;
+} ? TFields : TSchema extends {
+    readonly steps: infer TSteps;
+} ? TSteps extends readonly {
+    readonly fields: infer TFields;
+}[] ? TFields : readonly FormField[] : readonly FormField[];
+/**
+ * Extracts the authored steps from a form schema.
+ */
+export type ExtractFormSteps<TSchema> = TSchema extends {
+    readonly steps: infer TSteps;
+} ? TSteps : readonly FormStep[];
+type FormFieldByType<TType extends FormFieldType, TContext> = Extract<FormField<TContext>, {
+    type: TType;
+}>;
+type NoExtraFieldProperties<TField, TExpected> = Exclude<keyof TField, keyof TExpected> extends never ? TField : never;
+/**
+ * Strict authored field shape used by schema helpers.
+ */
+export type StrictFormField<TField, TContext = {}> = TField extends {
+    type: infer TType;
+} ? TType extends FormFieldType ? NoExtraFieldProperties<TField, FormFieldByType<TType, TContext>> : never : never;
+/**
+ * Strict authored field collection used by schema helpers.
+ */
+export type StrictFormFields<TFields extends readonly {
+    type: FormFieldType;
+}[], TContext = {}> = {
+    readonly [TKey in keyof TFields]: StrictFormField<TFields[TKey], TContext>;
+};
+export {};

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

@@ -0,0 +1,10 @@
+import type { FormFieldCallbackParams } from './callbacks.js';
+/**
+ * Input/output transform hooks for a stateful field.
+ */
+export interface FormTransformConfig<TInternal = unknown, TExternal = TInternal, TContext = {}, TDeps = {}> {
+    /** Converts an incoming raw value into the internal form value. Replaces legacy `preformat`. */
+    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;
+}