nuxt-ui-tools 1.8.1 → 1.10.0

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.8.1",
+  "version": "1.10.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/dashboard/components/dashboard-stat.vue

@@ -6,6 +6,7 @@ import { useUiToolsLocale } from "#ui-tools/i18n";
 import { isNumber, isString } from "#ui-tools/shared/utils/predicate";
 import { resolveTextValue } from "#ui-tools/shared/utils/render";
 import { DASHBOARD_MISSING_VALUE, useDashboardFormat } from "../composables/use-dashboard-format";
+import { countedFigure, tweenTarget, useDashboardTween } from "../composables/use-dashboard-tween";
 import { useDashboardUi } from "../composables/use-dashboard-ui";
 import { resolveDashboardColor } from "../utils/charts";
 import { resolveDashboardSparkBars, resolveDashboardSparkline } from "../utils/sparkline";
@@ -73,11 +74,12 @@ const ready = computed(() => {
 });
 const resolved = computed(() => ready.value ? value(ready.value.data) : void 0);
 const formatValue = computed(() => formats.resolve(format));
+const counted = useDashboardTween(() => [tweenTarget(resolved.value)]);
 const display = computed(() => {
   if (!ready.value) return "";
   const shown = resolved.value;
   if (shown === null || shown === void 0) return DASHBOARD_MISSING_VALUE;
-  return isNumber(shown) ? formatValue.value(shown) : resolveTextValue(shown);
+  return isNumber(shown) ? formatValue.value(countedFigure(shown, counted.value[0])) : resolveTextValue(shown);
 });
 const previous = computed(() => {
   if (!ready.value || !compare) return null;
@@ -201,7 +203,7 @@ const extra = computed(() => trend ? "trend" : goal ? "goal" : void 0);
     </template>
 
     <template v-if="ready">
-      <div :class="classes.value">
+      <div :class="classes.value" data-stat-value>
         <slot name="value" :data="ready.data" :value="display">{{ display }}</slot>
       </div>
       <div v-if="change || captionText || $slots.caption" :class="classes.meta">

package/dist/runtime/dashboard/components/dashboard-stats.vue

@@ -6,6 +6,7 @@ import { useResponsiveValue } from "#ui-tools/shared/composables/use-responsive-
 import { isNumber, isString } from "#ui-tools/shared/utils/predicate";
 import { resolveTextValue } from "#ui-tools/shared/utils/render";
 import { useDashboardFormat } from "../composables/use-dashboard-format";
+import { countedFigure, tweenTarget, useDashboardTween } from "../composables/use-dashboard-tween";
 import { useDashboardUi } from "../composables/use-dashboard-ui";
 import { resolveDashboardColor } from "../utils/charts";
 import { toDashboardCell } from "../utils/export";
@@ -100,6 +101,14 @@ const entries = computed(() => {
     };
   });
 });
