nuxt-ui-tools 1.9.0 → 1.10.1

package/dist/module.json

@@ -5,7 +5,7 @@
   "configKey": "nuxtUiTools",
   "docs": "https://ui.nuxt.com/docs/getting-started/installation/nuxt",
   "name": "nuxt-ui-tools",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/form/composables/use-field-control.d.ts

@@ -30,7 +30,7 @@ export declare function useFieldControl<TField extends FormField>(field: () => T
         activate: () => void;
         add: (option: FormValue) => import("../utils/options.js").ResolvedFormOption;
         creatable: import("vue").ComputedRef<boolean>;
-        create: (label: string) => Promise<import("../utils/options.js").ResolvedFormOption | null>;
+        create: (label?: string) => Promise<import("../utils/options.js").ResolvedFormOption | null>;
         createLabel: import("vue").ComputedRef<string | undefined>;
         creating: import("vue").ComputedRef<boolean>;
         disableOnLoading: import("vue").ComputedRef<boolean>;
@@ -54,7 +54,7 @@ export declare function useFieldControl<TField extends FormField>(field: () => T
         selectedItems: import("vue").ComputedRef<readonly import("../utils/options.js").ResolvedFormOption[]>;
         setSearch: (term: string) => void;
     };
-    params: import("vue").ComputedRef<import("../types/index.js").FormFieldCallbackParams<{}, Readonly<import("../../shared/index.js").GenericObject>, unknown, unknown>>;
+    params: import("vue").ComputedRef<import("../types/index.js").FormFieldCallbackParams<{}, import("../types/index.js").FormDependencies, unknown, unknown>>;
     placeholder: import("vue").ComputedRef<string>;
     validationPending: import("vue").ComputedRef<boolean>;
 };

package/dist/runtime/form/composables/use-field-effects.js

@@ -1,6 +1,7 @@
 import { debounceFilter, throttleFilter, watchWithFilter } from "@vueuse/core";
 import { computed, onMounted } from "vue";
 import { isEqualFormValue } from "../utils/compare.js";
+import { readFormDependencyValues } from "../utils/dependencies.js";
 import { cloneFormValue } from "../utils/path.js";
 import { isFunction, isNumber, isObject } from "../utils/predicate.js";
 import { useFormRuntimeContext } from "./use-form-runtime.js";
