nuxt-ui-tools 0.1.0

package/dist/runtime/form/fields/year/config.d.ts

@@ -0,0 +1,14 @@
+export declare const yearFieldKind: {
+    readonly type: "year";
+    readonly state: "stateful";
+    readonly ui: {
+        readonly label: true;
+        readonly description: true;
+        readonly hint: true;
+    };
+    readonly layout: {
+        readonly item: true;
+    };
+    readonly validation: true;
+    readonly transform: true;
+};

package/dist/runtime/form/fields/year/config.js

@@ -0,0 +1,9 @@
+import { defineFormFieldKind } from "../../utils/field-kind.js";
+export const yearFieldKind = defineFormFieldKind({
+  type: "year",
+  state: "stateful",
+  ui: { label: true, description: true, hint: true },
+  layout: { item: true },
+  validation: true,
+  transform: true
+});

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

@@ -0,0 +1 @@
+export type { FormYearField, YearFieldOutput } from '../date-family/types.js';

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

@@ -0,0 +1,11 @@
+export { defineFormField, defineFormFields, defineFormSchema } from './schema/index.js';
+export { useForm } from './composables/use-form.js';
+export { useFormUi } from './composables/use-form-ui.js';
+export { provideFormApi, useFormApi } from './composables/use-form-api.js';
+export type { FormController, UseFormParams } from './types/index.js';
+export { useFormSubmit } from './composables/use-form-submit.js';
+export { createFormFieldInstance, fieldKindHas, getFormFieldKind, isRegisteredFormFieldType, } from './utils/field-instance.js';
+export type { FormFieldCapability, FormFieldInstance, FormFieldKind, FormFieldState, } from './utils/field-instance.js';
+export { defineFormFieldKind } from './utils/field-kind.js';
+export * from './fields/index.js';
+export type * from './types';

package/dist/runtime/form/index.js

@@ -0,0 +1,13 @@
+export { defineFormField, defineFormFields, defineFormSchema } from "./schema/index.js";
+export { useForm } from "./composables/use-form.js";
+export { useFormUi } from "./composables/use-form-ui.js";
+export { provideFormApi, useFormApi } from "./composables/use-form-api.js";
+export { useFormSubmit } from "./composables/use-form-submit.js";
+export {
+  createFormFieldInstance,
+  fieldKindHas,
+  getFormFieldKind,
+  isRegisteredFormFieldType
+} from "./utils/field-instance.js";
+export { defineFormFieldKind } from "./utils/field-kind.js";
+export * from "./fields/index.js";

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

