nuxt-ui-tools 0.1.0 → 0.1.1

package/dist/runtime/form/fields/input-group/component.vue

@@ -1,35 +1,15 @@
 <script setup>
 import UFieldGroup from "@nuxt/ui/components/FieldGroup.vue";
-import { computed } from "vue";
 import FormFieldRenderer from "../../components/renderer/FormFieldRenderer.vue";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
-import { fieldPath } from "../../composables/use-form-runtime";
 import { useFormUi } from "../../composables/use-form-ui";
 import { mergeFormUiClass } from "../../utils/ui";
-import NumberField from "../number/component.vue";
-import PasswordField from "../password/component.vue";
-import SelectField from "../select/component.vue";
-import TextField from "../text/component.vue";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true },
   parentPath: { type: Array, required: true }
 });
 const formUi = useFormUi();
-const groupChildren = computed(
-  () => props.field.fields.map((child) => ({
-    field: child,
-    path: fieldPath(props.parentPath, child),
-    renderer: getGroupedRenderer(child)
-  }))
-);
-function getGroupedRenderer(field) {
-  if (field.type === "text") return TextField;
-  if (field.type === "password") return PasswordField;
-  if (field.type === "number") return NumberField;
-  if (field.type === "select") return SelectField;
-  return null;
-}
 </script>
 
 <template>
@@ -40,16 +20,13 @@ function getGroupedRenderer(field) {
   mergeFormUiClass('w-full', formUi.ui.value.group?.ui?.root, formUi.ui.value.group?.ui?.base)
 "
     >
-      <template v-for="child in groupChildren" :key="child.field.key">
-        <component
-          :is="child.renderer"
-          v-if="child.renderer"
-          :field="child.field"
-          :path="child.path"
-          bare
-        />
-        <FormFieldRenderer v-else :field="child.field" :parent-path="parentPath" />
-      </template>
+      <FormFieldRenderer
+        v-for="child in field.fields"
+        :key="child.key"
+        :field="child"
+        :parent-path="parentPath"
+        bare
+      />
     </UFieldGroup>
   </FormFieldShell>
 </template>

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

@@ -1,5 +1,5 @@
 <script setup>
-import { computed } from "vue";
+import { computed, useId } from "vue";
 import FormFieldRenderer from "../../components/renderer/FormFieldRenderer.vue";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFormUi } from "../../composables/use-form-ui";
@@ -10,10 +10,11 @@ const props = defineProps({
   path: { type: Array, required: true }
 });
 const formUi = useFormUi();
+const matrixInstanceId = useId();
 const visibleFields = computed(
   () => props.field.fields.filter((field) => field.type !== "hidden" && field.ignore !== true)
 );
-const matrixId = computed(() => props.path.join("-"));
+const matrixId = computed(() => `${matrixInstanceId}-${props.path.join("-")}`);
 const minWidth = computed(
   () => typeof props.field.minWidth === "number" ? `${props.field.minWidth}px` : props.field.minWidth ?? "40rem"
 );
