nuxt-ui-tools 1.18.0 → 1.19.0

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/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;

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[];

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

@@ -3,7 +3,32 @@ import { isRecord } from "./path.js";
 import { isBoolean, isFunction, isNumber, isString, isUndefined } from "./predicate.js";
 import { resolveFormText } from "./text.js";
 const DEFAULT_GROUP_KEY = "group";
+const CHIP_COLORS = [
+  "primary",
+  "secondary",
+  "success",
+  "info",
+  "warning",
+  "error",
+  "neutral"
+];
+export function resolveOptionLeading(option) {
+  if (option.icon) return "icon";
+  if (option.avatar) return "avatar";
+  if (option.chip) return "chip";
+  return void 0;
+}
+const DESCRIPTION_INDENT = {
+  avatar: "ps-8",
+  chip: "ps-6",
+  icon: "ps-6"
+};
+export function resolveOptionDescriptionIndent(option) {
+  const leading = resolveOptionLeading(option);
+  return leading ? DESCRIPTION_INDENT[leading] : void 0;
+}
 export function normalizeOptionItem(option, keys = {}) {
+  const item = isFormOptionItem(option) ? option : void 0;
   if (isRecord(option)) {
     const rawValue = readOptionProperty(option, keys.value ?? "value");
     const fallbackValue = isUndefined(rawValue) ? option.key : rawValue;
@@ -14,12 +39,17 @@ export function normalizeOptionItem(option, keys = {}) {
     const lazy = option.isLeaf === false || option.hasChildren === true;
     const value = normalizeOptionValue(fallbackValue);
     const rawIcon = readOptionProperty(option, "icon");
+    const rawSuffix = readOptionProperty(option, "suffix");
     const normalized = {
+      avatar: normalizeOptionAvatar(readOptionProperty(option, "avatar")),
+      chip: normalizeOptionChip(readOptionProperty(option, "chip")),
       description: isFormText(rawDescription) ? resolveFormText(rawDescription) : void 0,
       disabled: option.disabled === true,
       group: isFormText(rawGroup) ? resolveFormText(rawGroup) : void 0,
       icon: isString(rawIcon) ? rawIcon : void 0,
+      item,
       label: resolveFormText(readOptionProperty(option, keys.label ?? "label")) ?? String(value),
+      suffix: isFormText(rawSuffix) ? resolveFormText(rawSuffix) : void 0,
       value
     };
     if (children) {
@@ -33,10 +63,27 @@ export function normalizeOptionItem(option, keys = {}) {
     return normalized;
   }
   return {
+    item,
     label: String(option),
     value: normalizeOptionValue(option)
   };
 }
+function isFormOptionItem(value) {
+  return isOptionValue(value) || isRecord(value);
+}
+function normalizeOptionAvatar(raw) {
+  if (!isRecord(raw)) return void 0;
+  const { alt, src, text } = raw;
+  return {
+    alt: isString(alt) ? alt : void 0,
+    src: isString(src) ? src : void 0,
+    text: isString(text) ? text : void 0
+  };
+}
+function normalizeOptionChip(raw) {
+  if (!isRecord(raw)) return void 0;
+  return { color: CHIP_COLORS.find((color) => color === raw.color) };
+}
 export function normalizeOptionItems(options, keys = {}) {
   return (options ?? []).map((option) => normalizeOptionItem(option, keys));
 }
@@ -51,6 +98,17 @@ export function resolveOptionGroupKey(field) {
   if (isString(mapped) && mapped) return mapped;
   return Array.isArray(readOptionSource(field)) ? DEFAULT_GROUP_KEY : void 0;
 }
+export function groupOptions(items) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = item.group?.trim() ?? "";
+    const members = groups.get(key);
+    if (members) members.push(item);
+    else groups.set(key, [item]);
+  }
+  if (groups.size === 0) return [{ items: [], key: "" }];
+  return [...groups].map(([key, members]) => ({ heading: key || void 0, items: members, key }));
+}
 export const LOAD_MORE_OPTION_VALUE = "__nut:load-more__";
 export function isLoadMoreOption(item) {
   return isRecord(item) && item.value === LOAD_MORE_OPTION_VALUE;
@@ -61,6 +119,19 @@ export function appendLoadMoreOption(items, show, label) {
   }
   return [...items, { disabled: true, label, value: LOAD_MORE_OPTION_VALUE }];
 }
+function menuHeading(heading) {
+  return { label: heading, type: "label", value: "" };
+}
+export function toMenuItems(options, loadMore) {
+  const groups = groupOptions(options);
+  if (!groups.some((group) => group.heading)) {
+    return [...appendLoadMoreOption(options, loadMore.show, loadMore.label)];
+  }
+  const nested = groups.map(
+    (group) => group.heading ? [menuHeading(group.heading), ...group.items] : group.items
+  );
+  return loadMore.show ? [...nested, [...appendLoadMoreOption([], true, loadMore.label)]] : nested;
+}
 export function formOptionKey(value) {
   const type = isString(value) ? "string" : isNumber(value) ? "number" : isBoolean(value) ? "boolean" : "unknown";
   return `${type}:${String(value)}`;

package/dist/runtime/form/utils/page-surface.d.ts

@@ -15,6 +15,11 @@ export interface FormPageSurfaceClasses {
     /** Placeholder shown while the schema context loads. */
     sectionSkeleton: string;
 }
+/**
+ * The centered column of a page without a navigation. The body and the row of the header share
+ * it, so both start and end on the same edges, padding included.
+ */
+export declare const FORM_PAGE_COLUMN = "mx-auto w-full max-w-[816px]";
 export declare const DEFAULT_FORM_PAGE_SURFACE: FormPageSurface;
 /** The surface a page draws its sections with, `card` unless the config names a known one. */
 export declare function resolveFormPageSurface(value: FormValue): FormPageSurface;

package/dist/runtime/form/utils/page-surface.js

@@ -1,4 +1,5 @@
 import { isString } from "./predicate.js";
+export const FORM_PAGE_COLUMN = "mx-auto w-full max-w-[816px]";
 export const DEFAULT_FORM_PAGE_SURFACE = "card";
 const FORM_PAGE_SURFACES = {
   card: {

package/dist/runtime/spreadsheet/components/internal/spreadsheet-import-column-row.d.vue.ts

@@ -6,12 +6,12 @@ type __VLS_Props = {
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     reset: () => any;
-    assign: (header: number) => any;
     ignore: () => any;
+    assign: (header: number) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onReset?: (() => any) | undefined;
-    onAssign?: ((header: number) => any) | undefined;
     onIgnore?: (() => any) | undefined;
+    onAssign?: ((header: number) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/spreadsheet/components/internal/spreadsheet-import-column-row.vue.d.ts

@@ -6,12 +6,12 @@ type __VLS_Props = {
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     reset: () => any;
-    assign: (header: number) => any;
     ignore: () => any;
+    assign: (header: number) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
     onReset?: (() => any) | undefined;
-    onAssign?: ((header: number) => any) | undefined;
     onIgnore?: (() => any) | undefined;
+    onAssign?: ((header: number) => any) | undefined;
 }>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;