@@ -0,0 +1,84 @@
+import type { GenericObject } from '../../shared/types/utils.js';
+import type { FormAction, FormApi, FormContextData, FormContextDefinition, FormField, FormLayoutConfig, FormMaybePromise, FormSubmitHandler, FormStep, FormStepLifecycleParams, FormText } from '../types/index.js';
+type FormSchemaSubmit<TContext extends FormContextDefinition | undefined> = (params: {
+    value: unknown;
+    api: FormApi;
+    ctx: FormContextData<TContext>;
+}) => Promise<void> | void;
+interface FormSchemaBase<TContext extends FormContextDefinition | undefined> {
+    formKey?: string;
+    title?: FormText;
+    context: TContext;
+    layout?: FormLayoutConfig;
+    showStepper?: boolean;
+    controls?: import('../types').FormControlsConfig;
+    modal?: import('../types').FormModalConfig;
+    drawer?: import('../types').FormDrawerConfig;
+    fullscreen?: import('../types').FormFullscreenConfig;
+    actions?: readonly FormAction[];
+    onBeforeSubmit?: FormSubmitHandler<unknown, never>;
+    submit?: FormSchemaSubmit<TContext>;
+    onBeforeNext?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<boolean | void>;
+    onBeforePrevious?: (params: FormStepLifecycleParams<unknown>) => FormMaybePromise<void>;
+    skipStep?: (params: FormStepLifecycleParams<unknown>) => boolean;
+    onStepSkipped?: (params: Omit<FormStepLifecycleParams<unknown>, 'stepData'>) => void;
+}
+interface FormSchemaWithContextFields<TContext extends FormContextDefinition, TFields extends readonly FormField<FormContextData<NoInfer<TContext>>>[]> extends FormSchemaBase<TContext> {
+    fields: TFields;
+    steps?: never;
+}
+interface FormSchemaWithContextSteps<TContext extends FormContextDefinition, TSteps extends readonly FormStep<FormContextData<NoInfer<TContext>>>[]> extends FormSchemaBase<TContext> {
+    fields?: never;
+    steps: TSteps;
+}
+interface FormSchemaWithoutContextFields<TFields extends readonly FormField<FormContextData<undefined>>[]> extends Omit<FormSchemaBase<undefined>, 'context'> {
+    context?: undefined;
+    fields: TFields;
+    steps?: never;
+}
+interface FormSchemaWithoutContextSteps<TSteps extends readonly FormStep<FormContextData<undefined>>[]> extends Omit<FormSchemaBase<undefined>, 'context'> {
+    context?: undefined;
+    fields?: never;
+    steps: TSteps;
+}
+/**
+ * Defines a form schema while preserving literal field and context inference.
+ *
+ * @example
+ * ```ts
+ * const schema = defineFormSchema({
+ *   context: {
+ *     items: () => queryOptions({
+ *       queryKey: ['items'],
+ *       queryFn: () => api.items.list(),
+ *     }),
+ *   },
+ *   fields: [
+ *     {
+ *       key: 'item',
+ *       type: 'select',
+ *       label: 'Item',
+ *       options: ({ ctx }) => ctx.items.value ?? [],
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+export declare function defineFormSchema<const TSchema>(schema: TSchema extends {
+    readonly context?: undefined;
+    readonly fields?: never;
+    readonly steps: readonly unknown[];
+} ? TSchema : never): TSchema;
+export declare function defineFormSchema<const TContext extends FormContextDefinition, const TFields extends readonly FormField<FormContextData<NoInfer<TContext>>>[], const TSchema extends GenericObject>(schema: TSchema & FormSchemaWithContextFields<TContext, TFields>): TSchema;
+export declare function defineFormSchema<const TContext extends FormContextDefinition, const TSteps extends readonly FormStep<FormContextData<NoInfer<TContext>>>[], const TSchema extends GenericObject>(schema: TSchema & FormSchemaWithContextSteps<TContext, TSteps>): TSchema & FormSchemaWithContextSteps<TContext, TSteps>;
+export declare function defineFormSchema<const TFields extends readonly FormField<FormContextData<undefined>>[], const TSchema extends GenericObject>(schema: TSchema & FormSchemaWithoutContextFields<TFields>): TSchema;
+export declare function defineFormSchema<const TSteps extends readonly FormStep<FormContextData<undefined>>[], const TSchema extends GenericObject>(schema: TSchema & FormSchemaWithoutContextSteps<TSteps>): TSchema & FormSchemaWithoutContextSteps<TSteps>;
+/**
+ * Defines one field while preserving literal inference.
+ */
+export declare function defineFormField<const TField extends FormField>(field: TField): TField;
+/**
+ * Defines a reusable field group while preserving literal inference.
+ */
+export declare function defineFormFields<const TFields extends readonly FormField[]>(fields: TFields): TFields;
+export {};

package/dist/runtime/form/schema/index.js

@@ -0,0 +1,9 @@
+export function defineFormSchema(schema) {
+  return schema;
+}
+export function defineFormField(field) {
+  return field;
+}
+export function defineFormFields(fields) {
+  return fields;
+}

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

