nuxt-ui-tools 0.1.0

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

@@ -0,0 +1,27 @@
+import type { DeepPrettify, PathToObject, UnionToIntersection } from '../../shared/types/utils.js';
+import type { FormObject } from './utils.js';
+type DependencySource<TDependency> = TDependency extends readonly [infer TSource, infer _TTarget] ? TSource extends string ? TSource : never : TDependency extends string ? TDependency : never;
+type DependencyTarget<TDependency> = TDependency extends readonly [infer _TSource, infer TTarget] ? TTarget extends string ? TTarget : never : TDependency extends string ? TDependency : never;
+type PathValue<TSource, TPath extends string> = TPath extends '$root' ? TSource : TPath extends `$parent${string}` ? unknown : TPath extends `${infer THead}.${infer TTail}` ? THead extends keyof TSource ? PathValue<TSource[THead], TTail> : unknown : TPath extends keyof TSource ? TSource[TPath] : unknown;
+type DependencyObject<TDependency, TState> = DependencyTarget<TDependency> extends infer TTarget ? TTarget extends string ? PathToObject<TTarget, PathValue<TState, DependencySource<TDependency>>> : {} : {};
+type DependenciesValue<TDependencies, TState> = TDependencies extends readonly unknown[] ? UnionToIntersection<DependencyObject<TDependencies[number], TState>> : {};
+/**
+ * Extracts the `deps` object made available to callbacks for a single field.
+ *
+ * Pass the form internal state as the second type argument to resolve dependency values from
+ * absolute dotted paths. `$parent` dependencies intentionally resolve to `unknown` at this layer
+ * because their final type depends on where a reusable field is mounted.
+ *
+ * @example
+ * ```ts
+ * type State = { password: string | null, profile: { country: 'FR' | 'BE' | null } }
+ * type Deps = ExtractFormFieldDependencies<{
+ *   dependencies: ['password', ['profile.country', 'country']]
+ * }, State>
+ * // { password: string | null, country: 'FR' | 'BE' | null }
+ * ```
+ */
+export type ExtractFormFieldDependencies<TField, TState = FormObject> = TField extends {
+    readonly dependencies: infer TDependencies;
+} ? DeepPrettify<DependenciesValue<TDependencies, TState>> : {};
+export {};

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

