nuxt-ui-tools 1.18.0 → 1.20.0

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

@@ -2,7 +2,10 @@
 import URadioGroup from "@nuxt/ui/components/RadioGroup.vue";
 import { computed } from "vue";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
+import FormOptionChoiceLabel from "../../components/utils/form-option-choice-label.vue";
+import { useChoiceGroupItems } from "../../composables/use-choice-group-items";
 import { useFieldControl } from "../../composables/use-field-control";
+import { formOptionKey } from "../../utils/options";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
 import { mergeFormUiClass } from "../../utils/ui";
 import { CARD_SELECTED_RING } from "../card-selection";
@@ -24,7 +27,13 @@ const model = computed({
   },
   set: (value) => form.setValue(props.path, value)
 });
-const items = computed(() => [...options.items.value]);
+const renderOption = computed(() => props.field.renderOption);
+const { items, optionOf } = useChoiceGroupItems({
+  custom: () => renderOption.value !== void 0,
+  options,
+  ui: () => controlProps.value.ui,
+  valueOf: (option) => option.value
+});
 const groupUi = computed(() => ({
   ...controlProps.value.ui,
   item: mergeFormUiClass(
@@ -49,6 +58,14 @@ const groupUi = computed(() => ({
       :indicator="fieldProps.indicator"
       :disabled="disabled"
       @blur="handleBlur"
-    />
+    >
+      <template #label="{ item }">
+        <FormOptionChoiceLabel
+          :option="optionOf(formOptionKey(item.value))"
+          :selected="model === item.value"
+          :render="renderOption"
+        />
+      </template>
+    </URadioGroup>
   </FormFieldShell>
 </template>

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

@@ -1,6 +1,6 @@
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldOptionValue, NullableValue } from '../../types/field-output-utils.js';
-import type { FormOptionItem, FormOptionValue, FormOptionsSource } from '../../types/options.js';
+import type { FormOptionItem, FormOptionRenderers, FormOptionValue, FormOptionsSource } from '../../types/options.js';
 export interface FormRadioProps {
     /**
      * `list` (the default) lines up bare radios, `card` frames each option on its own, and `table`
@@ -11,7 +11,7 @@ export interface FormRadioProps {
     orientation?: 'horizontal' | 'vertical';
     indicator?: 'start' | 'end' | 'hidden';
 }
-export interface FormRadioField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'radio', TValue | null, TContext, TDeps, FormRadioProps> {
+export interface FormRadioField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'radio', TValue | null, TContext, TDeps, FormRadioProps>, FormOptionRenderers<TOption> {
     options: FormOptionsSource<TOption, TContext, TDeps, TValue | null>;
 }
 export type RadioFieldOutput<TField> = FieldOptionValue<TField> | NullableValue;

package/dist/runtime/form/fields/radio-card/component.vue

@@ -3,11 +3,11 @@ import URadioGroup from "@nuxt/ui/components/RadioGroup.vue";
 import { computed } from "vue";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
-import { formOptionKey } from "../../utils/options";
+import { formOptionKey, groupOptions } from "../../utils/options";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
 import ChoiceCardLabel from "../choice-card/choice-card-label.vue";
 import { CHOICE_CARD_PROPS, useChoiceCard } from "../choice-card/use-choice-card";
-import { choiceCardGroupAttrs, groupChoiceCardItems } from "../choice-card/utils";
+import { choiceCardGroupAttrs } from "../choice-card/utils";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
@@ -40,7 +40,7 @@ const items = computed(
     (item) => cards.compact.value ? { ...item, description: void 0 } : item
   )
 );
-const groups = computed(() => groupChoiceCardItems(items.value));
+const groups = computed(() => groupOptions(items.value));
 function selectionOf(group) {
   return group.items.some((item) => item.value === model.value) ? model.value : void 0;
 }

package/dist/runtime/form/fields/radio-card/types.d.ts

@@ -1,8 +1,8 @@
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldOptionValue, NullableValue } from '../../types/field-output-utils.js';
-import type { FormOptionValue, FormOptionsSource } from '../../types/options.js';
-import type { FormChoiceCardGrouping, FormChoiceCardOptionItem, FormChoiceCardProps } from '../choice-card/types.js';
-export interface FormRadioCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormChoiceCardOptionItem<TValue> = FormChoiceCardOptionItem<TValue>> extends FormStatefulFieldBase<'radio-card', TValue | null, TContext, TDeps, FormChoiceCardProps>, FormChoiceCardGrouping {
+import type { FormOptionGrouping, FormOptionValue, FormOptionsSource } from '../../types/options.js';
+import type { FormChoiceCardOptionItem, FormChoiceCardProps } from '../choice-card/types.js';
+export interface FormRadioCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormChoiceCardOptionItem<TValue> = FormChoiceCardOptionItem<TValue>> extends FormStatefulFieldBase<'radio-card', TValue | null, TContext, TDeps, FormChoiceCardProps>, FormOptionGrouping {
     options: FormOptionsSource<TOption, TContext, TDeps, TValue | null>;
 }
 export type RadioCardFieldOutput<TField> = FieldOptionValue<TField> | NullableValue;

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

@@ -1,12 +1,16 @@
 <script setup>
 import USelectMenu from "@nuxt/ui/components/SelectMenu.vue";
+import { createReusableTemplate } from "@vueuse/core";
 import { computed, ref, watch } from "vue";
 import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
+import FormOptionDisplayValue from "../../components/utils/form-option-display-value.vue";
 import FormOptionItemLabel from "../../components/utils/form-option-item-label.vue";
+import FormOptionLeading from "../../components/utils/form-option-leading.vue";
 import FormOptionMenuFooter from "../../components/utils/form-option-menu-footer.vue";
+import FormOptionSuffix from "../../components/utils/form-option-suffix.vue";
 import { useFieldControl } from "../../composables/use-field-control";
-import { appendLoadMoreOption } from "../../utils/options";
+import { useOptionMenu } from "../../composables/use-option-menu";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
 import { mergeFormUiClass } from "../../utils/ui";
 const props = defineProps({
@@ -30,6 +34,7 @@ const {
   () => props.path,
   { omit: ["createItem", "max", "searchable", "clearable"] }
 );
+const [DefineControl, ReuseControl] = createReusableTemplate();
 const searchTerm = ref("");
 const open = ref(false);
 const model = computed({
@@ -51,16 +56,20 @@ const model = computed({
     form.setValue(props.path, value);
   }
 });
-const items = computed(() => [
-  ...appendLoadMoreOption(
-    options.items.value,
-    options.remote.value && (options.hasMore.value || options.loadingMore.value),
-    t("form.fields.options.loadingMore")
-  )
-]);
+const menu = useOptionMenu({
+  field: () => props.field,
+  loadMoreLabel: () => t("form.fields.options.loadingMore"),
+  model: () => model.value,
+  multiple: () => fieldProps.value.multiple === true,
+  options
+});
 const controlUi = computed(() => ({
   ...controlProps.value.ui,
-  content: mergeFormUiClass(controlProps.value.ui?.content, interactionOwnerClass.value)
+  content: mergeFormUiClass(controlProps.value.ui?.content, interactionOwnerClass.value),
+  itemDescription: mergeFormUiClass(
+    menu.renderOption.value ? "hidden" : "text-[12.5px]",
+    controlProps.value.ui?.itemDescription
+  )
 }));
 const createItem = computed(
   () => options.creatable.value && fieldProps.value.createItem ? fieldProps.value.createItem : false
@@ -109,53 +118,7 @@ function isOptionValue(value) {
 </script>
 
 <template>
-  <USelectMenu
-    v-if="bare"
-    v-model="model"
-    v-model:search-term="searchTerm"
-    :open="open"
-    v-bind="controlProps"
-    class="w-full"
-    value-key="value"
-    label-key="label"
-    :items="items"
-    :multiple="fieldProps.multiple"
-    :placeholder="placeholder"
-    :disabled="disabled"
-    :loading="
-  validationPending || options.loading.value || options.fetching.value || options.creating.value
-"
-    :trailing="true"
-    :search-input="searchable"
-    :ignore-filter="options.remote.value"
-    :clear="fieldProps.clearable === true"
-    :create-item="createItem"
-    :ui="controlUi"
-    @update:open="handleOpen"
-    @create="handleNativeCreate"
-    @blur="handleBlur"
-  >
-    <template #item-label="{ item }">
-      <FormOptionItemLabel :item="item" />
-    </template>
-
-    <template #content-bottom>
-      <FormOptionMenuFooter
-        :options="options"
-        :disabled="disabled"
-        :show-create="showExplicitCreate"
-        :create-label="createActionLabel"
-        @create="handleCreateAction"
-      />
-    </template>
-
-    <template #create-item-label="{ 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">
+  <DefineControl>
     <USelectMenu
       v-model="model"
       v-model:search-term="searchTerm"
@@ -164,7 +127,7 @@ function isOptionValue(value) {
       class="w-full"
       value-key="value"
       label-key="label"
-      :items="items"
+      :items="menu.items.value"
       :multiple="fieldProps.multiple"
       :placeholder="placeholder"
       :disabled="disabled"
@@ -181,8 +144,38 @@ function isOptionValue(value) {
       @create="handleNativeCreate"
       @blur="handleBlur"
     >
+      <template v-if="menu.leadingOption.value" #leading="{ ui }">
+        <FormOptionLeading
+          :option="menu.leadingOption.value"
+          :icon-class="ui.leadingIcon()"
+          :avatar-size="ui.itemLeadingAvatarSize()"
+          chip-class="size-5"
+        />
+      </template>
+
+      <template v-if="menu.customValueOption.value" #default="{ ui }">
+        <span :class="ui.value({ class: controlProps.ui?.value })" data-slot="value">
+          <FormOptionDisplayValue
+            :option="menu.customValueOption.value"
+            :render="menu.renderValue.value"
+          />
+        </span>
+      </template>
+
+      <template #item-leading="{ item }">
+        <FormOptionLeading :option="menu.renderOption.value ? void 0 : item" />
+      </template>
+
       <template #item-label="{ item }">
-        <FormOptionItemLabel :item="item" />
+        <FormOptionItemLabel
+          :option="item"
+          :selected="menu.isSelected(item)"
+          :render="menu.renderOption.value"
+        />
+      </template>
+
+      <template #item-trailing="{ item }">
+        <FormOptionSuffix v-if="!menu.renderOption.value" :option="item" />
       </template>
 
       <template #content-bottom>
@@ -201,5 +194,10 @@ function isOptionValue(value) {
         }}
       </template>
     </USelectMenu>
+  </DefineControl>
+
+  <ReuseControl v-if="bare" />
+  <FormFieldShell v-else :field="field" :path="path">
+    <ReuseControl />
   </FormFieldShell>
 </template>

package/dist/runtime/form/fields/select/config.d.ts

@@ -4,6 +4,7 @@ export declare const selectFieldKind: {
     };
     readonly options: {
         readonly enabled: true;
+        readonly groups: true;
     };
     readonly state: "stateful";
     readonly transform: true;

package/dist/runtime/form/fields/select/config.js

@@ -1,7 +1,7 @@
 import { defineFormFieldKind } from "../../utils/field-kind.js";
 export const selectFieldKind = defineFormFieldKind({
   layout: { item: true },
-  options: { enabled: true },
+  options: { enabled: true, groups: true },
   state: "stateful",
   transform: true,
   type: "select",

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

@@ -1,6 +1,6 @@
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldOptionValue, FieldProps, FallbackNever, NullableValue } from '../../types/field-output-utils.js';
-import type { FormAnyOptionConfig, FormOptionItem, FormOptionValue } from '../../types/options.js';
+import type { FormAnyOptionConfig, FormOptionGrouping, FormOptionItem, FormOptionValue, FormOptionValueRenderers } from '../../types/options.js';
 export type FormSelectCreateItem = boolean | 'always' | {
     position?: 'top' | 'bottom';
     when?: 'always' | 'empty';
@@ -12,7 +12,7 @@ export interface FormSelectProps {
     createItem?: FormSelectCreateItem;
     max?: number;
 }
-export interface FormSelectField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'select', TValue | readonly TValue[] | null, TContext, TDeps, FormSelectProps> {
+export interface FormSelectField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'select', TValue | readonly TValue[] | null, TContext, TDeps, FormSelectProps>, FormOptionGrouping, FormOptionValueRenderers<TOption> {
     options: FormAnyOptionConfig<TOption, TContext, TDeps, TValue | readonly TValue[] | null>;
 }
 type SelectFieldValue<TField> = FieldProps<TField> extends {

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

@@ -20,6 +20,12 @@ export interface FormLayoutConfig {
 export interface FormItemLayout {
     /** Column span for this field inside the owning layout grid. Replaces legacy `size`. */
     span?: number | string;
+    /**
+     * Starts this field on a new row of the owning grid, at its first column, whatever the fields
+     * before it left free. Only the start of the column is set, so a responsive `span` still
+     * decides how wide the field is at each breakpoint.
+     */
+    newRow?: boolean;
     /** Fixed width used by renderers that lay fields out as columns, such as array tables. */
     width?: number | string;
     /** Label placement for this field. */

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

@@ -1,9 +1,29 @@
 import type { QueryKey } from '@tanstack/vue-query';
+import type { VNodeChild } from 'vue';
 import type { RemoteOptionsLoader, RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { FormValue } from './/index.js';
 import type { FormDependencies, FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
 import type { FormMaybePromise, FormText } from './utils.js';
+/** Colors a `chip` option dot can take. */
+export type FormOptionChipColor = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral';
+/**
+ * Picture drawn before an option label, passed to the Nuxt UI avatar. Use it for people and
+ * organisations: `text` is the fallback shown when `src` is missing or fails to load.
+ */
+export interface FormOptionAvatar {
+    /** Image URL. */
+    src?: string;
+    /** Accessible description of the image. Defaults to the option label. */
+    alt?: string;
+    /** Fallback text shown when there is no image, such as initials. */
+    text?: string;
+}
+/** Colored dot drawn before an option label, for statuses and categories. */
+export interface FormOptionChip {
+    /** Color of the dot. Defaults to `primary`. */
+    color?: FormOptionChipColor;
+}
 /**
  * Primitive value accepted by option-based fields.
  */
@@ -20,6 +40,123 @@ export interface FormOption<TValue extends FormOptionValue = FormOptionValue> {
     description?: FormText;
     /** Disables the option without removing it from the list. */
     disabled?: boolean;
+    /** Iconify icon drawn before the label. */
+    icon?: string;
+    /**
+     * Picture drawn before the label, for people and organisations. Only one leading visual shows,
+     * in the order `icon`, `avatar`, `chip`.
+     */
+    avatar?: FormOptionAvatar;
+    /**
+     * Colored dot drawn before the label, for statuses and categories. Only one leading visual
+     * shows, in the order `icon`, `avatar`, `chip`.
+     */
+    chip?: FormOptionChip;
+    /**
+     * Secondary text at the end of the option, such as a code (`EUR`) or a count. It also follows
+     * the label in the closed control of a select.
+     */
+    suffix?: FormText;
+}
+/**
+ * Option as the engine resolved it: the shared shape every option-based field renders from,
+ * whatever the authored option looked like (a primitive, a record, or a record with its own keys).
+ */
+export interface ResolvedFormOption {
+    value: FormOptionValue;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+    icon?: string;
+    avatar?: FormOptionAvatar;
+    chip?: FormOptionChip;
+    /** Secondary text at the end of the option, already resolved. */
+    suffix?: string;
+    /**
+     * The option exactly as the schema or the source gave it, so render functions can read any
+     * data it carries. A primitive option is the primitive itself. The load-more row has none.
+     */
+    item?: FormOptionItem;
+    /** Heading the option is listed under, for the fields that group their options. */
+    group?: string;
+    children?: readonly ResolvedFormOption[];
+    /** True when the option has children that load on demand. */
+    lazy?: boolean;
+}
+/** What a field hands `renderOption` for each option it lists. */
+export interface FormOptionRenderContext<TOption = FormOptionItem> {
+    /** The resolved option: label, description, icon, avatar, chip and suffix as the field reads them. */
+    option: ResolvedFormOption;
+    /** The option exactly as authored or returned by the source, with any custom data it carries. */
+    item: TOption;
+    /** True when the option is part of the field value. */
+    selected: boolean;
+    /** True when the option cannot be chosen. */
+    disabled: boolean;
+}
+/** What a field hands `renderValue` for the option it shows in the closed control. */
+export interface FormOptionValueRenderContext<TOption = FormOptionItem> {
+    /** The resolved option: label, description, icon, avatar, chip and suffix as the field reads them. */
+    option: ResolvedFormOption;
+    /** The option exactly as authored or returned by the source, with any custom data it carries. */
+    item: TOption;
+}
+/**
+ * Content render functions of the option-based fields, declared on the field next to its
+ * `options`. A field typed with its option type (`FormSelectField<Ctx, Deps, Value, Currency>`)
+ * hands them that type. In an inline schema the option type is not inferred into the callback, so
+ * annotate the parameter with the context of your option type to read its custom data.
+ *
+ * @example
+ * ```ts
+ * interface Currency extends FormOption<'EUR' | 'USD'> {
+ *   symbol: string
+ * }
+ *
+ * // Each currency is listed as its symbol, then its name.
+ * {
+ *   type: 'select',
+ *   key: 'currency',
+ *   options: [{ value: 'EUR', label: 'Euro', symbol: '€' }],
+ *   renderOption: ({ item, option }: FormOptionRenderContext<Currency>) =>
+ *     h('span', [item.symbol, ' ', option.label]),
+ * }
+ * ```
+ */
+export interface FormOptionRenderers<TOption = FormOptionItem> {
+    /**
+     * Replaces the content of each option in the list: label, description, leading visual and
+     * suffix. The control keeps its own selection indicator and keyboard behavior.
+     */
+    renderOption?(context: FormOptionRenderContext<TOption>): VNodeChild;
+}
+/** Renderers of the fields that show the chosen option in a closed control. */
+export interface FormOptionValueRenderers<TOption = FormOptionItem> extends FormOptionRenderers<TOption> {
+    /**
+     * Replaces how the chosen option reads in the closed control, in single selection. Multiple
+     * selection keeps its comma-separated labels.
+     */
+    renderValue?(context: FormOptionValueRenderContext<TOption>): VNodeChild;
+}
+/**
+ * Option grouping of the fields that list options under headings, declared on the field next to
+ * its `options`.
+ *
+ * @example
+ * ```ts
+ * // Rows from the API, each with a `section` to list the options under.
+ * { type: 'select', options: () => queryOptions({ queryKey: ['plans'], queryFn: fetchPlans }), groupKey: 'section' }
+ * ```
+ */
+export interface FormOptionGrouping {
+    /**
+     * Property of the options that holds the heading they are listed under. Options written inline
+     * in the schema group by their `group` without it. The records a function, a promise or a query
+     * returns group only when this names the property, so records that already carry a `group` for
+     * another purpose are never regrouped by surprise. `false` lists every option together, even
+     * inline options that carry a `group`.
+     */
+    groupKey?: string | false;
 }
 /**
  * Authored option item accepted by option-based fields.

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

@@ -40,6 +40,11 @@ export interface FormPageSection<TContext = NonNullable<unknown>, TFields extend
     label: FormText;
     /** Supporting copy next to the title. */
     description?: FormText;
+    /**
+     * Iconify icon drawn before the title, so each section of a long page reads at a glance
+     * (`'i-lucide-map-pin'` for an address). Style it with `ui.page.ui.sectionIcon`.
+     */
+    icon?: string;
     /**
      * Marks the section optional while nothing is entered in it, and leaves it out of the sections
      * left to complete. A section without a required field is optional already; set this when its
@@ -172,6 +177,8 @@ export interface FormPageSectionState {
     label: string;
     /** Resolved supporting copy. */
     description?: string;
+    /** Icon drawn before the title. */
+    icon?: string;
     /**
      * True when the section is declared optional, or declares nothing and has no required field
      * outside array items.

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

@@ -227,6 +227,11 @@ export interface FormPageUi {
     /** Grid holding the navigation and the sections. */
     body?: FormUiClass;
     header?: FormUiClass;
+    /**
+     * Row holding the heading and the actions. Beside a navigation it adds no box of its own; on a
+     * page without one it is the centered column the body shares, and carries the header padding.
+     */
+    headerRow?: FormUiClass;
     headerContent?: FormUiClass;
     heading?: FormUiClass;
     eyebrow?: FormUiClass;
@@ -263,6 +268,8 @@ export interface FormPageUi {
     sectionSkeleton?: FormUiClass;
     section?: FormUiClass;
     sectionHeader?: FormUiClass;
+    /** Tile around the section `icon`, before the title. */
+    sectionIcon?: FormUiClass;
     sectionTitle?: FormUiClass;
     sectionDescription?: FormUiClass;
     /** The "Optional" badge of an optional section with nothing entered. */

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

@@ -1,4 +1,4 @@
-import type { FormValue, FormField, FormFieldCallbackParams, FormOptionItem, FormOptionValue } from '../types/index.js';
+import type { FormValue, FormField, FormFieldCallbackParams, FormOptionItem, FormOptionValue, ResolvedFormOption } from '../types/index.js';
 export interface FormOptionKeys {
     value?: string;
     label?: string;
@@ -9,18 +9,11 @@ export interface FormOptionKeys {
      */
     group?: string;
 }
-export interface ResolvedFormOption {
-    value: FormOptionValue;
-    label: string;
-    description?: string;
-    disabled?: boolean;
-    icon?: string;
-    /** Heading the option is listed under, for the fields that group their options. */
-    group?: string;
-    children?: readonly ResolvedFormOption[];
-    /** True when the option has children that load on demand. */
-    lazy?: boolean;
-}
+export type { ResolvedFormOption } from '../types/index.js';
+/** The one visual an option draws before its label: its icon, else its avatar, else its chip. */
+export type OptionLeading = 'icon' | 'avatar' | 'chip';
+export declare function resolveOptionLeading(option: ResolvedFormOption): OptionLeading | undefined;
+export declare function resolveOptionDescriptionIndent(option: ResolvedFormOption): string | undefined;
 export declare function normalizeOptionItem(option: FormValue, keys?: FormOptionKeys): ResolvedFormOption;
 export declare function normalizeOptionItems(options: readonly FormValue[] | undefined, keys?: FormOptionKeys): ResolvedFormOption[];
 /**
@@ -37,9 +30,40 @@ export declare function readOptionSource(field: FormField): FormValue;
  * `groupKey` maps it. `groupKey: false` opts out.
  */
 export declare function resolveOptionGroupKey(field: FormField): string | undefined;
+export interface OptionGroup<TItem> {
+    /** Stable key of the group: its heading, or an empty string for the options without one. */
+    key: string;
+    /** Heading shown above the options of the group; none for options that declare no group. */
+    heading?: string;
+    /** The group's options, as the mutable list the Nuxt UI groups take. */
+    items: TItem[];
+}
+/**
+ * Lists options under their group headings. Headings follow the order in which they first appear
+ * in `items`, and each keeps its options in their authored order. The options without a group form
+ * one more group with no heading, placed where its first option appears. Without any group the
+ * result is a single headingless group, so an ungrouped list renders as it always did.
+ */
+export declare function groupOptions<TItem extends {
+    group?: string;
+}>(items: readonly TItem[]): readonly OptionGroup<TItem>[];
 export declare const LOAD_MORE_OPTION_VALUE = "__nut:load-more__";
 export declare function isLoadMoreOption(item: FormValue): boolean;
 export declare function appendLoadMoreOption(items: readonly ResolvedFormOption[], show: boolean, label: string): readonly ResolvedFormOption[];
+/** Item of a Nuxt UI menu: an option, or the heading (`type: 'label'`) the menu draws above a group. */
+export type OptionMenuItem = ResolvedFormOption & {
+    type?: 'label';
+};
+/**
+ * Items for the Nuxt UI menu of a select or auto-complete: the options as one flat list, or, when
+ * some options belong to a group, one array per group with a heading item first. Nuxt UI draws
+ * each array as a group and keeps a heading only while its group still has a match for the search.
+ * The load-more row, when shown, is last and belongs to no group.
+ */
+export declare function toMenuItems(options: readonly ResolvedFormOption[], loadMore: {
+    show: boolean;
+    label: string;
+}): OptionMenuItem[] | OptionMenuItem[][];
 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[];