@@ -0,0 +1,70 @@
+import type { FormApi } from './api.js';
+import type { FormText } from './utils.js';
+export type FormActionKey = 'reset' | 'cancel' | 'submit' | 'previous' | 'next';
+export type FormActionSlot = 'left' | 'right' | (string & {});
+export type FormActionWidth = 'fit' | 'fill' | (string & {});
+export type FormActionType = 'primary' | (string & {});
+export type FormActionColor = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral';
+export type FormActionVariant = 'solid' | 'outline' | 'soft' | 'subtle' | 'ghost' | 'link';
+export type FormActionSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Runtime context passed to form action conditions, disabled callbacks, links, and handlers.
+ */
+export interface FormActionContext {
+    /** Current zero-based step index. */
+    currentStep: number;
+    /** Public form API for state, validation, focus, submit, and reset operations. */
+    api: FormApi;
+    /** Current pending action, if a built-in action is running. */
+    actionPending: FormActionKey | null;
+    /** True when the rendered schema has steps. */
+    isMultiStep: boolean;
+    /** True on the first step or on non-stepped forms. */
+    isFirstStep: boolean;
+    /** True on the final step or on non-stepped forms. */
+    isLastStep: boolean;
+}
+/**
+ * Shared Nuxt UI button presentation for built-in and custom form actions.
+ */
+export interface FormActionUi {
+    /** Button label. Defaults are provided for built-in action keys. */
+    label?: FormText;
+    /** Leading icon name. Set to `false` to suppress built-in icons. */
+    icon?: string | false;
+    /** Trailing icon name. */
+    trailingIcon?: string | false;
+    /** Shared-ui action emphasis. `primary` maps to Nuxt UI's primary solid button. */
+    type?: FormActionType;
+    /** Nuxt UI button color. */
+    color?: FormActionColor;
+    /** Nuxt UI button variant. */
+    variant?: FormActionVariant;
+    /** Nuxt UI button size. */
+    size?: FormActionSize;
+    /** Responsive action slot. `left` and `right` map to the two footer groups. */
+    slot?: FormActionSlot;
+    /** Responsive width. `fill` makes the action flex within its slot. */
+    width?: FormActionWidth;
+    /** Additional class forwarded to the button. */
+    class?: string;
+    /** Controls whether the action is rendered. */
+    condition?: (params: FormActionContext) => boolean;
+    /** Controls whether the action is disabled. */
+    disabled?: (params: FormActionContext) => boolean;
+}
+/**
+ * Built-in form action. The runtime owns the behavior for the action key.
+ */
+export interface BaseFormAction extends FormActionUi {
+    key: FormActionKey;
+}
+/**
+ * Custom form action. Use this for side effects, custom navigation, or external links.
+ */
+export interface CustomFormAction extends FormActionUi {
+    key?: string;
+    link?: string | ((params: FormActionContext) => string);
+    action?: (params: FormActionContext) => Promise<void> | void;
+}
+export type FormAction = BaseFormAction | CustomFormAction;

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