@@ -0,0 +1,126 @@
+import type { FormFieldCallback } from './callbacks.js';
+import type { FormField } from './field.js';
+import type { FormContainerLayout, FormItemLayout } from './layout.js';
+import type { FormTransformConfig } from './transform.js';
+import type { FormDynamic, FormMaybePromise, FormObject, FormText } from './utils.js';
+import type { FormValidationConfig } from './validation.js';
+/**
+ * Field kinds targeted by the current form runtime plan.
+ */
+export type FormFieldType = 'text' | 'password' | 'textarea' | 'number' | 'auto-complete' | 'checkbox' | 'switch' | 'switch-group' | 'radio' | 'radio-card' | 'checkbox-group' | 'checkbox-card' | 'select' | 'date' | 'datetime' | 'daterange' | 'monthrange' | 'datetimerange' | 'month' | 'year' | 'time' | 'phone-number' | 'hidden' | 'info' | 'divider' | 'input-group' | 'object' | 'custom-component' | 'file' | 'upload' | 'array-list' | 'array-table' | 'array-tabs' | 'array-variant' | 'tree-select' | 'cascader' | 'tree' | 'group' | 'matrix' | 'slider' | 'color-picker' | 'one-time-code' | 'tag' | 'rating' | 'button' | 'card' | 'column';
+/**
+ * Common stateful field properties.
+ */
+export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TContext = {}, TDeps = {}> {
+    /** Raw path used to read/write the field value in form state. */
+    key: string;
+    /** Discriminant used by the field registry. */
+    type: TType;
+    /** Initial field value. */
+    default?: FormDynamic<TValue, {
+        ctx: TContext;
+    }>;
+    /** Label rendered by the field wrapper. */
+    label?: FormText;
+    /** Optional supporting copy rendered near the control. */
+    description?: FormText;
+    /** Optional right-side hint rendered by the field wrapper. */
+    hint?: FormText;
+    /** Placeholder forwarded to controls that support placeholders. */
+    placeholder?: FormText;
+    /** Raw dependency paths read before evaluating callbacks. */
+    dependencies?: readonly (string | readonly [string, string])[];
+    /** Item layout options for this field. */
+    layout?: FormItemLayout;
+    /** UI-library-specific props. This intentionally stays open because Nuxt UI props can evolve. */
+    props?: FormDynamic<FormObject, {
+        ctx: TContext;
+        deps: TDeps;
+    }>;
+    /** Disables the field without removing it from form state. */
+    disabled?: FormFieldCallback<boolean, TContext, TDeps, TValue>;
+    /** Controls whether the field is rendered. Hidden fields can still be part of form state. */
+    condition?: FormFieldCallback<boolean, TContext, TDeps, TValue>;
+    /** Validation behavior for this field. */
+    validation?: FormValidationConfig<TValue, TContext, TDeps>;
+    /** Input/output transforms for this field. */
+    transform?: FormTransformConfig<TValue, unknown, TContext, TDeps>;
+    /** Submit/output behavior for this field. */
+    submit?: {
+        /** Excludes the field from submitted output while keeping it in internal form state. */
+        omit?: boolean;
+    };
+    /** Runs after this field value changes. */
+    watch?: (params: {
+        value: TValue;
+        api: import('./api').FormFieldApi<TValue>;
+    }) => void;
+    /** Vue watch options used by the field value effect. */
+    watchOptions?: {
+        deep?: boolean;
+        immediate?: boolean;
+    };
+    /** Runs when the resolved dependency object changes. */
+    onDependencyChange?: FormFieldCallback<FormMaybePromise<void>, TContext, TDeps, TValue>;
+    /** Runs after the field renderer is mounted. */
+    onRendered?: FormFieldCallback<FormMaybePromise<void>, TContext, TDeps, TValue>;
+    /** Keeps the field in internal state while excluding it from rendering and submitted output. */
+    ignore?: boolean;
+    /** Enables a field-level dirty reset affordance. */
+    dirtyCheck?: boolean;
+    /** Wraps the field body in an expandable section. */
+    collapsible?: boolean;
+    /** Initial collapsed state when `collapsible` is enabled. */
+    collapsed?: boolean;
+    /** Debounces or throttles value/dependency effects. */
+    stateEffect?: {
+        type: 'debounce' | 'throttle';
+        duration: number;
+    };
+}
+/**
+ * Base properties for stateless visual fields.
+ */
+export interface FormStatelessFieldBase<TType extends FormFieldType, TContext = {}, TDeps = {}> {
+    /** Stable key for renderer identity. Stateless fields do not write form state. */
+    key: string;
+    /** Discriminant used by the field registry. */
+    type: TType;
+    /** Item layout options for this field. */
+    layout?: FormItemLayout;
+    /** UI-library-specific props. */
+    props?: FormDynamic<FormObject, {
+        ctx: TContext;
+        deps: TDeps;
+    }>;
+    /** Controls whether the field is rendered. */
+    condition?: FormFieldCallback<boolean, TContext, TDeps>;
+    /** Excludes this renderer from the runtime. */
+    ignore?: boolean;
+}
+/**
+ * Base properties for structural fields that render children.
+ */
+export interface FormContainerFieldBase<TType extends FormFieldType, TContext = {}, TDeps = {}> {
+    /** Stable renderer key. */
+    key: string;
+    /** Discriminant used by the field registry. */
+    type: TType;
+    /** Optional title/label for structural renderers that expose one. */
+    label?: FormText;
+    /** Optional supporting copy for structural renderers. */
+    description?: FormText;
+    /** Child fields rendered inside this field. */
+    fields: readonly FormField<TContext, TDeps>[];
+    /** Container layout options. */
+    layout?: FormContainerLayout;
+    /** UI-library-specific props. */
+    props?: FormDynamic<FormObject, {
+        ctx: TContext;
+        deps: TDeps;
+    }>;
+    /** Controls whether the field is rendered. */
+    condition?: FormFieldCallback<boolean, TContext, TDeps>;
+    /** Excludes this container and its children from the runtime. */
+    ignore?: boolean;
+}

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