@@ -29,7 +30,7 @@ export function useFieldEffects(field, path) {
     }
   );
   watchWithFilter(
-    () => params.value.deps,
+    () => readFormDependencyValues(params.value.deps),
     (deps) => {
       if (lastDeps !== UNSET && isEqualFormValue(deps, lastDeps)) {
         return;

package/dist/runtime/form/composables/use-field-options.d.ts

@@ -12,7 +12,7 @@ export declare function useFieldOptions(params: {
     activate: () => void;
     add: (option: FormValue) => ResolvedFormOption;
     creatable: ComputedRef<boolean>;
-    create: (label: string) => Promise<ResolvedFormOption | null>;
+    create: (label?: string) => Promise<ResolvedFormOption | null>;
     createLabel: ComputedRef<string | undefined>;
     creating: ComputedRef<boolean>;
     disableOnLoading: ComputedRef<boolean>;

package/dist/runtime/form/composables/use-field-options.js

@@ -46,7 +46,10 @@ export function useFieldOptions(params) {
     }
     return resolveTrackedOptionSource(params.field(), params.callbackParams.value);
   });
-  const resolvedSource = computed(() => trackedOptionSource.value.source);
+  const resolvedSource = computed(() => {
+    const { source } = trackedOptionSource.value;
+    return isRuntimeQueryOptions(source) && isDisabledQueryOptions(source) ? [] : source;
+  });
   const contextResources = computed(() => {
     const { ctx } = params.callbackParams.value;
     if (!isRecord(ctx)) {
@@ -260,8 +263,8 @@ export function useFieldOptions(params) {
     return normalized;
   }
   async function create(label) {
-    const normalizedLabel = label.trim();
-    if (!normalizedLabel || creating.value) {
+    const normalizedLabel = label?.trim() ?? "";
+    if (!isUndefined(label) && !normalizedLabel || creating.value) {
       return null;
     }
     const createOption = optionConfig.value?.create;
@@ -359,7 +362,7 @@ function resolveRemoteOptionConfig(field) {
       resolveSelected: loader.resolveSelected,
       search: loader.search,
       selectedQueryKeyFor: loader.selectedQueryKeyFor,
-      source: loader.load
+      load: loader.load
     };
   }
   return isRemoteOptionConfig(options) ? options : null;
@@ -372,7 +375,7 @@ function isRemoteLoaderOptionConfig(value) {
   return isFunction(loader.load) && isFunction(loader.resolveSelected) && isRecord(loader.pagination);
 }
 function isRemoteOptionConfig(value) {
-  return isRecord(value) && value.mode === "remote" && isFunction(Object.getOwnPropertyDescriptor(value, "source")?.value) && isRecord(value.pagination);
+  return isRecord(value) && value.mode === "remote" && isFunction(Object.getOwnPropertyDescriptor(value, "load")?.value) && isRecord(value.pagination);
 }
 function resolveOptionConfig(field) {
   if (!createFormFieldInstance(field).capability.has("options")) {
@@ -435,6 +438,9 @@ function trackContextAccess(ctx, contextKeys) {
     }
   });
 }
+function isDisabledQueryOptions(source) {
+  return Object.getOwnPropertyDescriptor(source, "enabled")?.value === false;
+}
 function isRuntimeQueryOptions(value) {
   if (!isRecord(value)) {
     return false;

package/dist/runtime/form/composables/use-remote-field-options.js

@@ -139,7 +139,7 @@ export function useRemoteFieldOptions(params) {
     sourceFetching.value = true;
     try {
       const result = await resolveRemoteResult(
-        config.source({
+        config.load({
           ...params.callbackParams.value,
           page: { cursor: page.cursor, index: page.index, size: pageSize.value },
           search: search.value
@@ -310,7 +310,7 @@ export function useRemoteFieldOptions(params) {
   async function loadChildrenPage(config, option, key, domain) {
     try {
       const result = await resolveRemoteResult(
-        config.source({
+        config.load({
           ...params.callbackParams.value,
           page: { cursor: null, index: 1, size: pageSize.value },
           parent: rawOptions.get(key) ?? option,
@@ -395,10 +395,10 @@ export function useRemoteFieldOptions(params) {
     () => {
       const config = params.config.value;
       const { deps } = params.callbackParams.value;
-      if (!config?.refreshOn?.length || !isRecord(deps)) {
+      if (!config?.refreshOn?.length) {
         return [];
       }
-      return config.refreshOn.map((alias) => deps[alias]);
+      return config.refreshOn.map((alias) => deps.get(alias));
     },
     (next, previous) => {
       if (isUndefined(previous) || sameValues(next, previous)) {

package/dist/runtime/form/fields/array-list/use-array-items.d.ts

@@ -7,7 +7,7 @@ export declare function isArrayActionConfig(action: FormArrayAction | undefined)
 export declare function useFormArrayItems(field: () => FormArrayItemsField, path: () => readonly string[]): {
     actionParams: (index: number) => {
         ctx: {};
-        deps: Readonly<import("../../../shared/index.js").GenericObject>;
+        deps: import("../../types/index.js").FormDependencies;
         getOptions: (key: string) => readonly unknown[];
         getValue: (key: string) => unknown;
         index: number;

package/dist/runtime/form/fields/auto-complete/component.vue

@@ -77,7 +77,7 @@ async function handleCreate(label) {
   await options.create(label);
 }
 async function handleCreateAction() {
-  await handleCreate(searchTerm.value);
+  await options.create(searchTerm.value.trim() || void 0);
 }
 async function handleNativeCreate(label) {
   const normalizedLabel = label.trim();

package/dist/runtime/form/fields/select/component.vue

@@ -85,7 +85,7 @@ async function handleCreate(label) {
   await options.create(label);
 }
 async function handleCreateAction() {
-  await handleCreate(searchTerm.value);
+  await options.create(searchTerm.value.trim() || void 0);
 }
 async function handleNativeCreate(label) {
   const normalizedLabel = label.trim();

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

@@ -16,7 +16,7 @@ import type { FormContextData, FormContextDefinition, FormPageSchema, FormPageSc
  *         label: 'VTEST ID',
  *         // `accountType` belongs to another section: a page is one form, one state.
  *         dependencies: ['accountType'],
- *         required: ({ deps }) => hasActiveContract || 'accountType' in deps,
+ *         required: ({ deps }) => hasActiveContract || deps.get('accountType') !== null,
  *       },
  *     ],
  *   })

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

@@ -86,8 +86,11 @@ export interface FormFieldOptionsApi<TOption = FormValue> {
     error: () => FormValue | 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>;
+    /**
+     * Creates a new option when the field configured an option creation handler. A blank typed label
+     * creates nothing; calling it without a label runs the handler with an empty one.
+     */
+    create: (label?: string) => Promise<TOption | null>;
     /** Returns hydrated options for the current selection, including values outside loaded pages. */
     selected: () => readonly TOption[];
     /** True when the field loads options remotely. */

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

@@ -1,18 +1,30 @@
 import type { FormValue } from './/index.js';
 import type { FormFieldApi } from './api.js';
-import type { FormObject } from './utils.js';
 /**
- * Dependency values a field callback reads: each declared dependency under its target name, typed
- * `FormValue` until the callback narrows it, since a reusable field can be mounted anywhere.
+ * The dependencies a field callback reads, each under the target name its `dependencies` entry
+ * declares.
+ *
+ * @example
+ * ```ts
+ * dependencies: ['year', ['profile.country', 'country']],
+ * options: ({ deps }) => ratesFor(deps.get<number | null>('year'), deps.get<string>('country')),
+ * ```
  */
-export type FormDependencyValues = Readonly<FormObject>;
+export interface FormDependencies {
+    /**
+     * Reads the dependency declared under `key`, typed as the caller states. The engine does not
+     * check the type, since a reusable field can be mounted anywhere; a key the field did not declare
+     * reads as `undefined`.
+     */
+    get: <TValue = FormValue>(key: string) => TValue;
+}
 /**
  * Parameters passed to field-level callbacks.
  */
-export interface FormFieldCallbackParams<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> {
+export interface FormFieldCallbackParams<TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue, TOption = FormValue> {
     /** Fully typed form-scoped context declared on the schema. */
     ctx: TContext;
-    /** Values read from the field's dependency list. */
+    /** The field's declared dependencies, read with `deps.get(key)`. */
     deps: TDeps;
     /** Field-level API for values, options, upload work, and validation. */
     api: FormFieldApi<TValue, TOption, TContext>;
@@ -20,4 +32,4 @@ export interface FormFieldCallbackParams<TContext = NonNullable<unknown>, TDeps
 /**
  * Function receiving field callback parameters.
  */
-export type FormFieldCallback<TResult, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> = (params: FormFieldCallbackParams<TContext, TDeps, TValue, TOption>) => TResult;
+export type FormFieldCallback<TResult, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue, TOption = FormValue> = (params: FormFieldCallbackParams<TContext, TDeps, TValue, TOption>) => TResult;

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

@@ -7,7 +7,8 @@ type PathValue<TSource, TPath extends string> = TPath extends '$root' ? TSource
 type DependencyObject<TDependency, TState> = DependencyTarget<TDependency> extends infer TTarget ? TTarget extends string ? PathToObject<TTarget, PathValue<TState, DependencySource<TDependency>>> : NonNullable<unknown> : NonNullable<unknown>;
 type DependenciesValue<TDependencies, TState> = TDependencies extends readonly FormValue[] ? UnionToIntersection<DependencyObject<TDependencies[number], TState>> : NonNullable<unknown>;
 /**
- * Extracts the `deps` object made available to callbacks for a single field.
+ * Extracts the values of a single field's declared dependencies, keyed by target name: the types a
+ * callback reads through `deps.get(key)`.
  *
  * 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
@@ -20,6 +21,7 @@ type DependenciesValue<TDependencies, TState> = TDependencies extends readonly F
  *   dependencies: ['password', ['profile.country', 'country']]
  * }, State>
  * // { password: string | null, country: 'FR' | 'BE' | null }
+ * deps.get<Deps['country']>('country')
  * ```
  */
 export type ExtractFormFieldDependencies<TField, TState = FormObject> = TField extends {

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

@@ -1,6 +1,6 @@
 import type { FormValue } from './/index.js';
 import type { FormFieldApi } from './api.js';
-import type { FormDependencyValues, FormFieldCallback } from './callbacks.js';
+import type { FormDependencies, FormFieldCallback } from './callbacks.js';
 import type { FormField } from './field.js';
 import type { FormContainerLayout, FormItemLayout } from './layout.js';
 import type { FormTransformConfig } from './transform.js';
@@ -19,11 +19,11 @@ export interface FormFieldDescription {
 /**
  * Common stateful field properties.
  */
-export type FormFieldProps<TProps = FormObject, TContext = NonNullable<unknown>, TDeps = FormDependencyValues> = FormDynamic<TProps & FormObject, {
+export type FormFieldProps<TProps = FormObject, TContext = NonNullable<unknown>, TDeps = FormDependencies> = FormDynamic<TProps & FormObject, {
     ctx: TContext;
     deps: TDeps;
 }>;
-export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TProps = FormObject> {
+export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TContext = NonNullable<unknown>, TDeps = FormDependencies, TProps = FormObject> {
     /** Raw path used to read/write the field value in form state. */
     key: string;
     /** Discriminant used by the field registry. */
@@ -101,7 +101,7 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
 /**
  * Base properties for stateless visual fields.
  */
-export interface FormStatelessFieldBase<TType extends FormFieldType, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TProps = FormObject> {
+export interface FormStatelessFieldBase<TType extends FormFieldType, TContext = NonNullable<unknown>, TDeps = FormDependencies, TProps = FormObject> {
     /** Stable key for renderer identity. Stateless fields do not write form state. */
     key: string;
     /** Discriminant used by the field registry. */
@@ -118,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 = NonNullable<unknown>, TDeps = FormDependencyValues, TProps = FormObject> {
+export interface FormContainerFieldBase<TType extends FormFieldType, TContext = NonNullable<unknown>, TDeps = FormDependencies, TProps = FormObject> {
     /** Stable renderer key. */
     key: string;
     /** Discriminant used by the field registry. */

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

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

@@ -49,5 +49,6 @@ export interface FormOptionRuntimeState {
     /** Loads the direct children of a remote tree option. */
     loadChildren: (option: ResolvedFormOption) => Promise<void>;
     add: (option: FormValue) => void;
-    create: (label: string) => Promise<ResolvedFormOption | null>;
+    /** Creates an option; a blank typed label creates nothing, and no label runs the handler with an empty one. */
+    create: (label?: string) => Promise<ResolvedFormOption | null>;
 }

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

@@ -1,7 +1,7 @@
 import type { QueryKey } from '@tanstack/vue-query';
 import type { RemoteOptionsLoader, RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { FormValue } from './/index.js';
-import type { FormDependencyValues, FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
+import type { FormDependencies, FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
 import type { FormMaybePromise, FormText } from './utils.js';
 /**
@@ -28,15 +28,18 @@ export type FormOptionItem<TValue extends FormOptionValue = FormOptionValue> = T
 /**
  * A static, sync-derived, promise-backed, or TanStack Query-backed option source.
  */
-export type FormOptionsSource<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> = readonly TOption[] | FormQueryOptions<readonly TOption[]> | FormFieldCallback<readonly TOption[] | Promise<readonly TOption[]> | FormQueryOptions<readonly TOption[]>, TContext, TDeps, TValue, TOption>;
+export type FormOptionsSource<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue> = readonly TOption[] | FormQueryOptions<readonly TOption[]> | FormFieldCallback<readonly TOption[] | Promise<readonly TOption[]> | FormQueryOptions<readonly TOption[]>, TContext, TDeps, TValue, TOption>;
 /**
  * Option creation hook for fields that can create a missing option from user input.
  */
-export interface FormCreateOptionParams<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
-    /** User-entered label that should be converted into a concrete option. */
+export interface FormCreateOptionParams<TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+    /**
+     * User-entered label that should be converted into a concrete option. Empty when the explicit
+     * create action runs without a search term, such as a creator that opens its own form.
+     */
     label: string;
 }
-export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
+export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue> {
     /** Label shown by the create affordance. */
     label?: FormText;
     /** Selects the newly-created option immediately. Defaults to `true`. */
@@ -46,14 +49,14 @@ export interface FormCreateOption<TOption, TContext = NonNullable<unknown>, TDep
     /** Creates an option and returns it. Return `null` when creation was cancelled. */
     handler: (params: FormCreateOptionParams<TContext, TDeps, TValue, TOption>) => FormMaybePromise<TOption | null>;
 }
-export interface FormOptionsChangeParams<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormOptionsChangeParams<TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Previously resolved normalized options. */
     previousOptions: readonly TOption[];
 }
 /**
  * Shared option configuration for option-based fields.
  */
-export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
+export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, 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. */
@@ -73,7 +76,7 @@ export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDep
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
-export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = FormDependencies, 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. */
@@ -81,7 +84,7 @@ export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps
     /** Parent option whose direct children are requested. Undefined for root pages. */
     parent?: NoInfer<TOption>;
 }
-export interface FormRemoteSelectedRequest<TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
+export interface FormRemoteSelectedRequest<TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Selected values that are not present in the loaded pages. */
     values: readonly FormOptionValue[];
 }
@@ -89,10 +92,13 @@ export type FormRemoteSource<TResult> = FormQueryOptions<TResult> | Promise<TRes
 /**
  * Remote option configuration: server-side search, pagination, and selected-value hydration.
  */
-export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> {
+export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue> {
     mode: 'remote';
-    /** Loads one page of options for the current search, page, and optional parent. */
-    source: (request: FormRemoteOptionsRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<RemoteOptionsResult<TOption>>;
+    /**
+     * Loads one page of options for the current search, page, and optional parent. Named apart from
+     * a local config's `source` so an object-form local source keeps typed callback parameters.
+     */
+    load: (request: FormRemoteOptionsRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<RemoteOptionsResult<TOption>>;
     /** Hydrates selected values that the loaded pages do not contain. */
     resolveSelected?: (request: FormRemoteSelectedRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<readonly TOption[]>;
     pagination: RemoteOptionsPagination;
@@ -118,13 +124,13 @@ export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>
     disableOnLoading?: boolean;
 }
 /** Reuses one remote loader while keeping field-specific refresh and creation behavior local. */
-export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> extends Omit<FormRemoteOptionConfig<TOption, TContext, TDeps, TValue>, 'source' | 'resolveSelected' | 'pagination' | 'search' | 'queryKeyFor' | 'selectedQueryKeyFor'> {
+export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue> extends Omit<FormRemoteOptionConfig<TOption, TContext, TDeps, TValue>, 'load' | 'resolveSelected' | 'pagination' | 'search' | 'queryKeyFor' | 'selectedQueryKeyFor'> {
     loader: RemoteOptionsLoader<TOption>;
-    source?: never;
+    load?: never;
     resolveSelected?: never;
     pagination?: never;
     search?: never;
     queryKeyFor?: never;
     selectedQueryKeyFor?: never;
 }
-export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencyValues, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteLoaderOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;
+export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = FormDependencies, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteLoaderOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;

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

@@ -1,7 +1,7 @@
 import type { RegleRuleRaw } from '@regle/core';
 import type { FormValue } from './/index.js';
 import type { FormFieldCallback } from './callbacks.js';
-import type { FormObject, FormText } from './utils.js';
+import type { FormText } from './utils.js';
 /**
  * Controls when a field starts running validation while the user edits it.
  *
@@ -52,4 +52,4 @@ export interface FormValidationConfig<TValue = FormValue, TContext = NonNullable
 /** Native Regle rules keyed by their validation name. */
 export type FormValidators = Record<string, RegleRuleRaw>;
 /** Static or dependency-aware native Regle rules for one field. */
-export type FormValidatorsConfig<TContext = NonNullable<unknown>> = FormValidators | FormFieldCallback<FormValidators, TContext, FormObject>;
+export type FormValidatorsConfig<TContext = NonNullable<unknown>> = FormValidators | FormFieldCallback<FormValidators, TContext>;

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

@@ -1,6 +1,17 @@
-import type { FormField, FormObject } from '../types/index.js';
+import type { FormDependencies, FormField, FormObject } from '../types/index.js';
+/**
+ * Resolves a field's declared dependencies against the form state, each under its target name.
+ */
 export declare function resolveFieldDependencies(params: {
     field: FormField;
     state: FormObject;
     parentPath: readonly string[];
-}): import("../../shared/index.js").GenericObject;
+}): FormDependencies;
+/**
+ * Wraps resolved dependency values in the reader field callbacks receive.
+ */
+export declare function createFormDependencies(values: FormObject): FormDependencies;
+/**
+ * The plain values behind a dependency reader, for the engine's own change detection.
+ */
+export declare function readFormDependencyValues(dependencies: FormDependencies): import("../../shared/index.js").GenericObject;

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

@@ -1,23 +1,35 @@
 import { getScopedPathValue } from "./path.js";
 import { isString } from "./predicate.js";
+const dependencyValues = /* @__PURE__ */ new WeakMap();
 export function resolveFieldDependencies(params) {
-  const output = {};
+  const values = {};
   const dependencies = Object.getOwnPropertyDescriptor(params.field, "dependencies")?.value;
-  if (!Array.isArray(dependencies)) {
-    return output;
-  }
-  for (const dependency of dependencies) {
-    const normalized = normalizeFieldDependency(dependency);
-    if (!normalized) {
-      continue;
+  if (Array.isArray(dependencies)) {
+    for (const dependency of dependencies) {
+      const normalized = normalizeFieldDependency(dependency);
+      if (!normalized) {
+        continue;
+      }
+      values[normalized.target] = getScopedPathValue(
+        params.state,
+        normalized.source,
+        params.parentPath
+      );
     }
-    output[normalized.target] = getScopedPathValue(
-      params.state,
-      normalized.source,
-      params.parentPath
-    );
   }
-  return output;
+  return createFormDependencies(values);
+}
+export function createFormDependencies(values) {
+  const dependencies = {
+    // SAFETY: the callback states the type it expects from a dependency it declared; the engine
+    // holds untyped form values and does not validate them, as the `get` contract documents.
+    get: (key) => values[key]
+  };
+  dependencyValues.set(dependencies, values);
+  return dependencies;
+}
+export function readFormDependencyValues(dependencies) {
+  return dependencyValues.get(dependencies) ?? {};
 }
 function normalizeFieldDependency(value) {
   if (isString(value)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",