@@ -0,0 +1,149 @@
+import type { ComputedRef } from 'vue';
+import type { FormContextData } from './context.js';
+import type { FormMaybePromise, FormObject } from './utils.js';
+import type { FormValidationOptions } from './validation.js';
+export type FormRefreshableContextKey<TContext> = {
+    [TKey in keyof TContext]: Extract<TContext[TKey], {
+        refresh: () => Promise<void>;
+    }> extends never ? never : TKey;
+}[keyof TContext] & string;
+export type FormContextResourceValue<TResource> = TResource extends {
+    value: infer TValue;
+} ? TValue : unknown;
+export type FormPatchableContextKey<TContext> = {
+    [TKey in keyof TContext]: NonNullable<FormContextResourceValue<TContext[TKey]>> extends readonly unknown[] ? never : NonNullable<FormContextResourceValue<TContext[TKey]>> extends object ? TKey : never;
+}[keyof TContext] & string;
+export type FormContextPatchValue<TContext, TKey extends keyof TContext> = Partial<NonNullable<FormContextResourceValue<TContext[TKey]>>>;
+/**
+ * Public value namespace exposed to a mounted field.
+ */
+export interface FormFieldValueApi<TValue = unknown> {
+    /** Reads the current internal field value. */
+    get: () => TValue;
+    /** Updates the current internal field value. */
+    set: (value: TValue) => void;
+    /** Resets the current internal field value to its configured default. */
+    reset: () => void;
+}
+/**
+ * Public option namespace exposed to option-based fields.
+ */
+export interface FormFieldOptionsApi<TOption = unknown> {
+    /** Returns the current resolved options. */
+    get: () => readonly TOption[];
+    /** Adds a local option to the mounted field without calling the async create handler. */
+    add: (option: TOption) => void;
+    /** True while the first option value is loading. */
+    pending: () => boolean;
+    /** True while options are refreshing after usable data already exists. */
+    fetching: () => boolean;
+    /** True when options should render a visible loader. */
+    loading: () => boolean;
+    /** True while an option creation handler is pending. */
+    creating: () => boolean;
+    /** True when the option field configured a refresh affordance. */
+    refreshable: () => boolean;
+    /** Returns the latest option-source error, if any. */
+    error: () => unknown | null;
+    /** Refreshes the option source when it is async or query-backed. */
+    refresh: () => Promise<void>;
+    /** Creates a new option when the field configured an option creation handler. */
+    create: (label: string) => Promise<TOption | null>;
+}
+/**
+ * Public upload namespace exposed to upload fields.
+ */
+export interface FormFieldUploadApi<TValue = unknown> {
+    /** Starts or restarts upload work for the current selected file value. */
+    start: () => Promise<void>;
+    /** Cancels upload work when the current upload source supports cancellation. */
+    cancel: () => Promise<void>;
+    /** Retries the last failed upload. */
+    retry: () => Promise<void>;
+    /** Removes the current uploaded value and runs delete lifecycle hooks when configured. */
+    remove: (value?: TValue) => Promise<void>;
+}
+/**
+ * Public validation namespace exposed to a mounted field.
+ */
+export interface FormFieldValidationApi {
+    /** Runs validation for the current field. */
+    validate: () => Promise<boolean>;
+    /** Sets an external field error. */
+    setError: (message: string) => void;
+    /** Clears external field errors. */
+    clearError: () => void;
+}
+/**
+ * Public context namespace exposed to a mounted field.
+ */
+export interface FormFieldContextApi<TContext = FormContextData> {
+    /** Reads a form-scoped context resource by key. */
+    get: <TKey extends keyof TContext & string>(key: TKey) => TContext[TKey];
+    /** Replaces the current value of a form-scoped context resource. */
+    set: <TKey extends keyof TContext & string>(key: TKey, value: FormContextResourceValue<TContext[TKey]>) => void;
+    /** Updates the current value of a form-scoped context resource from its previous value. */
+    update: <TKey extends keyof TContext & string>(key: TKey, updater: (value: FormContextResourceValue<TContext[TKey]>) => FormContextResourceValue<TContext[TKey]>) => void;
+    /** Shallow-patches object context values. Arrays and primitives should use `set` or `update`. */
+    patch: <TKey extends FormPatchableContextKey<TContext>>(key: TKey, value: FormContextPatchValue<TContext, TKey> | ((value: NonNullable<FormContextResourceValue<TContext[TKey]>>) => FormContextPatchValue<TContext, TKey>)) => void;
+    /** Refreshes an async form-scoped context resource by key. */
+    refresh: <TKey extends FormRefreshableContextKey<TContext>>(key: TKey) => Promise<void>;
+    /** Refreshes every async form-scoped context resource declared by the schema. */
+    refreshAll: () => Promise<void>;
+}
+/**
+ * Public field API available from field callbacks.
+ */
+export interface FormFieldApi<TValue = unknown, TOption = unknown, TContext = FormContextData> {
+    /** Field-local value operations. */
+    value: FormFieldValueApi<TValue>;
+    /** Form-scoped context operations. */
+    context: FormFieldContextApi<TContext>;
+    /** Option operations. Present for all fields at type level only where the field supports options. */
+    options: FormFieldOptionsApi<TOption>;
+    /** Upload operations. Present for upload fields. */
+    upload: FormFieldUploadApi<TValue>;
+    /** Validation operations for the field. */
+    validation: FormFieldValidationApi;
+    /** Focuses the mounted control for this field when it has a focusable input. */
+    focus: () => Promise<boolean>;
+}
+/**
+ * Public form API available from form-level callbacks.
+ */
+export interface FormApi {
+    /** Reads an internal form value by raw path. */
+    get: (path: string) => unknown;
+    /** Writes an internal form value by raw path. */
+    set: (path: string, value: unknown) => void;
+    /** Runs form validation. */
+    validate: (options?: FormValidationOptions) => Promise<boolean>;
+    /** Focuses a mounted field by raw path. */
+    focus: (path: string | readonly string[]) => Promise<boolean>;
+    /** Submits the form through the configured submit lifecycle. */
+    submit: () => Promise<void>;
+    /** Resets the form to configured defaults. */
+    reset: () => void;
+}
+export type FormSubmitAction = 'next' | 'previous' | 'submit';
+export type FormSubmitResult<TSubmitData = unknown> = boolean | void | {
+    success: false;
+} | {
+    success: true;
+    data?: TSubmitData;
+};
+export interface FormSubmitHandlerParams<TOutput = FormObject> {
+    /** Submitted output value after output transforms and omitted fields are applied. */
+    formData: TOutput;
+    /** Namespaced form API for state, validation, submit, and reset operations. */
+    api: FormApi;
+}
+export type FormSubmitHandler<TOutput = FormObject, TSubmitData = unknown> = (params: FormSubmitHandlerParams<TOutput>) => FormMaybePromise<FormSubmitResult<TSubmitData>>;
+export interface FormSubmitHandlerResult<TSubmitData = unknown> {
+    success: boolean;
+    data?: TSubmitData;
+}
+export interface FormSubmitTarget<TOutput = FormObject, TSubmitData = unknown> {
+    actionPending: ComputedRef<FormSubmitAction | null>;
+    submitHandler: (submitHandler?: FormSubmitHandler<TOutput, TSubmitData>) => Promise<FormSubmitHandlerResult<TSubmitData>>;
+}

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