@@ -0,0 +1,36 @@
+import type { FormFieldType } from './field-base.js';
+/**
+ * Describes how a field kind participates in form state and runtime features.
+ */
+export interface FormFieldKindDefinition<TType extends FormFieldType = FormFieldType> {
+    /** Field type handled by this kind. */
+    type: TType;
+    /** Runtime state model used by this field. */
+    state: 'stateful' | 'stateless' | 'passthrough';
+    /** Whether the field renders label/description/hint chrome. */
+    ui?: {
+        label?: boolean;
+        description?: boolean;
+        hint?: boolean;
+    };
+    /** Whether the field participates in item or container layout. */
+    layout?: {
+        item?: boolean;
+        container?: boolean;
+    };
+    /** Whether the field owns option resolution. */
+    options?: {
+        enabled: boolean;
+    };
+    /** Whether the field owns file upload work. */
+    upload?: {
+        enabled: boolean;
+    };
+    /** Whether the field can validate its value. */
+    validation?: boolean;
+    /** Whether the field supports input/output transforms. */
+    transform?: boolean;
+}
+export type FormFieldKindState = FormFieldKindDefinition['state'];
+export type FormFieldState = FormFieldKindState;
+export type FormFieldCapability = 'value' | 'children' | 'label' | 'description' | 'hint' | 'layout' | 'itemLayout' | 'containerLayout' | 'options' | 'upload' | 'validation' | 'transform' | 'submit';

package/dist/runtime/form/types/field-output-utils.d.ts

@@ -0,0 +1,40 @@
+import type { DataTag, QueryKey } from './context.js';
+import type { FormOptionValue } from './options.js';
+export type FormStateMode = 'internal' | 'output';
+export type NullableValue = null;
+export type AwaitedValue<TValue> = TValue extends Promise<infer TResolved> ? TResolved : TValue;
+export type FallbackNever<TValue, TFallback> = [TValue] extends [never] ? TFallback : TValue;
+export type FunctionReturn<TValue> = TValue extends (...params: infer _TParams) => infer TResult ? TResult : never;
+export type DynamicValue<TValue> = TValue extends (...params: infer _TParams) => infer TResult ? TResult : TValue;
+type QuerySelectedValue<TValue> = TValue extends {
+    select?: infer TSelect;
+} ? FunctionReturn<Exclude<TSelect, undefined>> : never;
+type QueryFunctionValue<TValue> = TValue extends {
+    queryFn?: infer TQueryFn;
+} ? AwaitedValue<FunctionReturn<Exclude<TQueryFn, undefined>>> : never;
+export type QueryOptionsValue<TValue> = [TValue] extends [{
+    queryKey: infer TQueryKey;
+}] ? [QuerySelectedValue<TValue>] extends [never] ? TQueryKey extends DataTag<QueryKey, infer TResult, infer _TError> ? TResult : QueryFunctionValue<TValue> : QuerySelectedValue<TValue> : TValue;
+export type OptionSource<TField> = TField extends {
+    options: infer TOptions;
+} ? TOptions extends {
+    source: infer TSource;
+} ? TSource : TOptions : never;
+export type OptionSourceValue<TSource> = TSource extends (...params: infer _TParams) => infer TResult ? QueryOptionsValue<AwaitedValue<TResult>> : QueryOptionsValue<AwaitedValue<TSource>>;
+export type OptionItemFromValue<TValue> = TValue extends readonly (infer TOption)[] ? TOption : never;
+export type OptionItem<TField> = OptionItemFromValue<OptionSourceValue<OptionSource<TField>>>;
+export type OptionValue<TOption> = TOption extends {
+    value: infer TValue;
+} ? TValue : TOption extends {
+    key: infer TValue;
+} ? TValue : TOption extends FormOptionValue ? TOption : never;
+export type FieldOptionValue<TField> = FallbackNever<OptionValue<OptionItem<TField>>, FormOptionValue>;
+export type FieldDefaultValue<TField> = TField extends {
+    default: infer TDefault;
+} ? DynamicValue<TDefault> : never;
+export type TransformOutputValue<TField, TFallback> = TField extends {
+    transform: {
+        output: infer TOutput;
+    };
+} ? FallbackNever<AwaitedValue<FunctionReturn<TOutput>>, TFallback> : TFallback;
+export {};

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

