nuxt-ui-tools 0.1.0

package/dist/runtime/form/components/renderer/FormFieldShell.vue.d.ts

@@ -0,0 +1,38 @@
+import type { FormField } from '../../types/index.js';
+type __VLS_Props = {
+    field: FormField;
+    path: readonly string[];
+    inlineLabel?: boolean;
+};
+declare var __VLS_1: {
+    label: string | undefined;
+    description: string | undefined;
+    hint: string | undefined;
+    required: boolean;
+}, __VLS_23: {
+    label: string | undefined;
+    description: string | undefined;
+    hint: string | undefined;
+    required: boolean;
+}, __VLS_32: {
+    label: string | undefined;
+    description: string | undefined;
+    hint: string | undefined;
+    required: boolean;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_23) => any;
+} & {
+    default?: (props: typeof __VLS_32) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/form/components/root/Form.d.vue.ts

@@ -0,0 +1,42 @@
+import type { FormObject, FormRendererController, FormRenderShell, FormUiConfig } from '../../types/index.js';
+import type { FormValidationMode } from '../../types/index.js';
+type __VLS_Props = {
+    form?: FormRendererController;
+    schema?: unknown;
+    input?: FormObject;
+    shell?: FormRenderShell;
+    syncInput?: boolean | readonly string[];
+    validate?: FormValidationMode;
+    showCloseButton?: boolean;
+    ui?: FormUiConfig;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    state: import("vue").ComputedRef<import("../../../shared/index.js").GenericObject>;
+    output: import("vue").ComputedRef<import("../../../shared/index.js").GenericObject>;
+    dirtyPaths: import("vue").ComputedRef<readonly string[]>;
+    isDirty: import("vue").ComputedRef<boolean>;
+    errors: import("vue").ComputedRef<readonly import("../../types/index.js").FormValidationError[]>;
+    actionPending: import("vue").ComputedRef<import("../../types/index.js").FormSubmitAction | null>;
+    validate: (options?: import("../../types/index.js").FormValidationOptions) => Promise<boolean>;
+    focus: (path: string | readonly string[]) => Promise<boolean>;
+    focusFirstInvalid: () => Promise<boolean>;
+    submit: () => Promise<boolean>;
+    submitHandler: (submitHandler?: import("../../types/index.js").FormSubmitHandler<FormObject>) => Promise<import("../../types/index.js").FormSubmitHandlerResult>;
+    reset: () => void;
+    nextStep: () => Promise<boolean>;
+    previousStep: () => Promise<boolean>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    cancel: (value: import("../../../shared/index.js").GenericObject) => any;
+    submit: (value: import("../../../shared/index.js").GenericObject, result: {
+        success: boolean;
+        data?: unknown;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCancel?: ((value: import("../../../shared/index.js").GenericObject) => any) | undefined;
+    onSubmit?: ((value: import("../../../shared/index.js").GenericObject, result: {
+        success: boolean;
+        data?: unknown;
+    }) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/form/components/root/Form.vue

@@ -0,0 +1,310 @@
+<script setup>
+import UBadge from "@nuxt/ui/components/Badge.vue";
+import UButton from "@nuxt/ui/components/Button.vue";
+import USkeleton from "@nuxt/ui/components/Skeleton.vue";
+import { useAppConfig } from "nuxt/app";
+import { computed, nextTick, onBeforeUnmount, onMounted, watch } from "vue";
+import { onBeforeRouteLeave } from "vue-router";
+import { useFormActions } from "../../composables/use-form-actions";
+import { useFormGridLayout } from "../../composables/use-form-layout";
+import { provideFormRuntime, useFormRuntime } from "../../composables/use-form-runtime";
+import { provideFormUi } from "../../composables/use-form-ui";
+import { isRecord } from "../../utils/path";
+import { getSchemaSteps } from "../../utils/state";
+import { resolveFormText } from "../../utils/text";
+import { mergeFormUi, mergeFormUiClass, resolveAppFormUi } from "../../utils/ui";
+import FormActions from "../actions/FormActions.vue";
+import FormFieldRenderer from "../renderer/FormFieldRenderer.vue";
+const props = defineProps({
+  form: { type: Object, required: false },
+  schema: { type: null, required: false },
+  input: { type: Object, required: false },
+  shell: { type: String, required: false },
+  syncInput: { type: [Boolean, Array], required: false },
+  validate: { type: [Boolean, String], required: false },
+  showCloseButton: { type: Boolean, required: false },
+  ui: { type: Object, required: false }
+});
+const emit = defineEmits(["submit", "cancel"]);
+const schemaRef = computed(() => props.form?.schema.value ?? props.schema ?? {});
+const appConfig = useAppConfig();
+const formUi = provideFormUi(
+  computed(
+    () => mergeFormUi(resolveAppFormUi(appConfig), getSchemaUi(schemaRef.value), props.ui)
+  )
+);
+const inputRef = computed(() => props.form?.input.value ?? props.input);
+const syncInputRef = computed(
+  () => props.form?.syncInput.value ?? props.syncInput ?? getSchemaSyncInput(schemaRef.value)
+);
+const validationModeRef = computed(
+  () => props.form?.validationMode.value ?? props.validate ?? getSchemaValidationMode(schemaRef.value)
+);
+const runtime = useFormRuntime({
+  schema: schemaRef,
+  input: inputRef,
+  syncInput: syncInputRef,
+  validationMode: validationModeRef
+});
+provideFormRuntime(runtime);
+watch(
+  () => props.form,
+  (controller, previousController) => {
+    previousController?.unbind(runtime);
+    controller?.bind(runtime);
+  },
+  { immediate: true }
+);
+onBeforeUnmount(() => props.form?.unbind(runtime));
+onMounted(async () => {
+  await nextTick();
+  const target = getSchemaAutoFocus(schemaRef.value);
+  if (typeof target === "string") {
+    await runtime.focusField(target);
+    return;
+  }
+  if (target === true) await focusFirstRenderedField();
+});
+if (typeof window !== "undefined") {
+  const handleBeforeUnload = (event) => {
+    if (!shouldConfirmDirtyNavigation()) return;
+    event.preventDefault();
+    event.returnValue = "";
+  };
+  window.addEventListener("beforeunload", handleBeforeUnload);
+  onBeforeUnmount(() => window.removeEventListener("beforeunload", handleBeforeUnload));
+}
+onBeforeRouteLeave(() => {
+  if (!shouldConfirmDirtyNavigation()) return true;
+  return window.confirm(getDirtyNavigationMessage());
+});
+const currentStep = computed(() => getSchemaSteps(schemaRef.value)[runtime.currentStepIndex.value]);
+const parentPath = computed(
+  () => runtime.currentStepRoot.value ? [runtime.currentStepRoot.value] : []
+);
+const title = computed(() => resolveFormText(getSchemaTitle(schemaRef.value)));
+const showStepper = computed(() => getSchemaShowStepper(schemaRef.value));
+const grid = useFormGridLayout({ layout: runtime.currentLayout });
+const shell = computed(() => props.shell ?? "inline");
+const isOverlayShell = computed(
+  () => shell.value === "drawer" || shell.value === "modal" || shell.value === "fullscreen"
+);
+const rootClass = computed(
+  () => mergeFormUiClass(
+    isOverlayShell.value ? "flex h-full min-h-0 flex-col" : "grid gap-5",
+    formUi.ui.value.root?.ui?.root
+  )
+);
+const headerClass = computed(
+  () => mergeFormUiClass(
+    isOverlayShell.value ? "shrink-0 border-b border-default bg-default px-5 py-4" : "grid gap-3",
+    formUi.ui.value.root?.ui?.header
+  )
+);
+const viewportClass = computed(
+  () => mergeFormUiClass(
+    isOverlayShell.value ? "min-h-0 flex-1 overflow-y-auto px-5 py-5" : "",
+    formUi.ui.value.root?.ui?.viewport
+  )
+);
+const footerClass = computed(
+  () => mergeFormUiClass(
+    isOverlayShell.value ? "flex shrink-0 items-center justify-between gap-3 border-t border-default bg-default px-5 py-4" : "flex items-center justify-between gap-3 border-t border-default pt-4",
+    formUi.ui.value.root?.ui?.footer
+  )
+);
+const actions = useFormActions({ runtime, shell });
+const contextPending = computed(
+  () => Object.values(runtime.context).some(
+    (resource) => "pending" in resource && resource.pending && typeof resource.value === "undefined"
+  )
+);
+async function submit() {
+  if (props.form) {
+    const result2 = await props.form.submitHandler();
+    if (result2.success) emit("submit", runtime.output.value, result2);
+    return;
+  }
+  const result = await runtime.submitHandler();
+  if (result.success) emit("submit", runtime.output.value, result);
+}
+function cancel() {
+  if (shouldConfirmDirtyNavigation() && !window.confirm(getDirtyNavigationMessage())) return;
+  emit("cancel", runtime.output.value);
+}
+defineExpose({
+  state: computed(() => runtime.state),
+  output: runtime.output,
+  dirtyPaths: runtime.dirtyPaths,
+  isDirty: runtime.isDirty,
+  errors: runtime.errors,
+  actionPending: runtime.actionPending,
+  validate: runtime.validate,
+  focus: runtime.focusField,
+  focusFirstInvalid: runtime.focusFirstInvalid,
+  submit: runtime.submit,
+  submitHandler: runtime.submitHandler,
+  reset: runtime.reset,
+  nextStep: runtime.nextStep,
+  previousStep: runtime.previousStep
+});
+function stepLabel(index) {
+  return runtime.steps.value[index]?.label ?? `Step ${index + 1}`;
+}
+function getSchemaTitle(schema) {
+  if (!isRecord(schema)) return void 0;
+  const value = Object.getOwnPropertyDescriptor(schema, "title")?.value;
+  return typeof value === "string" || typeof value === "number" || typeof value === "function" ? value : void 0;
+}
+function getSchemaUi(schema) {
+  if (!isRecord(schema)) return void 0;
+  const value = Object.getOwnPropertyDescriptor(schema, "ui")?.value;
+  return isRecord(value) ? value : void 0;
+}
+function getSchemaShowStepper(schema) {
+  if (!isRecord(schema)) return true;
+  const value = Object.getOwnPropertyDescriptor(schema, "showStepper")?.value;
+  return value !== false;
+}
+function getSchemaSyncInput(schema) {
+  const controls = getSchemaControls(schema);
+  const value = controls ? Object.getOwnPropertyDescriptor(controls, "syncInput")?.value : void 0;
+  if (typeof value === "boolean") return value;
+  return Array.isArray(value) ? value.filter((path) => typeof path === "string") : false;
+}
+function getSchemaValidationMode(schema) {
+  const controls = getSchemaControls(schema);
+  const value = controls ? Object.getOwnPropertyDescriptor(controls, "validate")?.value : void 0;
+  return value === false || value === "required" || value === "rules" ? value : true;
+}
+function getSchemaControls(schema) {
+  if (!isRecord(schema)) return void 0;
+  const controls = Object.getOwnPropertyDescriptor(schema, "controls")?.value;
+  return isRecord(controls) ? controls : void 0;
+}
+function getSchemaAutoFocus(schema) {
+  const controls = getSchemaControls(schema);
+  const value = controls ? Object.getOwnPropertyDescriptor(controls, "autoFocus")?.value : void 0;
+  return typeof value === "string" || typeof value === "boolean" ? value : false;
+}
+function dirtyNavigationConfig() {
+  const controls = getSchemaControls(schemaRef.value);
+  return controls ? Object.getOwnPropertyDescriptor(controls, "confirmNavOnDirty")?.value : void 0;
+}
+function shouldConfirmDirtyNavigation() {
+  if (!runtime.isDirty.value) return false;
+  const config = dirtyNavigationConfig();
+  if (!config) return false;
+  if (!isRecord(config)) return config === true;
+  const ignored = Array.isArray(config.ignorePaths) ? config.ignorePaths.filter((path) => typeof path === "string") : [];
+  return runtime.dirtyPaths.value.some(
+    (path) => !ignored.some((ignoredPath) => path === ignoredPath || path.startsWith(`${ignoredPath}.`))
+  );
+}
+function getDirtyNavigationMessage() {
+  const config = dirtyNavigationConfig();
+  if (!isRecord(config)) return "You have unsaved changes. Close this form?";
+  const message = Object.getOwnPropertyDescriptor(config, "message")?.value;
+  return resolveFormText(message) ?? "You have unsaved changes. Close this form?";
+}
+async function focusFirstRenderedField() {
+  const path = runtime.currentFields.value.map(
+    (field) => `${parentPath.value.join(".")}${parentPath.value.length ? "." : ""}${field.key}`
+  ).find(Boolean);
+  if (path) await runtime.focusField(path);
+}
+</script>
+
+<template>
+  <form :class="rootClass" @submit.prevent="submit">
+    <header v-if="title || runtime.isStepped.value || isOverlayShell" :class="headerClass">
+      <div
+        v-if="title || isOverlayShell"
+        :class="
+  mergeFormUiClass(
+    'flex items-start justify-between gap-4',
+    formUi.ui.value.root?.ui?.headerContent
+  )
+"
+      >
+        <div
+          v-if="title"
+          :class="mergeFormUiClass('grid gap-1', formUi.ui.value.root?.ui?.heading)"
+        >
+          <h2
+            :class="
+  mergeFormUiClass(
+    'text-lg font-semibold text-highlighted',
+    formUi.ui.value.root?.ui?.title
+  )
+"
+          >
+            {{ title }}
+          </h2>
+        </div>
+
+        <UButton
+          v-if="isOverlayShell && showCloseButton !== false"
+          type="button"
+          color="neutral"
+          variant="ghost"
+          :size="formUi.controlSize.value"
+          icon="i-lucide-x"
+          :disabled="runtime.actionPending.value !== null"
+          aria-label="Close form"
+          :class="formUi.ui.value.root?.ui?.close"
+          @click="cancel"
+        />
+      </div>
+
+      <div
+        v-if="runtime.isStepped.value && showStepper"
+        :class="mergeFormUiClass('flex flex-wrap gap-2', formUi.ui.value.root?.ui?.stepper)"
+      >
+        <UBadge
+          v-for="(step, index) in runtime.steps.value"
+          :key="step.key"
+          :color="step.active ? 'primary' : 'neutral'"
+          :variant="step.active ? 'solid' : 'soft'"
+          :class="formUi.ui.value.root?.ui?.step"
+        >
+          {{ stepLabel(index) }}
+        </UBadge>
+      </div>
+    </header>
+
+    <div :class="viewportClass">
+      <div
+        v-if="contextPending"
+        data-form-skeleton
+        :class="formUi.ui.value.root?.ui?.skeleton"
+        :style="grid.style.value"
+      >
+        <div
+          v-for="field in runtime.currentFields.value"
+          :key="field.key"
+          :class="mergeFormUiClass('grid gap-2', formUi.ui.value.root?.ui?.skeletonField)"
+        >
+          <USkeleton
+            :class="mergeFormUiClass('h-4 w-32', formUi.ui.value.root?.ui?.skeletonLabel)"
+          />
+          <USkeleton
+            :class="mergeFormUiClass('h-9 w-full', formUi.ui.value.root?.ui?.skeletonControl)"
+          />
+        </div>
+      </div>
+      <div v-else :class="formUi.ui.value.root?.ui?.grid" :style="grid.style.value">
+        <FormFieldRenderer
+          v-for="field in runtime.currentFields.value"
+          :key="`${parentPath.join('.')}:${field.key}`"
+          :field="field"
+          :parent-path="parentPath"
+        />
+      </div>
+    </div>
+
+    <footer :class="footerClass">
+      <FormActions :runtime="runtime" :actions="actions" @submit="submit" @cancel="cancel" />
+    </footer>
+  </form>
+</template>

package/dist/runtime/form/components/root/Form.vue.d.ts

@@ -0,0 +1,42 @@
+import type { FormObject, FormRendererController, FormRenderShell, FormUiConfig } from '../../types/index.js';
+import type { FormValidationMode } from '../../types/index.js';
+type __VLS_Props = {
+    form?: FormRendererController;
+    schema?: unknown;
+    input?: FormObject;
+    shell?: FormRenderShell;
+    syncInput?: boolean | readonly string[];
+    validate?: FormValidationMode;
+    showCloseButton?: boolean;
+    ui?: FormUiConfig;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {
+    state: import("vue").ComputedRef<import("../../../shared/index.js").GenericObject>;
+    output: import("vue").ComputedRef<import("../../../shared/index.js").GenericObject>;
+    dirtyPaths: import("vue").ComputedRef<readonly string[]>;
+    isDirty: import("vue").ComputedRef<boolean>;
+    errors: import("vue").ComputedRef<readonly import("../../types/index.js").FormValidationError[]>;
+    actionPending: import("vue").ComputedRef<import("../../types/index.js").FormSubmitAction | null>;
+    validate: (options?: import("../../types/index.js").FormValidationOptions) => Promise<boolean>;
+    focus: (path: string | readonly string[]) => Promise<boolean>;
+    focusFirstInvalid: () => Promise<boolean>;
+    submit: () => Promise<boolean>;
+    submitHandler: (submitHandler?: import("../../types/index.js").FormSubmitHandler<FormObject>) => Promise<import("../../types/index.js").FormSubmitHandlerResult>;
+    reset: () => void;
+    nextStep: () => Promise<boolean>;
+    previousStep: () => Promise<boolean>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    cancel: (value: import("../../../shared/index.js").GenericObject) => any;
+    submit: (value: import("../../../shared/index.js").GenericObject, result: {
+        success: boolean;
+        data?: unknown;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onCancel?: ((value: import("../../../shared/index.js").GenericObject) => any) | undefined;
+    onSubmit?: ((value: import("../../../shared/index.js").GenericObject, result: {
+        success: boolean;
+        data?: unknown;
+    }) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

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

@@ -0,0 +1,31 @@
+import type { FormControlSize, FormField } from '../types/index.js';
+export declare function useFieldControl(field: () => FormField, path: () => readonly string[]): {
+    form: import("../types/index.js").FormRuntime;
+    api: import("vue").ComputedRef<import("../types/index.js").FormFieldApi<unknown, unknown, {
+        [x: string]: import("../types/index.js").FormSyncResource<unknown>;
+        [x: number]: import("../types/index.js").FormSyncResource<unknown>;
+        [x: symbol]: import("../types/index.js").FormSyncResource<unknown>;
+    }>>;
+    params: import("vue").ComputedRef<import("../types/index.js").FormFieldCallbackParams<{}, {}, unknown, unknown>>;
+    controlProps: import("vue").ComputedRef<import("../../shared/index.js").GenericObject>;
+    disabled: import("vue").ComputedRef<boolean>;
+    handleBlur: () => Promise<void>;
+    options: {
+        items: import("vue").ComputedRef<readonly import("../utils/options.js").ResolvedFormOption[]>;
+        pending: import("vue").ComputedRef<boolean>;
+        fetching: import("vue").ComputedRef<boolean>;
+        loading: import("vue").ComputedRef<boolean>;
+        creating: import("vue").ComputedRef<boolean>;
+        creatable: import("vue").ComputedRef<boolean>;
+        createLabel: import("vue").ComputedRef<string | undefined>;
+        error: import("vue").ComputedRef<unknown>;
+        disableOnLoading: import("vue").ComputedRef<boolean>;
+        refreshable: import("vue").ComputedRef<boolean>;
+        selectCreatedOption: import("vue").ComputedRef<boolean>;
+        refresh: () => Promise<void>;
+        add: (option: unknown) => void;
+        create: (label: string) => Promise<import("../utils/options.js").ResolvedFormOption | null>;
+    };
+    placeholder: import("vue").ComputedRef<string>;
+    controlSize: import("vue").ComputedRef<FormControlSize>;
+};

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

@@ -0,0 +1,160 @@
+import { debounceFilter, throttleFilter, watchWithFilter } from "@vueuse/core";
+import { computed, onMounted } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import { createFormFieldInstance } from "../utils/field-instance.js";
+import { resolveFormText } from "../utils/text.js";
+import { mergeFormUiClass } from "../utils/ui.js";
+import { useFieldOptions } from "./use-field-options.js";
+import { useFormRuntimeContext } from "./use-form-runtime.js";
+import { useFormUi } from "./use-form-ui.js";
+export function useFieldControl(field, path) {
+  const form = useFormRuntimeContext();
+  const formUi = useFormUi();
+  const { t } = useUiToolsLocale();
+  const api = computed(() => form.getFieldApi(path(), field()));
+  const params = computed(() => form.getFieldCallbackParams(path(), field()));
+  const options = useFieldOptions({
+    field,
+    path,
+    api,
+    callbackParams: params,
+    register: form.registerFieldOptions,
+    refreshFieldOptions: form.refreshFieldOptions
+  });
+  const controlProps = computed(() => {
+    const current = field();
+    const fieldUi = formUi.ui.value.fields?.[current.type];
+    const defaults = {
+      size: fieldUi?.size ?? formUi.controlSize.value,
+      class: fieldUi?.class,
+      ui: mergeControlUi(formUi.ui.value.control?.ui, fieldUi?.ui)
+    };
+    if (!("props" in current)) return defaults;
+    const value = Object.getOwnPropertyDescriptor(current, "props")?.value;
+    if (typeof value === "function") {
+      const result = value(params.value);
+      const resolved2 = typeof result === "object" && result !== null && !Array.isArray(result) ? result : {};
+      return {
+        ...defaults,
+        ...resolved2,
+        class: mergeControlClass(fieldUi?.class, resolved2.class),
+        ui: mergeControlUi(formUi.ui.value.control?.ui, fieldUi?.ui, resolved2.ui)
+      };
+    }
+    const resolved = typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+    return {
+      ...defaults,
+      ...resolved,
+      class: mergeControlClass(fieldUi?.class, resolved.class),
+      ui: mergeControlUi(formUi.ui.value.control?.ui, fieldUi?.ui, resolved.ui)
+    };
+  });
+  const controlSize = computed(() => {
+    const value = controlProps.value.size;
+    return isFormControlSize(value) ? value : formUi.controlSize.value;
+  });
+  const disabled = computed(() => {
+    const current = field();
+    const value = Object.getOwnPropertyDescriptor(current, "disabled")?.value;
+    const disabledByCallback = typeof value === "function" ? value(params.value) === true : false;
+    return disabledByCallback || options.disableOnLoading.value && options.loading.value;
+  });
+  const placeholder = computed(() => {
+    const current = field();
+    const value = Object.getOwnPropertyDescriptor(current, "placeholder")?.value;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "function") {
+      return resolveFormText(value) ?? t("form.fields.text.defaultPlaceholder");
+    }
+    return t("form.fields.text.defaultPlaceholder");
+  });
+  watchWithFilter(
+    () => form.getValue(path()),
+    async () => {
+      if (!createFormFieldInstance(field()).capability.has("validation")) return;
+      const trigger = getValidationTrigger(field());
+      if (trigger === "submit") return;
+      if (trigger === "blur" && !form.isFieldTouched(path())) return;
+      if (trigger === "input") form.markFieldTouched(path());
+      await api.value.validation.validate();
+    },
+    { deep: true }
+  );
+  watchWithFilter(
+    () => form.getValue(path()),
+    (value) => {
+      const effect = Object.getOwnPropertyDescriptor(field(), "watch")?.value;
+      if (typeof effect === "function") effect({ value, api: api.value });
+    },
+    {
+      ...resolveWatchOptions(field()),
+      eventFilter: resolveEffectFilter(field())
+    }
+  );
+  watchWithFilter(
+    () => params.value.deps,
+    () => {
+      const effect = Object.getOwnPropertyDescriptor(field(), "onDependencyChange")?.value;
+      if (typeof effect === "function") void effect(params.value);
+    },
+    { deep: true, eventFilter: resolveEffectFilter(field()) }
+  );
+  onMounted(() => {
+    const effect = Object.getOwnPropertyDescriptor(field(), "onRendered")?.value;
+    if (typeof effect === "function") void effect(params.value);
+  });
+  async function handleBlur() {
+    if (!createFormFieldInstance(field()).capability.has("validation")) return;
+    if (getValidationTrigger(field()) === "submit") return;
+    form.markFieldTouched(path());
+    await api.value.validation.validate();
+  }
+  return {
+    form,
+    api,
+    params,
+    controlProps,
+    disabled,
+    handleBlur,
+    options,
+    placeholder,
+    controlSize
+  };
+}
+function mergeControlUi(...configs) {
+  return configs.reduce((merged, config) => {
+    if (typeof config !== "object" || config === null || Array.isArray(config)) return merged;
+    return { ...merged, ...config };
+  }, {});
+}
+function mergeControlClass(defaults, local) {
+  if (typeof local === "string") return mergeFormUiClass(defaults, local);
+  if (typeof local === "undefined") return defaults;
+  return [defaults, local];
+}
+function isFormControlSize(value) {
+  return value === "xs" || value === "sm" || value === "md" || value === "lg" || value === "xl";
+}
+function resolveWatchOptions(field) {
+  const options = Object.getOwnPropertyDescriptor(field, "watchOptions")?.value;
+  if (typeof options !== "object" || options === null || Array.isArray(options)) return {};
+  return {
+    deep: options.deep === true,
+    immediate: options.immediate === true
+  };
+}
+function resolveEffectFilter(field) {
+  const effect = Object.getOwnPropertyDescriptor(field, "stateEffect")?.value;
+  if (typeof effect !== "object" || effect === null || Array.isArray(effect)) return void 0;
+  const duration = typeof effect.duration === "number" ? effect.duration : 0;
+  if (effect.type === "debounce") return debounceFilter(duration);
+  if (effect.type === "throttle") return throttleFilter(duration);
+  return void 0;
+}
+function getValidationTrigger(field) {
+  if (!createFormFieldInstance(field).capability.has("validation")) return "blur";
+  const validation = Object.getOwnPropertyDescriptor(field, "validation")?.value;
+  if (typeof validation !== "object" || validation === null || Array.isArray(validation))
+    return "blur";
+  const trigger = Object.getOwnPropertyDescriptor(validation, "trigger")?.value;
+  return trigger === "input" || trigger === "submit" ? trigger : "blur";
+}

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

@@ -0,0 +1,26 @@
+import type { ComputedRef } from 'vue';
+import type { FormField, FormFieldApi, FormFieldCallbackParams, FormRuntime } from '../types/index.js';
+import { type ResolvedFormOption } from '../utils/options.js';
+export declare function useFieldOptions(params: {
+    field: () => FormField;
+    path: () => readonly string[];
+    api: ComputedRef<FormFieldApi>;
+    callbackParams: ComputedRef<FormFieldCallbackParams>;
+    register: FormRuntime['registerFieldOptions'];
+    refreshFieldOptions: FormRuntime['refreshFieldOptions'];
+}): {
+    items: ComputedRef<readonly ResolvedFormOption[]>;
+    pending: ComputedRef<boolean>;
+    fetching: ComputedRef<boolean>;
+    loading: ComputedRef<boolean>;
+    creating: ComputedRef<boolean>;
+    creatable: ComputedRef<boolean>;
+    createLabel: ComputedRef<string | undefined>;
+    error: ComputedRef<unknown>;
+    disableOnLoading: ComputedRef<boolean>;
+    refreshable: ComputedRef<boolean>;
+    selectCreatedOption: ComputedRef<boolean>;
+    refresh: () => Promise<void>;
+    add: (option: unknown) => void;
+    create: (label: string) => Promise<ResolvedFormOption | null>;
+};