@@ -0,0 +1,16 @@
+import type { FormFieldApi } from './api.js';
+/**
+ * Parameters passed to field-level callbacks.
+ */
+export interface FormFieldCallbackParams<TContext = {}, TDeps = {}, TValue = unknown, TOption = unknown> {
+    /** Fully typed form-scoped context declared on the schema. */
+    ctx: TContext;
+    /** Values read from the field's dependency list. */
+    deps: TDeps;
+    /** Field-level API for values, options, upload work, and validation. */
+    api: FormFieldApi<TValue, TOption, TContext>;
+}
+/**
+ * Function receiving field callback parameters.
+ */
+export type FormFieldCallback<TResult, TContext = {}, TDeps = {}, TValue = unknown, TOption = unknown> = (params: FormFieldCallbackParams<TContext, TDeps, TValue, TOption>) => TResult;

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

@@ -0,0 +1,31 @@
+import type { DataTag, QueryKey } from '@tanstack/vue-query';
+import type { GenericObject } from '../../shared/types/utils.js';
+import type { FormAsyncResource, FormContextResource, FormSyncResource } from './utils.js';
+/**
+ * Query options accepted by form context and option sources.
+ */
+export interface FormQueryOptions<_TValue = unknown> {
+    queryKey: QueryKey;
+}
+/**
+ * A single context source declared on a form schema.
+ *
+ * Sources do not receive other context values. This keeps the context graph easy to infer and
+ * matches the intended form-scoped data model.
+ */
+export type FormContextSource<TValue = unknown> = TValue | Promise<TValue> | FormQueryOptions<TValue> | (() => TValue | Promise<TValue> | FormQueryOptions<TValue>);
+/**
+ * Object of named context sources declared by a form schema.
+ */
+export type FormContextDefinition = GenericObject;
+type ResolveContextSource<TSource> = TSource extends () => infer TResult ? FormContextResource<TResult> : FormContextResource<TSource>;
+/**
+ * Fully typed context object exposed to field callbacks as `ctx`.
+ */
+export type FormContextData<TContext extends FormContextDefinition | undefined = FormContextDefinition> = TContext extends FormContextDefinition ? {
+    [TKey in keyof TContext]: ResolveContextSource<TContext[TKey]>;
+} : {};
+export type FormRuntimeContext = {
+    [key: string]: FormSyncResource<unknown> | FormAsyncResource<unknown>;
+};
+export type { DataTag, QueryKey };

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