@@ -0,0 +1,104 @@
+import type { AutoCompleteFieldOutput } from '../fields/auto-complete/types.js';
+import type { CheckboxCardFieldOutput } from '../fields/checkbox-card/types.js';
+import type { CheckboxGroupFieldOutput } from '../fields/checkbox-group/types.js';
+import type { CheckboxFieldOutput } from '../fields/checkbox/types.js';
+import type { ColorPickerFieldOutput } from '../fields/color-picker/types.js';
+import type { CustomComponentFieldOutput } from '../fields/custom-component/types.js';
+import type { DateRangeFieldOutput, DateTimeFieldOutput, DateTimeRangeFieldOutput, MonthFieldOutput, MonthRangeFieldOutput, YearFieldOutput } from '../fields/date-family/types.js';
+import type { DateFieldOutput } from '../fields/date/types.js';
+import type { FileFieldOutput } from '../fields/file/types.js';
+import type { HiddenFieldOutput } from '../fields/hidden/types.js';
+import type { HierarchyFieldOutput } from '../fields/hierarchy/types.js';
+import type { NumberFieldOutput } from '../fields/number/types.js';
+import type { ObjectFieldOutput } from '../fields/object/types.js';
+import type { OneTimeCodeFieldOutput } from '../fields/one-time-code/types.js';
+import type { PasswordFieldOutput } from '../fields/password/types.js';
+import type { PhoneNumberFieldOutput } from '../fields/phone-number/types.js';
+import type { RadioCardFieldOutput } from '../fields/radio-card/types.js';
+import type { RadioFieldOutput } from '../fields/radio/types.js';
+import type { RatingFieldOutput } from '../fields/rating/types.js';
+import type { SelectFieldOutput } from '../fields/select/types.js';
+import type { SliderFieldOutput } from '../fields/slider/types.js';
+import type { SwitchGroupFieldOutput } from '../fields/switch-group/types.js';
+import type { SwitchFieldOutput } from '../fields/switch/types.js';
+import type { TagFieldOutput } from '../fields/tag/types.js';
+import type { TextFieldOutput } from '../fields/text/types.js';
+import type { TextareaFieldOutput } from '../fields/textarea/types.js';
+import type { TimeFieldOutput } from '../fields/time/types.js';
+import type { UploadFieldOutput } from '../fields/upload/types.js';
+export type { FormStateMode, NullableValue } from './field-output-utils.js';
+export type { ObjectFieldOutput } from '../fields/object/types.js';
+export type { ArrayListFieldOutput } from '../fields/array-list/types.js';
+export type { ArrayTableFieldOutput } from '../fields/array-table/types.js';
+export type { ArrayTabsFieldOutput } from '../fields/array-tabs/types.js';
+export type { ArrayVariantFieldOutput } from '../fields/array-variant/types.js';
+export type { GroupFieldOutput } from '../fields/group/types.js';
+export type { MatrixFieldOutput } from '../fields/matrix/types.js';
+export type ResolveFormFieldValue<TField> = TField extends {
+    type: 'text';
+} ? TextFieldOutput : TField extends {
+    type: 'password';
+} ? PasswordFieldOutput : TField extends {
+    type: 'textarea';
+} ? TextareaFieldOutput : TField extends {
+    type: 'number';
+} ? NumberFieldOutput : TField extends {
+    type: 'auto-complete';
+} ? AutoCompleteFieldOutput<TField> : TField extends {
+    type: 'checkbox';
+} ? CheckboxFieldOutput : TField extends {
+    type: 'switch';
+} ? SwitchFieldOutput<TField> : TField extends {
+    type: 'switch-group';
+} ? SwitchGroupFieldOutput<TField> : TField extends {
+    type: 'radio';
+} ? RadioFieldOutput<TField> : TField extends {
+    type: 'radio-card';
+} ? RadioCardFieldOutput<TField> : TField extends {
+    type: 'checkbox-group';
+} ? CheckboxGroupFieldOutput<TField> : TField extends {
+    type: 'checkbox-card';
+} ? CheckboxCardFieldOutput<TField> : TField extends {
+    type: 'select';
+} ? SelectFieldOutput<TField> : TField extends {
+    type: 'phone-number';
+} ? PhoneNumberFieldOutput : TField extends {
+    type: 'hidden';
+} ? HiddenFieldOutput<TField> : TField extends {
+    type: 'custom-component';
+} ? CustomComponentFieldOutput<TField> : TField extends {
+    type: 'file';
+} ? FileFieldOutput<TField> : TField extends {
+    type: 'upload';
+} ? UploadFieldOutput<TField> : TField extends {
+    type: 'slider';
+} ? SliderFieldOutput<TField> : TField extends {
+    type: 'color-picker';
+} ? ColorPickerFieldOutput : TField extends {
+    type: 'one-time-code';
+} ? OneTimeCodeFieldOutput : TField extends {
+    type: 'tag';
+} ? TagFieldOutput : TField extends {
+    type: 'rating';
+} ? RatingFieldOutput : TField extends {
+    type: 'date';
+} ? DateFieldOutput : TField extends {
+    type: 'datetime';
+} ? DateTimeFieldOutput : TField extends {
+    type: 'daterange';
+} ? DateRangeFieldOutput : TField extends {
+    type: 'monthrange';
+} ? MonthRangeFieldOutput : TField extends {
+    type: 'datetimerange';
+} ? DateTimeRangeFieldOutput : TField extends {
+    type: 'month';
+} ? MonthFieldOutput : TField extends {
+    type: 'year';
+} ? YearFieldOutput : TField extends {
+    type: 'time';
+} ? TimeFieldOutput : TField extends {
+    type: 'tree-select' | 'cascader' | 'tree';
+} ? HierarchyFieldOutput<TField> : TField extends {
+    type: 'object';
+} ? ObjectFieldOutput<unknown> : unknown;
+export type ExtractFormFieldInternalValue<TField> = ResolveFormFieldValue<TField>;

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