+const counted = useDashboardTween(
+  () => items.map((_item, index) => tweenTarget(entries.value[index]?.raw))
+);
+const shown = computed(
+  () => entries.value.map(
+    (entry, index) => isNumber(entry.raw) ? formats.resolve(items[index]?.format)(countedFigure(entry.raw, counted.value[index])) : entry.value
+  )
+);
 function tabulate() {
   const hasDelta = items.some((item) => item.delta);
   return {
@@ -142,7 +151,7 @@ function tabulate() {
     </template>
 
     <div :class="classes.grid" :style="gridColumns ?? void 0" :data-variant="variant">
-      <div v-for="entry in entries" :key="entry.key" :class="classes.item" data-stats-item>
+      <div v-for="(entry, index) in entries" :key="entry.key" :class="classes.item" data-stats-item>
         <div class="flex min-w-0 items-center gap-2">
           <span
             v-if="entry.icon"
@@ -157,7 +166,7 @@ function tabulate() {
           <span :class="classes.label">{{ entry.label }}</span>
         </div>
         <div :class="classes.value">
-          <span class="truncate">{{ entry.value }}</span>
+          <span class="truncate">{{ shown[index] }}</span>
           <span
             v-if="entry.status"
             :class="classes.status"

package/dist/runtime/dashboard/composables/use-dashboard-tween.d.ts

@@ -0,0 +1,16 @@
+import type { MaybeRefOrGetter } from 'vue';
+/** How long a figure takes to count toward a new value. */
+export declare const DASHBOARD_TWEEN_DURATION = 700;
+/**
+ * Counts figures toward their new values instead of jumping to them: on the first load, a filter
+ * change, or a refresh. Keep the list the same length between updates, since each position counts
+ * from its previous value. Figures change at once when the user prefers reduced motion.
+ */
+export declare function useDashboardTween(figures: MaybeRefOrGetter<number[]>): import("vue").ComputedRef<number[]>;
+/**
+ * The figure to show while counting toward `target`. Whole numbers count through whole numbers, so
+ * a count never reads "12.3" on its way to 21; values that cannot be counted show as they are.
+ */
+export declare function countedFigure(target: number, current: number | undefined): number;
+/** A figure a tween can count toward: finite numbers, and zero for anything else. */
+export declare function tweenTarget(value: unknown): number;

package/dist/runtime/dashboard/composables/use-dashboard-tween.js

@@ -0,0 +1,20 @@
+import { TransitionPresets, usePreferredReducedMotion, useTransition } from "@vueuse/core";
+import { computed } from "vue";
+import { isNumber } from "../../shared/utils/predicate.js";
+export const DASHBOARD_TWEEN_DURATION = 700;
+export function useDashboardTween(figures) {
+  const reducedMotion = usePreferredReducedMotion();
+  return useTransition(figures, {
+    disabled: computed(() => reducedMotion.value === "reduce"),
+    duration: DASHBOARD_TWEEN_DURATION,
+    transition: TransitionPresets.easeOutCubic
+  });
+}
+export function countedFigure(target, current) {
+  if (!Number.isFinite(target)) return target;
+  const shown = current !== void 0 && Number.isFinite(current) ? current : target;
+  return Number.isInteger(target) ? Math.round(shown) : shown;
+}
+export function tweenTarget(value) {
+  return isNumber(value) && Number.isFinite(value) ? value : 0;
+}

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

@@ -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.js

@@ -64,6 +64,9 @@ export function useFieldOptions(params) {
     () => contextResources.value.find((resource) => resource.error !== null)?.error ?? null
   );
   const optionConfig = computed(() => resolveOptionConfig(params.field()));
+  const declaresOptions = computed(
+    () => createFormFieldInstance(params.field()).capability.has("options") && !isUndefined(Object.getOwnPropertyDescriptor(params.field(), "options")?.value)
+  );
   const querySource = computed(() => {
     const source = resolvedSource.value;
     return isRuntimeQueryOptions(source) ? source : null;
@@ -303,13 +306,10 @@ export function useFieldOptions(params) {
     params.api.value.value.set([...selected, value]);
   }
   function clearInvalidValue(options) {
-    if (!optionConfig.value || remoteConfig.value) {
-      return;
-    }
-    if (pending.value) {
+    if (remoteConfig.value || pending.value || error.value !== null) {
       return;
     }
-    if (optionConfig.value?.clearOnInvalid === false) {
+    if (!declaresOptions.value || optionConfig.value?.clearOnInvalid === false) {
       return;
     }
     const current = params.api.value.value.get();
@@ -359,7 +359,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 +372,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")) {

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/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/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.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,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 = 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> {
+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. */
     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 +46,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. */
@@ -62,14 +62,18 @@ export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDep
     create?: FormCreateOption<TOption, TContext, TDeps, TValue>;
     /** Enables the field-level refresh affordance. Matches shared-ui `allowOptionsRefresh`. */
     allowOptionsRefresh?: boolean;
-    /** Clears current values that no longer exist in resolved options. Defaults to `true`. */
+    /**
+     * Clears current values that no longer exist in resolved options. Defaults to `true`, which
+     * shorthand sources (arrays, functions, promises, query options) always use. Values are kept
+     * while the source is pending or failed.
+     */
     clearOnInvalid?: boolean;
     /** Runs when resolved source options change, excluding locally-created options. */
     onOptionsChange?: (options: readonly TOption[], params: FormOptionsChangeParams<TContext, TDeps, TValue, TOption>) => void;
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
-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. */
@@ -77,7 +81,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[];
 }
@@ -85,10 +89,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;
@@ -114,13 +121,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.8.1",
+  "version": "1.10.0",
   "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",