@@ -0,0 +1,198 @@
+import type { ComputedRef, MaybeRefOrGetter } from 'vue';
+import type { FormSubmitAction, FormSubmitHandler, FormSubmitHandlerResult, FormSubmitTarget } from './api.js';
+import type { ExtractFormInternalValue, ExtractFormOutput } from './output.js';
+import type { FormRuntime, FormRuntimeStep } from './runtime.js';
+import type { ExtractFormContext } from './schema.js';
+import type { FormObject } from './utils.js';
+import type { FormValidationError, FormValidationMode, FormValidationOptions } from './validation.js';
+/**
+ * Options accepted by `useForm`.
+ *
+ * `useForm` is the preferred high-level action API for rendered forms. It owns the schema,
+ * keeps the rendered `<NutForm>` bound to the same typed controller, and exposes values,
+ * validation, submission, and step navigation without template ref plumbing.
+ *
+ * @example
+ * ```ts
+ * const form = useForm({
+ *   schema: accountForm,
+ *   onSubmit: ({ formData }) => saveAccount(formData),
+ * })
+ * ```
+ */
+export interface UseFormParams<TSchema, TSubmitData = unknown> {
+    /** Schema owned by this form controller and passed to `<NutForm :form="form" />`. */
+    schema: MaybeRefOrGetter<TSchema>;
+    /** Optional initial internal state. Dotted field keys are still normalized by the runtime. */
+    input?: MaybeRefOrGetter<FormObject | undefined>;
+    /** Keeps later input changes synchronized into the mounted runtime. */
+    syncInput?: MaybeRefOrGetter<boolean | readonly string[]>;
+    /** Selects required, custom-rule, all, or no validation. */
+    validate?: MaybeRefOrGetter<FormValidationMode>;
+    /** Optional default submit handler used by `form.submit()` and native form submit. */
+    onSubmit?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>;
+}
+/**
+ * Untyped runtime overload used internally once the authored schema has crossed the
+ * Vue runtime boundary.
+ */
+export interface RuntimeUseFormParams {
+    schema: MaybeRefOrGetter<unknown>;
+    input?: MaybeRefOrGetter<FormObject | undefined>;
+    syncInput?: MaybeRefOrGetter<boolean | readonly string[]>;
+    validate?: MaybeRefOrGetter<FormValidationMode>;
+    onSubmit?: FormSubmitHandler<FormObject, unknown>;
+}
+export interface FormControllerState<TInternal = FormObject, TOutput = FormObject> {
+    /** Current internal form state before output transforms and omitted submit fields. */
+    internal: ComputedRef<TInternal>;
+    /** Current submitted output after transforms, step roots, and omissions. */
+    output: ComputedRef<TOutput>;
+    /** Reads an internal form value by raw path. Dotted paths address nested state. */
+    get: (path: string) => unknown;
+    /** Writes an internal form value by raw path. Dotted paths create nested state. */
+    set: (path: string, value: unknown) => void;
+    /** Resets internal state to schema defaults and configured input. */
+    reset: () => void;
+}
+export interface FormControllerMeta {
+    /** True once a rendered `<NutForm>` is mounted and bound to this controller. */
+    isBound: ComputedRef<boolean>;
+    /** Dirty state derived from the initial state snapshot. */
+    isDirty: ComputedRef<boolean>;
+    /** Dirty internal paths derived from the initial state snapshot. */
+    dirtyPaths: ComputedRef<readonly string[]>;
+}
+export interface FormControllerValidation {
+    /** Current validation errors produced by live, step, or submit validation. */
+    errors: ComputedRef<readonly FormValidationError[]>;
+    /** True when the current validation result contains at least one error. */
+    hasErrors: ComputedRef<boolean>;
+    /** True when the current validation result has no errors. */
+    isValid: ComputedRef<boolean>;
+    /** Runs whole-form validation and marks invalid paths as touched. */
+    validate: (options?: FormValidationOptions) => Promise<boolean>;
+    /** Runs validation for the currently visible step or field collection. */
+    validateCurrentStep: (options?: FormValidationOptions) => Promise<boolean>;
+    /** Focuses the first focusable invalid field from the current error list. */
+    focusFirstInvalid: () => Promise<boolean>;
+    /** Reads the current error message for a raw path. */
+    getError: (path: string) => string | undefined;
+    /** Clears all current validation and external errors. */
+    clear: () => void;
+}
+export interface FormControllerSubmission<TOutput = FormObject, TSubmitData = unknown> {
+    /** Current pending submit/navigation action. */
+    actionPending: ComputedRef<FormSubmitAction | null>;
+    /** True while the form submit lifecycle is pending. */
+    isSubmitting: ComputedRef<boolean>;
+    /** Runs the default or provided submit handler through the form lifecycle. */
+    submit: (submitHandler?: FormSubmitHandler<TOutput, TSubmitData>) => Promise<boolean>;
+    /** Runs the submit lifecycle and returns the normalized submit result. */
+    submitHandler: (submitHandler?: FormSubmitHandler<TOutput, TSubmitData>) => Promise<FormSubmitHandlerResult<TSubmitData>>;
+}
+export interface FormControllerNavigation {
+    /** Current step index. */
+    currentStepIndex: ComputedRef<number>;
+    /** Current step summary, or `null` when the schema is not stepped. */
+    currentStep: ComputedRef<FormRuntimeStep | null>;
+    /** Current step summaries. */
+    steps: ComputedRef<readonly FormRuntimeStep[]>;
+    /** True when the schema has steps. */
+    isStepped: ComputedRef<boolean>;
+    /** True on the first step or on non-stepped forms. */
+    isFirstStep: ComputedRef<boolean>;
+    /** True on the final step or on non-stepped forms. */
+    isLastStep: ComputedRef<boolean>;
+    /** True when moving to a previous step is currently meaningful. */
+    canGoPrevious: ComputedRef<boolean>;
+    /** True when moving to a next step is currently meaningful. */
+    canGoNext: ComputedRef<boolean>;
+    /** Moves to the next step after validating the current step. */
+    next: () => Promise<boolean>;
+    /** Moves to the previous step. */
+    previous: () => Promise<boolean>;
+    /** Moves to a step index. Forward moves validate the current step first. */
+    goTo: (index: number) => Promise<boolean>;
+}
+/**
+ * Minimal controller shape consumed by the rendered form component.
+ *
+ * This keeps `<NutForm :form="form" />` assignable for every schema-specific controller
+ * without forcing the component prop to know the controller's submitted output type.
+ */
+export interface FormRendererController {
+    /** Schema bound to the controller. */
+    schema: ComputedRef<unknown>;
+    /** Initial input state bound to the controller. */
+    input: ComputedRef<FormObject | undefined>;
+    /** External input synchronization policy bound to the controller. */
+    syncInput: ComputedRef<boolean | readonly string[]>;
+    /** Validation mode bound to the controller. */
+    validationMode: ComputedRef<FormValidationMode>;
+    /** Runs the controller's default submit lifecycle. */
+    submit: () => Promise<boolean>;
+    /** Runs the controller's default submit lifecycle and returns the normalized result. */
+    submitHandler: () => Promise<FormSubmitHandlerResult<unknown>>;
+    /** Binds a mounted runtime instance to the controller. */
+    bind: (runtime: FormRuntime) => void;
+    /** Unbinds a mounted runtime instance from the controller. */
+    unbind: (runtime: FormRuntime) => void;
+}
+/**
+ * Typed form controller returned by `useForm`.
+ *
+ * Pass the controller to `<NutForm :form="form" />` and use the namespaces here for
+ * state inspection, autosave flows, custom action bars, wizard navigation, and explicit
+ * submit handling.
+ */
+export interface FormController<TSchema = FormObject, TSubmitData = unknown> extends FormSubmitTarget<ExtractFormOutput<TSchema>, TSubmitData>, FormRendererController {
+    /** Schema bound to this controller. */
+    schema: ComputedRef<TSchema>;
+    /** Initial input state bound to this controller. */
+    input: ComputedRef<FormObject | undefined>;
+    /** Form-scoped context resources declared on the schema. */
+    context: ComputedRef<ExtractFormContext<TSchema>>;
+    /** Value namespace for internal/output state and raw path operations. */
+    state: FormControllerState<ExtractFormInternalValue<TSchema>, ExtractFormOutput<TSchema>>;
+    /** Dirty and binding metadata. */
+    meta: FormControllerMeta;
+    /** Validation namespace. */
+    validation: FormControllerValidation;
+    /** Submission namespace. */
+    submission: FormControllerSubmission<ExtractFormOutput<TSchema>, TSubmitData>;
+    /** Step navigation namespace. */
+    navigation: FormControllerNavigation;
+    /** Ergonomic alias for `form.state.internal`. */
+    internal: ComputedRef<ExtractFormInternalValue<TSchema>>;
+    /** Ergonomic alias for `form.state.output`. */
+    output: ComputedRef<ExtractFormOutput<TSchema>>;
+    /** Ergonomic alias for `form.validation.errors`. */
+    errors: ComputedRef<readonly FormValidationError[]>;
+    /** Ergonomic alias for `form.meta.isDirty`. */
+    isDirty: ComputedRef<boolean>;
+    /** Ergonomic alias for `form.meta.dirtyPaths`. */
+    dirtyPaths: ComputedRef<readonly string[]>;
+    /** Ergonomic alias for `form.submission.isSubmitting`. */
+    isSubmitting: ComputedRef<boolean>;
+    /** Ergonomic alias for `form.submission.actionPending`. */
+    actionPending: ComputedRef<FormSubmitAction | null>;
+    /** Ergonomic alias for `form.validation.validate`. */
+    validate: (options?: FormValidationOptions) => Promise<boolean>;
+    /** Ergonomic alias for focusing a mounted field by raw path. */
+    focus: (path: string | readonly string[]) => Promise<boolean>;
+    /** Ergonomic alias for `form.submission.submit`. */
+    submit: (submitHandler?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>) => Promise<boolean>;
+    /** Ergonomic alias for `form.submission.submitHandler`. */
+    submitHandler: (submitHandler?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>) => Promise<FormSubmitHandlerResult<TSubmitData>>;
+    /** Ergonomic alias for `form.state.reset`. */
+    reset: () => void;
+    /** Ergonomic alias for `form.navigation.next`. */
+    nextStep: () => Promise<boolean>;
+    /** Ergonomic alias for `form.navigation.previous`. */
+    previousStep: () => Promise<boolean>;
+    /** Internal renderer binding used by `<NutForm :form="form" />`. */
+    bind: (runtime: FormRuntime) => void;
+    /** Internal renderer unbinding used when the form component unmounts. */
+    unbind: (runtime: FormRuntime) => void;
+}