@@ -0,0 +1,88 @@
+import type { FormArrayListField } from '../fields/array-list/types.js';
+import type { FormArrayTableField } from '../fields/array-table/types.js';
+import type { FormArrayTabsField } from '../fields/array-tabs/types.js';
+import type { FormArrayVariantField } from '../fields/array-variant/types.js';
+import type { FormAutoCompleteField } from '../fields/auto-complete/types.js';
+import type { FormButtonField } from '../fields/button/types.js';
+import type { FormCardField } from '../fields/card/types.js';
+import type { FormCheckboxCardField } from '../fields/checkbox-card/types.js';
+import type { FormCheckboxGroupField } from '../fields/checkbox-group/types.js';
+import type { FormCheckboxField } from '../fields/checkbox/types.js';
+import type { FormColorPickerField } from '../fields/color-picker/types.js';
+import type { FormColumnField } from '../fields/column/types.js';
+import type { FormCustomComponentField } from '../fields/custom-component/types.js';
+import type { FormDateRangeField, FormDateTimeField, FormDateTimeRangeField, FormMonthField, FormMonthRangeField, FormYearField } from '../fields/date-family/types.js';
+import type { FormDateField } from '../fields/date/types.js';
+import type { FormDividerField } from '../fields/divider/types.js';
+import type { FormFileField } from '../fields/file/types.js';
+import type { FormGroupField } from '../fields/group/types.js';
+import type { FormHiddenField } from '../fields/hidden/types.js';
+import type { FormCascaderField, FormTreeField, FormTreeSelectField } from '../fields/hierarchy/types.js';
+import type { FormInfoField } from '../fields/info/types.js';
+import type { FormInputGroupField } from '../fields/input-group/types.js';
+import type { FormMatrixField } from '../fields/matrix/types.js';
+import type { FormNumberField } from '../fields/number/types.js';
+import type { FormObjectField } from '../fields/object/types.js';
+import type { FormOneTimeCodeField } from '../fields/one-time-code/types.js';
+import type { FormPasswordField } from '../fields/password/types.js';
+import type { FormPhoneNumberField } from '../fields/phone-number/types.js';
+import type { FormRadioCardField } from '../fields/radio-card/types.js';
+import type { FormRadioField } from '../fields/radio/types.js';
+import type { FormRatingField } from '../fields/rating/types.js';
+import type { FormSelectField } from '../fields/select/types.js';
+import type { FormSliderField } from '../fields/slider/types.js';
+import type { FormSwitchGroupField } from '../fields/switch-group/types.js';
+import type { FormSwitchField } from '../fields/switch/types.js';
+import type { FormTagField } from '../fields/tag/types.js';
+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';
+export type { FormContainerFieldBase, FormFieldType, FormStatefulFieldBase, FormStatelessFieldBase, } from './field-base.js';
+export type { FormArrayListField } from '../fields/array-list/types.js';
+export type { FormArrayTableField } from '../fields/array-table/types.js';
+export type { FormArrayTabsField } from '../fields/array-tabs/types.js';
+export type { FormArrayVariantField } from '../fields/array-variant/types.js';
+export type { FormAutoCompleteField } from '../fields/auto-complete/types.js';
+export type { FormButtonField } from '../fields/button/types.js';
+export type { FormCardField } from '../fields/card/types.js';
+export type { FormCheckboxCardField } from '../fields/checkbox-card/types.js';
+export type { FormCheckboxField } from '../fields/checkbox/types.js';
+export type { FormCheckboxGroupField } from '../fields/checkbox-group/types.js';
+export type { FormColorPickerField } from '../fields/color-picker/types.js';
+export type { FormColumnField } from '../fields/column/types.js';
+export type { FormCustomComponentField } from '../fields/custom-component/types.js';
+export type { FormDateField } from '../fields/date/types.js';
+export type { FormDateFamilyField, FormDateRangeField, FormDateTimeField, FormDateTimeRangeField, FormMonthField, FormMonthRangeField, FormYearField, } from '../fields/date-family/types.js';
+export type { FormDividerField } from '../fields/divider/types.js';
+export type { FormFileField } from '../fields/file/types.js';
+export type { FormHiddenField } from '../fields/hidden/types.js';
+export type { FormGroupField } from '../fields/group/types.js';
+export type { FormCascaderField, FormHierarchyField, FormHierarchyOption, FormTreeField, FormTreeSelectField, } from '../fields/hierarchy/types.js';
+export type { FormInfoField } from '../fields/info/types.js';
+export type { FormInputGroupField } from '../fields/input-group/types.js';
+export type { FormMatrixField, FormMatrixRow } from '../fields/matrix/types.js';
+export type { FormNumberField } from '../fields/number/types.js';
+export type { FormOneTimeCodeField } from '../fields/one-time-code/types.js';
+export type { FormObjectField } from '../fields/object/types.js';
+export type { FormPasswordField } from '../fields/password/types.js';
+export type { FormPhoneNumberField } from '../fields/phone-number/types.js';
+export type { FormRadioCardField } from '../fields/radio-card/types.js';
+export type { FormRadioField } from '../fields/radio/types.js';
+export type { FormRatingField } from '../fields/rating/types.js';
+export type { FormSelectCreateItem, FormSelectField } from '../fields/select/types.js';
+export type { FormSliderField } from '../fields/slider/types.js';
+export type { FormSwitchGroupField } from '../fields/switch-group/types.js';
+export type { FormSwitchField } from '../fields/switch/types.js';
+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';
+/**
+ * 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 = {}, TDeps = {}> = 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> | FormInputGroupField<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> | 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/focus.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal focus request emitted by the runtime and consumed by mounted field renderers.
+ */
+export interface FormFocusRequest {
+    /** Normalized dotted field path to focus. */
+    path: string;
+    /** Monotonic value so repeated focus calls to the same path still notify renderers. */
+    sequence: number;
+}

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

