nuxt-ui-tools 0.1.3 → 1.0.0

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

@@ -1,17 +1,29 @@
+import type { FormValue } from './/index.js';
+import type { FormFieldApi } from './api.js';
 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, FormRenderable, FormText } from './utils.js';
-import type { FormValidationConfig } from './validation.js';
+import type { FormValidationConfig, FormValidatorsConfig } 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';
+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' | 'section' | 'input-group' | 'tabs' | 'object' | 'custom-component' | 'file' | 'upload' | 'array-list' | 'array-table' | 'array-tabs' | 'array-variant' | 'array-collapse' | 'array-primitive' | 'tree-select' | 'cascader' | 'tree' | 'group' | 'matrix' | 'slider' | 'color-picker' | 'one-time-code' | 'tag' | 'rating' | 'button' | 'card' | 'column';
+export type FormFieldDescriptionDisplay = 'inline' | 'tooltip' | 'modal';
+export interface FormFieldDescription {
+    text: FormText;
+    display?: FormFieldDescriptionDisplay;
+    title?: FormText;
+}
 /**
  * Common stateful field properties.
  */
-export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TContext = {}, TDeps = {}> {
+export type FormFieldProps<TProps = FormObject, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>> = FormDynamic<TProps & FormObject, {
+    ctx: TContext;
+    deps: TDeps;
+}>;
+export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TProps = FormObject> {
     /** Raw path used to read/write the field value in form state. */
     key: string;
     /** Discriminant used by the field registry. */
@@ -19,34 +31,40 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
     /** Initial field value. */
     default?: FormDynamic<TValue, {
         ctx: TContext;
+        api: FormFieldApi<TValue, FormValue, TContext>;
     }>;
     /** Label rendered by the field wrapper. */
     label?: FormText;
-    /** Optional supporting copy rendered near the control. */
-    description?: FormText;
+    /** Optional supporting copy rendered near the control, or a tooltip/modal variant. */
+    description?: FormText | FormFieldDescription;
     /** Optional right-side hint rendered by the field wrapper. */
     hint?: FormText;
+    /** Optional help text rendered under the control. */
+    help?: FormText;
     /** Optional rich content rendered beside the label. Takes precedence over `hint`. */
     labelExtra?: FormRenderable;
-    /** Placeholder forwarded to controls that support placeholders. */
-    placeholder?: FormText;
+    /** Placeholder forwarded to controls that support placeholders. Callbacks receive `{ ctx, deps, api }`. */
+    placeholder?: FormText | FormFieldCallback<FormText, TContext, TDeps, TValue>;
     /** 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;
-    }>;
+    /** Control props: the typed props of this kind plus any Nuxt UI prop as passthrough. */
+    props?: FormFieldProps<TProps, TContext, 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>;
+    /** Marks this field as required. */
+    required?: boolean | FormFieldCallback<boolean, TContext, TDeps, TValue>;
+    /** Message used by the required rule. */
+    requiredMessage?: FormText;
+    /** Native Regle validation rules. */
+    validators?: FormValidatorsConfig<TContext>;
     /** Input/output transforms for this field. */
-    transform?: FormTransformConfig<TValue, unknown, TContext, TDeps>;
+    transform?: FormTransformConfig<TValue, FormValue, TContext, TDeps>;
     /** Submit/output behavior for this field. */
     submit?: {
         /** Excludes the field from submitted output while keeping it in internal form state. */
@@ -55,7 +73,7 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
     /** Runs after this field value changes. */
     watch?: (params: {
         value: TValue;
-        api: import('./api').FormFieldApi<TValue>;
+        api: FormFieldApi<TValue>;
     }) => void;
     /** Vue watch options used by the field value effect. */
     watchOptions?: {
@@ -83,18 +101,15 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
 /**
  * Base properties for stateless visual fields.
  */
-export interface FormStatelessFieldBase<TType extends FormFieldType, TContext = {}, TDeps = {}> {
+export interface FormStatelessFieldBase<TType extends FormFieldType, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TProps = FormObject> {
     /** 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;
-    }>;
+    /** Control props: the typed props of this kind plus any Nuxt UI prop as passthrough. */
+    props?: FormFieldProps<TProps, TContext, TDeps>;
     /** Controls whether the field is rendered. */
     condition?: FormFieldCallback<boolean, TContext, TDeps>;
     /** Excludes this renderer from the runtime. */
@@ -103,7 +118,7 @@ export interface FormStatelessFieldBase<TType extends FormFieldType, TContext =
 /**
  * Base properties for structural fields that render children.
  */
-export interface FormContainerFieldBase<TType extends FormFieldType, TContext = {}, TDeps = {}> {
+export interface FormContainerFieldBase<TType extends FormFieldType, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TProps = FormObject> {
     /** Stable renderer key. */
     key: string;
     /** Discriminant used by the field registry. */
@@ -114,15 +129,33 @@ export interface FormContainerFieldBase<TType extends FormFieldType, TContext =
     description?: FormText;
     /** Child fields rendered inside this field. */
     fields: readonly FormField<TContext, TDeps>[];
+    /** Raw dependency paths read before evaluating callbacks. */
+    dependencies?: readonly (string | readonly [string, string])[];
     /** Container layout options. */
     layout?: FormContainerLayout;
-    /** UI-library-specific props. */
-    props?: FormDynamic<FormObject, {
-        ctx: TContext;
-        deps: TDeps;
-    }>;
+    /** Control props: the typed props of this kind plus any Nuxt UI prop as passthrough. */
+    props?: FormFieldProps<TProps, TContext, TDeps>;
     /** Controls whether the field is rendered. */
     condition?: FormFieldCallback<boolean, TContext, TDeps>;
     /** Excludes this container and its children from the runtime. */
     ignore?: boolean;
+    /** Runs after the container value changes. */
+    watch?: (params: {
+        value: FormValue;
+        api: FormFieldApi<FormValue>;
+    }) => void;
+    /** Vue watch options used by the container value effect. */
+    watchOptions?: {
+        deep?: boolean;
+        immediate?: boolean;
+    };
+    /** Runs when the resolved dependency object changes. */
+    onDependencyChange?: FormFieldCallback<FormMaybePromise<void>, TContext, TDeps>;
+    /** Runs after the container renderer is mounted. */
+    onRendered?: FormFieldCallback<FormMaybePromise<void>, TContext, TDeps>;
+    /** Debounces or throttles value/dependency effects. */
+    stateEffect?: {
+        type: 'debounce' | 'throttle';
+        duration: number;
+    };
 }

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

@@ -2,6 +2,9 @@ import type { DataTag, QueryKey } from './context.js';
 import type { FormOptionValue } from './options.js';
 export type FormStateMode = 'internal' | 'output';
 export type NullableValue = null;
+export type FieldProps<TField> = TField extends {
+    readonly props: infer TProps;
+} ? TProps extends (...args: never[]) => infer TResult ? TResult : TProps : NonNullable<unknown>;
 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;

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

@@ -26,15 +26,18 @@ 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';
+import type { FormValue } from './/index.js';
 export type { FormStateMode, NullableValue } from './field-output-utils.js';
 export type { ObjectFieldOutput } from '../fields/object/types.js';
+export type { ArrayCollapseFieldOutput } from '../fields/array-collapse/types.js';
 export type { ArrayListFieldOutput } from '../fields/array-list/types.js';
+export type { ArrayPrimitiveFieldOutput } from '../fields/array-primitive/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 ResolveNullableFormFieldValue<TField> = TField extends {
     type: 'text';
 } ? TextFieldOutput : TField extends {
     type: 'password';
@@ -100,5 +103,8 @@ export type ResolveFormFieldValue<TField> = TField extends {
     type: 'tree-select' | 'cascader' | 'tree';
 } ? HierarchyFieldOutput<TField> : TField extends {
     type: 'object';
-} ? ObjectFieldOutput<unknown> : unknown;
+} ? ObjectFieldOutput<FormValue> : FormValue;
+export type ResolveFormFieldValue<TField> = TField extends {
+    required: true;
+} ? NonNullable<ResolveNullableFormFieldValue<TField>> : ResolveNullableFormFieldValue<TField>;
 export type ExtractFormFieldInternalValue<TField> = ResolveFormFieldValue<TField>;

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

@@ -1,4 +1,6 @@
+import type { FormArrayCollapseField } from '../fields/array-collapse/types.js';
 import type { FormArrayListField } from '../fields/array-list/types.js';
+import type { FormArrayPrimitiveField } from '../fields/array-primitive/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';
@@ -29,17 +31,21 @@ 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 { FormSectionField } from '../fields/section/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 { FormTabsField } from '../fields/tabs/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 { FormArrayCollapseField } from '../fields/array-collapse/types.js';
 export type { FormArrayListField } from '../fields/array-list/types.js';
+export type { FormArrayPrimitiveField, FormArrayPrimitiveItemField, } from '../fields/array-primitive/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';
@@ -55,6 +61,7 @@ export type { FormCustomComponentField } from '../fields/custom-component/types.
 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 { FormSectionField } from '../fields/section/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';
@@ -74,6 +81,7 @@ export type { FormSelectCreateItem, FormSelectField } from '../fields/select/typ
 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 { FormTab, FormTabsField } from '../fields/tabs/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';
@@ -85,4 +93,4 @@ export type { FormUploadField } from '../fields/upload/types.js';
  * 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>;
+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>;

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

@@ -1,4 +1,5 @@
 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';
@@ -13,7 +14,13 @@ export interface FormApiCreateBaseOptions {
     /** 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 {
+export interface FormResolvedCreateOptions {
+    id?: string;
+    input?: FormObject;
+    mode: FormApiDisplayModeInput;
+    onSubmit?: FormSubmitHandler<FormObject, FormValue>;
+}
+export interface FormApiCreateOptions<TSchema, TSubmitData = FormValue> extends FormApiCreateBaseOptions {
     /** Optional submit handler owned by the form overlay. Keeps submit buttons pending until it settles. */
     onSubmit?: FormSubmitHandler<ExtractFormOutput<TSchema>, TSubmitData>;
 }
@@ -33,11 +40,11 @@ export type FormApiCreateResult<TOutput, TSubmitData = undefined> = {
 } | CompletedFormApiResult<TOutput, TSubmitData>;
 export interface FormApiRuntimeInstance {
     id: string;
-    schema: unknown;
+    schema: FormValue;
     input?: FormObject;
     mode: FormApiDisplayModeInput;
-    onSubmit?: FormSubmitHandler<FormObject, unknown>;
-    complete: (formData: FormObject, submitData?: unknown) => void;
+    onSubmit?: FormSubmitHandler<FormObject, FormValue>;
+    complete: (formData: FormObject, submitData?: FormValue) => void;
     cancel: (formData: FormObject) => void;
 }
 export interface FormApiRuntimeControls {
@@ -45,9 +52,9 @@ export interface FormApiRuntimeControls {
     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;
+    getController: (id: string) => FormController<FormValue, FormValue> | null;
+    setController: (id: string, controller: FormController<FormValue, FormValue>) => void;
+    removeController: (id: string, controller: FormController<FormValue, FormValue>) => void;
     setRuntimeControls: (id: string, controls: FormApiRuntimeControls) => void;
     removeRuntimeControls: (id: string, controls: FormApiRuntimeControls) => void;
 }

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

@@ -1,7 +1,12 @@
 /**
  * Layout options available at form or step level.
  */
+export type FormLabelPosition = 'top' | 'left';
 export interface FormLayoutConfig {
+    /** Label placement for every field of the form. */
+    labelPosition?: FormLabelPosition;
+    /** Label column width when labels sit on the left. */
+    labelWidth?: number | string;
     /** Number of columns used by the current field grid. */
     columns?: number | string;
     /** Default column span used by fields that do not define `layout.span`. */
@@ -15,6 +20,12 @@ export interface FormLayoutConfig {
 export interface FormItemLayout {
     /** Column span for this field inside the owning layout grid. Replaces legacy `size`. */
     span?: number | string;
+    /** Fixed width used by renderers that lay fields out as columns, such as array tables. */
+    width?: number | string;
+    /** Label placement for this field. */
+    labelPosition?: FormLabelPosition;
+    /** Label column width when the label sits on the left. */
+    labelWidth?: number | string;
 }
 /**
  * Layout options available to fields that render child fields.

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

@@ -1,42 +1,49 @@
 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>>;
+import type { FormValue } from './/index.js';
 /**
- * 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.
+ * Query options accepted by option sources once they cross the runtime boundary.
+ */
+export type FormRuntimeQueryOptions = Exclude<UseQueryOptions<FormValue, Error, FormValue, FormValue, QueryKey>, Ref<FormValue> | ComputedRef<FormValue>>;
+/**
+ * Option state registered by a mounted option field and read through the field API.
  */
 export interface FormOptionRuntimeState {
-    /** Current normalized options, including locally-created options. */
+    /** Options available to the control: loaded pages merged with hydrated selections. */
     items: ComputedRef<readonly ResolvedFormOption[]>;
-    /** True while the first usable option payload is loading. */
+    /** Hydrated options for the current selection, including values outside the loaded pages. */
+    selectedItems: ComputedRef<readonly ResolvedFormOption[]>;
     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. */
+    error: ComputedRef<FormValue | null>;
     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. */
+    /** True when options load remotely with search and pagination. */
+    remote: ComputedRef<boolean>;
+    /** Current remote search term. */
+    search: ComputedRef<string>;
+    /** True when another remote page can be loaded. */
+    hasMore: ComputedRef<boolean>;
+    /** True while a next page is loading. */
+    loadingMore: ComputedRef<boolean>;
+    /** True when the last remote request failed and can be retried. */
+    retryable: ComputedRef<boolean>;
+    /** Distance from the list end that triggers the next page. */
+    prefetchDistance: ComputedRef<number | 'viewport'>;
     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. */
+    retry: () => Promise<void>;
+    /** Starts remote loading, typically when the menu opens. */
+    activate: () => void;
+    setSearch: (term: string) => void;
+    loadMore: () => Promise<void>;
+    /** Loads the direct children of a remote tree option. */
+    loadChildren: (option: ResolvedFormOption) => Promise<void>;
+    add: (option: FormValue) => void;
     create: (label: string) => Promise<ResolvedFormOption | null>;
 }

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

@@ -1,3 +1,4 @@
+import type { FormValue } from './/index.js';
 import type { FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
 import type { FormMaybePromise, FormText } from './utils.js';
@@ -25,15 +26,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 = {}, TDeps = {}, TValue = unknown> = 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 = NonNullable<unknown>, 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 = {}, TDeps = {}, TValue = unknown, TOption = unknown> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormCreateOptionParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, 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 = {}, TDeps = {}, TValue = unknown> {
+export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> {
     /** Label shown by the create affordance. */
     label?: FormText;
     /** Selects the newly-created option immediately. Defaults to `true`. */
@@ -43,14 +44,16 @@ export interface FormCreateOption<TOption, TContext = {}, TDeps = {}, TValue = u
     /** 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> {
+export interface FormOptionsChangeParams<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, 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 = {}, TDeps = {}, TValue = unknown> {
+export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, 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. */
     source: FormOptionsSource<TOption, TContext, TDeps, TValue>;
     /** Optional creation behavior for missing options. */
@@ -64,3 +67,71 @@ export interface FormOptionConfig<TOption, TContext = {}, TDeps = {}, TValue = u
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
+/**
+ * Page envelope returned by an index-paginated remote option source.
+ */
+export interface FormRemoteOptionsPage<TOption> {
+    options: readonly TOption[];
+    hasMore: boolean;
+}
+/**
+ * Page envelope returned by a cursor-paginated remote option source.
+ */
+export interface FormRemoteCursorOptionsPage<TOption> {
+    options: readonly TOption[];
+    nextCursor: string | null;
+}
+export type FormRemoteOptionsResult<TOption> = FormRemoteOptionsPage<TOption> | FormRemoteCursorOptionsPage<TOption>;
+export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, 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. */
+    page: {
+        index: number;
+        cursor: string | null;
+        size: number;
+    };
+    /** 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> {
+    /** Selected values that are not present in the loaded pages. */
+    values: readonly FormOptionValue[];
+}
+export type FormRemoteSource<TResult> = FormQueryOptions<TResult> | Promise<TResult>;
+export interface FormRemotePagination {
+    type: 'page' | 'cursor';
+    /** Page size forwarded to the source. */
+    size: number;
+    /** Distance from the list end that triggers the next page: pixels, or `'viewport'` for three viewport heights. Defaults to `'viewport'`. */
+    prefetchDistance?: number | 'viewport';
+}
+export interface FormRemoteSearch {
+    /** Debounce applied to typed search terms, in milliseconds. Defaults to 250. */
+    debounce?: number;
+    /** Minimum term length before a search request runs. Defaults to 0. */
+    minLength?: number;
+}
+/**
+ * Remote option configuration: server-side search, pagination, and selected-value hydration.
+ */
+export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, 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<FormRemoteOptionsResult<TOption>>;
+    /** Hydrates selected values that the loaded pages do not contain. */
+    resolveSelected?: (request: FormRemoteSelectedRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<readonly TOption[]>;
+    pagination: FormRemotePagination;
+    search?: FormRemoteSearch;
+    /** Dependency aliases whose changes reset the loaded pages and re-run selected hydration. */
+    refreshOn?: readonly string[];
+    /** Clears selected values the latest successful selected hydration did not return. Defaults to `false`. */
+    clearOnInvalid?: boolean;
+    /** Optional creation behavior for missing options. */
+    create?: FormCreateOption<TOption, TContext, TDeps, TValue>;
+    /** Enables the field-level refresh affordance. */
+    allowOptionsRefresh?: boolean;
+    /** Disable the field while its option source has no usable data yet. */
+    disableOnLoading?: boolean;
+}
+export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;