@@ -118,7 +119,12 @@ function controlClass(field) {
 "
             >
               <div :class="controlClass(column)">
-                <FormFieldRenderer :field="column" :parent-path="rowPath(row)" bare />
+                <FormFieldRenderer
+                  :field="column"
+                  :parent-path="rowPath(row)"
+                  :control-labelledby="`${rowLabelId(row)} ${columnLabelId(column)}`"
+                  bare
+                />
               </div>
             </td>
           </tr>

package/dist/runtime/form/fields/phone-number/component.vue

@@ -4,7 +4,7 @@ import UIcon from "@nuxt/ui/components/Icon.vue";
 import UInput from "@nuxt/ui/components/Input.vue";
 import USelectMenu from "@nuxt/ui/components/SelectMenu.vue";
 import { getCountries, getCountryCallingCode, parsePhoneNumberFromString } from "libphonenumber-js";
-import { computed, onMounted, ref, watch } from "vue";
+import { computed, onMounted, ref, useId, watch } from "vue";
 import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
@@ -14,7 +14,7 @@ const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
-const { locale } = useUiToolsLocale();
+const { locale, t } = useUiToolsLocale();
 const { form, controlProps, disabled, handleBlur, placeholder } = useFieldControl(
   () => props.field,
   () => props.path
@@ -25,6 +25,7 @@ const phoneValue = ref("");
 const syncingFromExternal = ref(false);
 const syncingToForm = ref(false);
 const mounted = ref(false);
+const controlId = useId();
 const countryOptions = computed(
   () => getCountries().map((code) => createCountryOption(code)).filter((option) => isCountryAllowed(option)).sort((left, right) => left.label.localeCompare(right.label))
 );
@@ -140,6 +141,8 @@ function toFlagEmoji(code) {
     >
       <USelectMenu
         v-model="countryCode"
+        :id="`${controlId}-country`"
+        :aria-label="t('form.fields.phone.country')"
         class="w-auto min-w-[5.75rem] shrink-0"
         value-key="value"
         label-key="label"
@@ -152,6 +155,8 @@ function toFlagEmoji(code) {
       <UInput
         v-model="phoneValue"
         v-bind="controlProps"
+        :id="`${controlId}-number`"
+        :aria-label="t('form.fields.phone.number')"
         class="min-w-0 flex-1"
         type="tel"
         :placeholder="placeholder"

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

@@ -1,12 +1,14 @@
 <script setup>
 import UIcon from "@nuxt/ui/components/Icon.vue";
 import { computed, ref } from "vue";
+import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
+const { t } = useUiToolsLocale();
 const { form, controlProps, disabled, handleBlur } = useFieldControl(
   () => props.field,
   () => props.path
@@ -30,17 +32,38 @@ function setRating(value) {
   }
   model.value = value;
 }
+function moveRating(event) {
+  if (disabled.value) return;
+  const current = model.value ?? 0;
+  if (event.key === "Home") model.value = 1;
+  else if (event.key === "End") model.value = max.value;
+  else if (event.key === "ArrowRight" || event.key === "ArrowUp")
+    model.value = Math.min(max.value, current + 1);
+  else if (event.key === "ArrowLeft" || event.key === "ArrowDown")
+    model.value = Math.max(1, current - 1);
+  else return;
+  event.preventDefault();
+}
 </script>
 
 <template>
   <FormFieldShell :field="field" :path="path">
-    <div v-bind="controlProps" class="flex items-center gap-1" @blur="handleBlur">
+    <div
+      v-bind="controlProps"
+      role="radiogroup"
+      class="flex w-fit items-center gap-0.5 rounded-lg"
+      @blur="handleBlur"
+      @keydown="moveRating"
+    >
       <button
         v-for="value in max"
         :key="value"
         type="button"
         :disabled="disabled"
-        :aria-pressed="model === value"
+        role="radio"
+        :aria-checked="model === value"
+        :aria-label="t('form.fields.rating.value', { value, max })"
+        :tabindex="model === value || !model && value === 1 ? 0 : -1"
         class="grid size-8 place-items-center rounded-md text-warning transition-colors hover:bg-elevated disabled:cursor-not-allowed disabled:opacity-50 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary"
         :class="value <= visualValue ? 'opacity-100' : 'opacity-40'"
         @mouseenter="hoverValue = value"

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

@@ -2,6 +2,7 @@
 import UButton from "@nuxt/ui/components/Button.vue";
 import USelectMenu from "@nuxt/ui/components/SelectMenu.vue";
 import { computed, ref } from "vue";
+import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 const props = defineProps({
@@ -9,6 +10,7 @@ const props = defineProps({
   path: { type: Array, required: true },
   bare: { type: Boolean, required: false }
 });
+const { t } = useUiToolsLocale();
 const { form, controlProps, disabled, handleBlur, options, placeholder } = useFieldControl(
   () => props.field,
   () => props.path
@@ -25,27 +27,29 @@ const model = computed({
 });
 const items = computed(() => [...options.items.value]);
 const createItem = computed(
-  () => options.creatable.value ? props.field.createItem ?? { position: "bottom", when: "empty" } : false
+  () => options.creatable.value && props.field.createItem ? props.field.createItem : false
 );
-const showFooterActions = computed(() => options.refreshable.value || options.creatable.value);
+const showExplicitCreate = computed(
+  () => options.creatable.value && !props.field.createItem
+);
+const showFooterActions = computed(() => options.refreshable.value || showExplicitCreate.value);
 const footerActionsClass = computed(
-  () => options.refreshable.value && options.creatable.value ? "sm:grid-cols-2" : "grid-cols-1"
+  () => options.refreshable.value && showExplicitCreate.value ? "sm:grid-cols-2" : "grid-cols-1"
+);
+const createActionLabel = computed(
+  () => options.createLabel.value ?? t("form.fields.options.create")
 );
-const createActionLabel = computed(() => options.createLabel.value ?? "Create option");
 async function handleCreate(label) {
-  const option = await options.create(label);
-  if (!option) return;
-  if (!options.selectCreatedOption.value) return;
-  if (props.field.multiple) {
-    const current = Array.isArray(model.value) ? model.value.filter(isOptionValue) : [];
-    model.value = [...current, option.value];
-    return;
-  }
-  model.value = option.value;
+  await options.create(label);
 }
 async function handleCreateAction() {
   await handleCreate(searchTerm.value);
 }
+async function handleNativeCreate(label) {
+  const normalizedLabel = label.trim();
+  if (!normalizedLabel) return;
+  await handleCreate(normalizedLabel);
+}
 async function refreshOptions() {
   await options.refresh();
 }
@@ -71,7 +75,7 @@ function isOptionValue(value) {
     :search-input="field.searchable ?? false"
     :clear="field.clearable === true"
     :create-item="createItem"
-    @create="handleCreate"
+    @create="handleNativeCreate"
     @blur="handleBlur"
   >
     <template #content-bottom>
@@ -90,10 +94,10 @@ function isOptionValue(value) {
           :loading="options.pending.value || options.fetching.value"
           @click.stop="refreshOptions"
         >
-          Refresh
+          {{ t("form.fields.options.refresh") }}
         </UButton>
         <UButton
-          v-if="options.creatable.value"
+          v-if="showExplicitCreate"
           block
           size="xs"
           variant="ghost"
@@ -109,7 +113,9 @@ function isOptionValue(value) {
     </template>
 
     <template #create-item-label="{ item }">
-      {{ options.creating.value ? "Creating..." : `Create "${item}"` }}
+      {{
+        options.creating.value ? t("form.fields.options.creating") : t("form.fields.options.createNamed", { label: item })
+      }}
     </template>
   </USelectMenu>
   <FormFieldShell v-else :field="field" :path="path">
@@ -128,7 +134,7 @@ function isOptionValue(value) {
       :search-input="field.searchable ?? false"
       :clear="field.clearable === true"
       :create-item="createItem"
-      @create="handleCreate"
+      @create="handleNativeCreate"
       @blur="handleBlur"
     >
       <template #content-bottom>
@@ -147,10 +153,10 @@ function isOptionValue(value) {
             :loading="options.pending.value || options.fetching.value"
             @click.stop="refreshOptions"
           >
-            Refresh
+            {{ t("form.fields.options.refresh") }}
           </UButton>
           <UButton
-            v-if="options.creatable.value"
+            v-if="showExplicitCreate"
             block
             size="xs"
             variant="ghost"
@@ -166,7 +172,9 @@ function isOptionValue(value) {
       </template>
 
       <template #create-item-label="{ item }">
-        {{ options.creating.value ? "Creating..." : `Create "${item}"` }}
+        {{
+          options.creating.value ? t("form.fields.options.creating") : t("form.fields.options.createNamed", { label: item })
+        }}
       </template>
     </USelectMenu>
   </FormFieldShell>

package/dist/runtime/form/fields/switch-group/component.vue

@@ -1,8 +1,9 @@
 <script setup>
 import USwitch from "@nuxt/ui/components/Switch.vue";
-import { computed } from "vue";
+import { computed, useId } from "vue";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
+import { formOptionKey } from "../../utils/options";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
@@ -19,6 +20,7 @@ const model = computed({
   set: (value) => form.setValue(props.path, value)
 });
 const items = computed(() => [...options.items.value]);
+const groupId = useId();
 function toggleOption(value, checked) {
   const current = model.value;
   if (checked) {
@@ -35,15 +37,18 @@ function isOptionValue(value) {
 <template>
   <FormFieldShell :field="field" :path="path">
     <div
-      v-bind="controlProps"
+      role="group"
       class="grid gap-3"
       :class="field.orientation === 'horizontal' ? 'sm:flex sm:flex-wrap' : ''"
     >
       <USwitch
         v-for="item in items"
-        :key="String(item.value)"
+        :id="`${groupId}:${formOptionKey(item.value)}`"
+        :key="formOptionKey(item.value)"
+        v-bind="controlProps"
         :model-value="model.includes(item.value)"
         :label="item.label"
+        :aria-label="item.label"
         :description="item.description"
         :disabled="disabled || item.disabled"
         :checked-icon="field.checkedIcon"

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

@@ -4,12 +4,14 @@ import UInput from "@nuxt/ui/components/Input.vue";
 import UPopover from "@nuxt/ui/components/Popover.vue";
 import USelect from "@nuxt/ui/components/Select.vue";
 import { computed, ref, watch } from "vue";
+import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
+const { t } = useUiToolsLocale();
 const { form, controlProps, disabled, handleBlur, placeholder } = useFieldControl(
   () => props.field,
   () => props.path
@@ -128,7 +130,7 @@ function padTimePart(value) {
           class="w-full"
           inputmode="numeric"
           leading-icon="i-lucide-clock"
-          :placeholder="placeholder ?? 'HH:mm'"
+          :placeholder="placeholder ?? t('form.fields.time.format')"
           :disabled="disabled"
           @update:model-value="handleInput"
           @focus="handleFocus"
@@ -142,7 +144,7 @@ function padTimePart(value) {
               variant="ghost"
               size="xs"
               :disabled="disabled"
-              aria-label="Clear time"
+              :aria-label="t('form.fields.time.clear')"
               @mousedown.prevent
               @click="clearTime"
             />
@@ -158,7 +160,7 @@ function padTimePart(value) {
               :items="hours"
               class="min-w-0"
               size="sm"
-              placeholder="Hour"
+              :placeholder="t('form.fields.time.hour')"
               :portal="false"
             />
             <USelect
@@ -166,7 +168,7 @@ function padTimePart(value) {
               :items="minutes"
               class="min-w-0"
               size="sm"
-              placeholder="Minute"
+              :placeholder="t('form.fields.time.minute')"
               :portal="false"
             />
           </div>
@@ -209,7 +211,7 @@ function padTimePart(value) {
             >
           </div>
           <p class="text-xs text-muted">
-            {{ model ?? "HH:mm" }}
+            {{ model ?? t("form.fields.time.format") }}
           </p>
         </div>
       </template>

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

@@ -3,12 +3,14 @@ import UAlert from "@nuxt/ui/components/Alert.vue";
 import UButton from "@nuxt/ui/components/Button.vue";
 import UFileUpload from "@nuxt/ui/components/FileUpload.vue";
 import { computed, onScopeDispose, ref } from "vue";
+import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/FormFieldShell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
+const { t } = useUiToolsLocale();
 const { form, controlProps, disabled, handleBlur, params } = useFieldControl(
   () => props.field,
   () => props.path
@@ -44,7 +46,7 @@ async function uploadFiles() {
     selectedFiles.value = null;
   } catch (error) {
     if (uploadRun.value !== run) return;
-    uploadError.value = error instanceof Error ? error.message : "Upload failed.";
+    uploadError.value = error instanceof Error ? error.message : t("form.fields.upload.failed");
   } finally {
     if (uploadRun.value === run) uploadPending.value = false;
   }
@@ -105,7 +107,7 @@ function isFormObject(value) {
           :disabled="disabled || !files.length"
           @click="uploadFiles"
         >
-          Upload
+          {{ t("form.fields.upload.upload") }}
         </UButton>
         <UButton
           v-if="uploadedValue"
@@ -116,7 +118,7 @@ function isFormObject(value) {
           :disabled="disabled"
           @click="removeUpload"
         >
-          Remove
+          {{ t("form.fields.upload.remove") }}
         </UButton>
       </div>
 

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

@@ -1,4 +1,5 @@
 import type { ComputedRef } from 'vue';
+import type { NestedPaths } from '../../shared/types/utils.js';
 import type { FormContextData } from './context.js';
 import type { FormMaybePromise, FormObject } from './utils.js';
 import type { FormValidationOptions } from './validation.js';
@@ -111,15 +112,20 @@ export interface FormFieldApi<TValue = unknown, TOption = unknown, TContext = Fo
 /**
  * Public form API available from form-level callbacks.
  */
-export interface FormApi {
+export type FormFieldPath<TOutput = FormObject> = TOutput extends FormObject ? FormObject extends TOutput ? string : NestedPaths<TOutput> : string;
+export interface FormApi<TOutput = FormObject> {
     /** Reads an internal form value by raw path. */
     get: (path: string) => unknown;
     /** Writes an internal form value by raw path. */
     set: (path: string, value: unknown) => void;
     /** Runs form validation. */
     validate: (options?: FormValidationOptions) => Promise<boolean>;
+    /** Sets an external error on a submitted output field. */
+    setError: (path: FormFieldPath<TOutput>, message: string) => void;
+    /** Clears one external field error, or every form error when no path is provided. */
+    clearError: (path?: FormFieldPath<TOutput>) => void;
     /** Focuses a mounted field by raw path. */
-    focus: (path: string | readonly string[]) => Promise<boolean>;
+    focus: (path: FormFieldPath<TOutput> | readonly string[]) => Promise<boolean>;
     /** Submits the form through the configured submit lifecycle. */
     submit: () => Promise<void>;
     /** Resets the form to configured defaults. */
@@ -136,7 +142,7 @@ export interface FormSubmitHandlerParams<TOutput = FormObject> {
     /** Submitted output value after output transforms and omitted fields are applied. */
     formData: TOutput;
     /** Namespaced form API for state, validation, submit, and reset operations. */
-    api: FormApi;
+    api: FormApi<TOutput>;
 }
 export type FormSubmitHandler<TOutput = FormObject, TSubmitData = unknown> = (params: FormSubmitHandlerParams<TOutput>) => FormMaybePromise<FormSubmitResult<TSubmitData>>;
 export interface FormSubmitHandlerResult<TSubmitData = unknown> {

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

@@ -2,7 +2,7 @@ import type { FormFieldCallback } from './callbacks.js';
 import type { FormField } from './field.js';
 import type { FormContainerLayout, FormItemLayout } from './layout.js';
 import type { FormTransformConfig } from './transform.js';
-import type { FormDynamic, FormMaybePromise, FormObject, FormText } from './utils.js';
+import type { FormDynamic, FormMaybePromise, FormObject, FormRenderable, FormText } from './utils.js';
 import type { FormValidationConfig } from './validation.js';
 /**
  * Field kinds targeted by the current form runtime plan.
@@ -26,6 +26,8 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
     description?: FormText;
     /** Optional right-side hint rendered by the field wrapper. */
     hint?: FormText;
+    /** Optional rich content rendered beside the label. Takes precedence over `hint`. */
+    labelExtra?: FormRenderable;
     /** Placeholder forwarded to controls that support placeholders. */
     placeholder?: FormText;
     /** Raw dependency paths read before evaluating callbacks. */

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

@@ -76,6 +76,8 @@ export interface FormRuntime {
     shouldRender: (field: FormField, path: readonly string[]) => boolean;
     validate: (options?: FormValidationOptions) => Promise<boolean>;
     validateCurrentStep: (options?: FormValidationOptions) => Promise<boolean>;
+    setError: (path: string | readonly string[], message: string) => void;
+    clearError: (path?: string | readonly string[]) => void;
     focusRequest: Ref<FormFocusRequest | null>;
     registerFieldElement: (path: string | readonly string[], element: HTMLElement) => () => void;
     focusField: (path: string | readonly string[]) => Promise<boolean>;

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

@@ -40,6 +40,7 @@ export interface FormFieldUi {
     description?: FormUiClass;
     error?: FormUiClass;
     hint?: FormUiClass;
+    labelExtra?: FormUiClass;
     help?: FormUiClass;
     body?: FormUiClass;
     content?: FormUiClass;

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

@@ -1,8 +1,11 @@
+import { pathSegments } from "./path.js";
 export function createPublicFormApi(runtime) {
   return {
     get: runtime.getValue,
     set: runtime.setValue,
     validate: runtime.validate,
+    setError: (path, message) => runtime.setError(pathSegments(path), message),
+    clearError: (path) => runtime.clearError(path ? pathSegments(path) : void 0),
     focus: runtime.focusField,
     submit: async () => {
       await runtime.submit();

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

@@ -1,4 +1,9 @@
 import type { FormFieldCallbackParams, FormOptionItem, FormOptionValue } from '../types/index.js';
+export interface FormOptionKeys {
+    value?: string;
+    label?: string;
+    children?: string;
+}
 export interface ResolvedFormOption {
     value: FormOptionValue;
     label: string;
@@ -6,6 +11,10 @@ export interface ResolvedFormOption {
     disabled?: boolean;
     children?: readonly ResolvedFormOption[];
 }
-export declare function normalizeOptionItem(option: unknown): ResolvedFormOption;
-export declare function normalizeOptionItems(options: readonly unknown[] | undefined): ResolvedFormOption[];
+export declare function normalizeOptionItem(option: unknown, keys?: FormOptionKeys): ResolvedFormOption;
+export declare function normalizeOptionItems(options: readonly unknown[] | undefined, keys?: FormOptionKeys): ResolvedFormOption[];
+export declare function formOptionKey(value: FormOptionValue): string;
+export declare function flattenResolvedOptions(options: readonly ResolvedFormOption[]): readonly ResolvedFormOption[];
+export declare function mergeResolvedOptions(...collections: readonly (readonly ResolvedFormOption[])[]): readonly ResolvedFormOption[];
+export declare function normalizeOptionSelection(value: unknown, options: readonly ResolvedFormOption[]): any[] | FormOptionValue | null | undefined;
 export declare function resolveOptionSource(source: unknown, params: FormFieldCallbackParams): readonly FormOptionItem[];

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

@@ -1,14 +1,19 @@
 import { isRecord } from "./path.js";
-export function normalizeOptionItem(option) {
+import { resolveFormText } from "./text.js";
+export function normalizeOptionItem(option, keys = {}) {
   if (isRecord(option)) {
-    const rawValue = typeof option.value === "undefined" ? option.key : option.value;
-    const children = Array.isArray(option.children) ? option.children.map((child) => normalizeOptionItem(child)) : void 0;
+    const rawValue = readOptionProperty(option, keys.value ?? "value");
+    const fallbackValue = typeof rawValue === "undefined" ? option.key : rawValue;
+    const rawChildren = readOptionProperty(option, keys.children ?? "children");
+    const rawDescription = readOptionProperty(option, "description");
+    const children = Array.isArray(rawChildren) ? rawChildren.map((child) => normalizeOptionItem(child, keys)) : void 0;
+    const value = normalizeOptionValue(fallbackValue);
     return {
-      value: normalizeOptionValue(rawValue),
-      label: typeof option.label === "string" || typeof option.label === "number" ? String(option.label) : String(normalizeOptionValue(rawValue)),
-      description: typeof option.description === "string" || typeof option.description === "number" ? String(option.description) : void 0,
+      value,
+      label: resolveFormText(readOptionProperty(option, keys.label ?? "label")) ?? String(value),
+      description: isFormText(rawDescription) ? resolveFormText(rawDescription) : void 0,
       disabled: option.disabled === true,
-      children
+      ...children ? { children } : {}
     };
   }
   return {
@@ -16,8 +21,42 @@ export function normalizeOptionItem(option) {
     label: String(option)
   };
 }
-export function normalizeOptionItems(options) {
-  return (options ?? []).map((option) => normalizeOptionItem(option));
+export function normalizeOptionItems(options, keys = {}) {
+  return (options ?? []).map((option) => normalizeOptionItem(option, keys));
+}
+export function formOptionKey(value) {
+  return `${typeof value}:${String(value)}`;
+}
+export function flattenResolvedOptions(options) {
+  return options.flatMap((option) => [option, ...flattenResolvedOptions(option.children ?? [])]);
+}
+export function mergeResolvedOptions(...collections) {
+  const seen = /* @__PURE__ */ new Set();
+  return collections.flatMap(
+    (collection) => collection.filter((option) => {
+      const key = formOptionKey(option.value);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+  );
+}
+export function normalizeOptionSelection(value, options) {
+  const validKeys = new Set(
+    flattenResolvedOptions(options).map((option) => formOptionKey(option.value))
+  );
+  if (Array.isArray(value)) {
+    const selected = /* @__PURE__ */ new Set();
+    return value.filter((item) => {
+      if (!isOptionValue(item)) return false;
+      const key = formOptionKey(item);
+      if (!validKeys.has(key) || selected.has(key)) return false;
+      selected.add(key);
+      return true;
+    });
+  }
+  if (value === null || typeof value === "undefined") return value;
+  return isOptionValue(value) && validKeys.has(formOptionKey(value)) ? value : null;
 }
 export function resolveOptionSource(source, params) {
   if (!source) return [];
@@ -34,3 +73,12 @@ function normalizeOptionValue(value) {
     return value;
   return String(value);
 }
+function readOptionProperty(option, key) {
+  return Object.getOwnPropertyDescriptor(option, key)?.value;
+}
+function isFormText(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "function";
+}
+function isOptionValue(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}