@@ -0,0 +1,92 @@
+import type { ComputedRef } from 'vue';
+import type { FormSubmitHandler } from './api.js';
+import type { FormController } from './controller.js';
+import type { ExtractFormOutput } from './output.js';
+import type { FormObject } from './utils.js';
+export type FormApiDisplayMode = 'modal' | 'drawer' | 'fullscreen';
+export type FormApiDisplayModeInput = FormApiDisplayMode | string | (() => FormApiDisplayModeInput);
+export interface FormApiCreateBaseOptions {
+    /** Optional stable runtime id used by external controls such as `closeForm` or `submitForm`. */
+    id?: string;
+    /** Initial internal state passed to the rendered form. */
+    input?: FormObject;
+    /** Overlay display mode used by the provider. Supports responsive values such as `drawer md:modal`. */
+    mode?: FormApiDisplayModeInput;
+}
+export interface FormApiCreateOptions<TSchema, TSubmitData = unknown> extends FormApiCreateBaseOptions {
+    /** Optional submit handler owned by the form overlay. Keeps submit buttons pending until it settles. */
+    onSubmit?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>;
+}
+type CompletedFormApiResult<TOutput, TSubmitData> = [TSubmitData] extends [undefined] ? {
+    isCompleted: true;
+    formData: TOutput;
+    submitData?: undefined;
+} : {
+    isCompleted: true;
+    formData: TOutput;
+    submitData: TSubmitData;
+};
+export type FormApiCreateResult<TOutput, TSubmitData = undefined> = {
+    isCompleted: false;
+    formData: TOutput;
+    submitData?: undefined;
+} | CompletedFormApiResult<TOutput, TSubmitData>;
+export interface FormApiRuntimeInstance {
+    id: string;
+    schema: unknown;
+    input?: FormObject;
+    mode: FormApiDisplayModeInput;
+    onSubmit?: FormSubmitHandler<FormObject, unknown>;
+    complete: (formData: FormObject, submitData?: unknown) => void;
+    cancel: (formData: FormObject) => void;
+}
+export interface FormApiRuntimeControls {
+    close: () => void;
+    submit: () => Promise<boolean>;
+}
+export interface FormApiControllerRegistry {
+    getController: (id: string) => FormController<unknown, unknown> | null;
+    setController: (id: string, controller: FormController<unknown, unknown>) => void;
+    removeController: (id: string, controller: FormController<unknown, unknown>) => void;
+    setRuntimeControls: (id: string, controls: FormApiRuntimeControls) => void;
+    removeRuntimeControls: (id: string, controls: FormApiRuntimeControls) => void;
+}
+/**
+ * Global form API provided by `<NutFormProvider>`.
+ *
+ * The primary entrypoint is `createForm`, which renders a schema in a provider-owned overlay
+ * and resolves when the user submits or cancels the form.
+ *
+ * @example
+ * ```ts
+ * const result = await formApi.createForm(accountForm, {
+ *   mode: 'drawer',
+ *   input: account,
+ *   onSubmit: ({ formData }) => saveAccount(formData),
+ * })
+ * ```
+ */
+export interface FormApiController extends FormApiControllerRegistry {
+    /** Active provider-owned form overlays. */
+    formInstances: ComputedRef<readonly FormApiRuntimeInstance[]>;
+    /** Opens a schema in the provider overlay runtime. */
+    createForm: {
+        <const TSchema>(schema: TSchema): Promise<FormApiCreateResult<ExtractFormOutput<TSchema>>>;
+        <const TSchema, TSubmitData>(schema: TSchema, options: FormApiCreateBaseOptions & {
+            onSubmit: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>;
+        }): Promise<FormApiCreateResult<ExtractFormOutput<TSchema>, TSubmitData>>;
+        <const TSchema>(schema: TSchema, input: FormObject): Promise<FormApiCreateResult<ExtractFormOutput<TSchema>>>;
+        <const TSchema, TSubmitData = undefined>(schema: TSchema, options: FormApiCreateOptions<TSchema, TSubmitData>): Promise<FormApiCreateResult<ExtractFormOutput<TSchema>, TSubmitData>>;
+    };
+    /** Returns an active form overlay by id or form schema key. */
+    getForm: (idOrFormKey: string) => FormApiRuntimeInstance | null;
+    /** True when a form overlay with the id or schema form key is active. */
+    isOpen: (idOrFormKey: string) => boolean;
+    /** Cancels an active form overlay and resolves its promise as incomplete. */
+    closeForm: (idOrFormKey: string) => boolean;
+    /** Submits an active form overlay through its controller, when mounted. */
+    submitForm: (idOrFormKey: string) => Promise<boolean>;
+    /** Cancels every active form overlay. */
+    destroyAll: () => void;
+}
+export {};

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

@@ -0,0 +1,25 @@
+export type * from './api';
+export type * from './actions';
+export type * from './callbacks';
+export type * from './context';
+export type * from './controller';
+export type * from './dependencies';
+export type * from './field';
+export type * from './field-base';
+export type * from './field-output';
+export type * from './field-output-utils';
+export type * from './field-kind';
+export type * from './focus';
+export type * from './form-api';
+export type * from './layout';
+export type * from './options';
+export type * from './options-runtime';
+export type * from './overlay';
+export type * from './output';
+export type * from './runtime';
+export type * from './schema';
+export type * from './transform';
+export type * from './ui';
+export type * from './utils';
+export type * from './upload-runtime';
+export type * from './validation';

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

@@ -0,0 +1,32 @@
+/**
+ * Layout options available at form or step level.
+ */
+export interface FormLayoutConfig {
+    /** Number of columns used by the current field grid. */
+    columns?: number | string;
+    /** Default column span used by fields that do not define `layout.span`. */
+    fieldSpan?: number | string;
+    /** Gap between fields in the owning grid. */
+    gap?: number | string;
+}
+/**
+ * Layout options available to normal form items.
+ */
+export interface FormItemLayout {
+    /** Column span for this field inside the owning layout grid. Replaces legacy `size`. */
+    span?: number | string;
+}
+/**
+ * Layout options available to fields that render child fields.
+ */
+export interface FormContainerLayout extends FormItemLayout {
+    /** Column definition for child fields. Replaces legacy `gridSize`. */
+    columns?: number | string;
+    /** Visual variant used by structural field renderers. */
+    variant?: 'plain' | 'card' | 'section' | 'fieldset';
+}
+/**
+ * Rendering shell used by `<NutForm>` when the same form root is placed inline or inside
+ * overlay layouts.
+ */
+export type FormRenderShell = 'inline' | 'drawer' | 'modal' | 'fullscreen';