nuxt-ui-tools 1.17.1 → 1.19.0

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/field-base.d.ts

@@ -53,6 +53,12 @@ export interface FormStatefulFieldBase<TType extends FormFieldType, TValue, TCon
     props?: FormFieldProps<TProps, TContext, TDeps>;
     /** Disables the field without removing it from form state. */
     disabled?: FormFieldCallback<boolean, TContext, TDeps, TValue>;
+    /**
+     * Why the field is disabled, shown under the control with a lock icon only while the `disabled`
+     * callback holds. Static text, or a callback receiving `{ ctx, deps, api }` that returns nothing
+     * when no reason applies.
+     */
+    disabledReason?: FormText | FormFieldCallback<FormText | undefined, TContext, TDeps, TValue>;
     /** Controls whether the field is rendered. Hidden fields can still be part of form state. */
     condition?: FormFieldCallback<boolean, TContext, TDeps, TValue>;
     /** Validation behavior for this field. */

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

@@ -21,6 +21,8 @@ export interface FormFieldKindDefinition<TType extends FormFieldType = FormField
     /** Whether the field owns option resolution. */
     options?: {
         enabled: boolean;
+        /** Whether the field lists its options under headings read from a property of the options. */
+        groups?: boolean;
     };
     /** Whether the field owns file upload work. */
     upload?: {
@@ -33,4 +35,4 @@ export interface FormFieldKindDefinition<TType extends FormFieldType = FormField
 }
 export type FormFieldKindState = FormFieldKindDefinition['state'];
 export type FormFieldState = FormFieldKindState;
-export type FormFieldCapability = 'value' | 'children' | 'label' | 'description' | 'hint' | 'layout' | 'itemLayout' | 'containerLayout' | 'options' | 'upload' | 'validation' | 'transform' | 'submit';
+export type FormFieldCapability = 'value' | 'children' | 'label' | 'description' | 'hint' | 'layout' | 'itemLayout' | 'containerLayout' | 'options' | 'optionGroups' | 'upload' | 'validation' | 'transform' | 'submit';

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

@@ -54,6 +54,7 @@ export type { FormAutoCompleteField } from '../fields/auto-complete/types.js';
 export type { FormButtonField } from '../fields/button/types.js';
 export type { FormCardField } from '../fields/card/types.js';
 export type { FormCheckboxCardField } from '../fields/checkbox-card/types.js';
+export type { FormChoiceCardDensity, FormChoiceCardOption, FormChoiceCardOptionItem, FormChoiceCardProps, } from '../fields/choice-card/types.js';
 export type { FormCheckboxField } from '../fields/checkbox/types.js';
 export type { FormCheckboxGroupField } from '../fields/checkbox-group/types.js';
 export type { FormColorPickerField } from '../fields/color-picker/types.js';

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

@@ -41,10 +41,10 @@ export interface FormPageSection<TContext = NonNullable<unknown>, TFields extend
     /** Supporting copy next to the title. */
     description?: FormText;
     /**
-     * Shows the section as optional and leaves it out of the sections left to complete. A section
-     * without a required field is optional already; set this when its required fields are filled
-     * by their defaults and the user has nothing to do there. Set `false` to keep a section
-     * required when its only required fields are the cells of array rows.
+     * 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
+     * required fields are filled by their defaults and the user has nothing to do there. Set
+     * `false` to keep a section required when its only required fields are the cells of array rows.
      */
     optional?: boolean;
     /** Grid of the section's fields, merged over the schema `layout`. */
@@ -62,6 +62,12 @@ export interface FormPageSection<TContext = NonNullable<unknown>, TFields extend
 export interface FormPageNavigationConfig {
     /** Heading above the entries, e.g. `'Création'`. Accepts a function to translate it. */
     title?: FormText;
+    /**
+     * Shows the navigation only when the page has at least this many visible sections. Below it,
+     * the page is one focused column of content: two short sections gain nothing from a side
+     * navigation. Without it, the navigation always shows.
+     */
+    minSections?: number;
 }
 /**
  * Schema accepted by `defineFormPageSchema`: a form schema whose `sections` replace `fields`.
@@ -142,12 +148,18 @@ export interface FormPageScrollOptions {
 /**
  * Where a section stands:
  *
- * - `invalid`: it shows at least one validation error
+ * - `invalid`: it shows at least one validation error, which only appears once the user left the
+ *   field or tried to submit, so a section nobody touched is never `invalid`
+ * - `pending`: a required field has no value yet, in a required section, or in an optional one
+ *   the user started and left incomplete
  * - `complete`: nothing required is missing and it shows no error; an optional section also
  *   needs a value, entered by the user or provided by the form input
- * - `pending`: anything else
+ * - `optional`: an optional section without any entered value, where there is nothing to do
+ *
+ * `invalid` and `pending` are the sections that keep the form from being submitted, and the only
+ * ones the navigation counts as left to complete.
  */
-export type FormPageSectionStatus = 'invalid' | 'complete' | 'pending';
+export type FormPageSectionStatus = 'invalid' | 'pending' | 'complete' | 'optional';
 /**
  * Live state of a visible section, as the page navigation and section slots receive it.
  */
@@ -167,7 +179,7 @@ export interface FormPageSectionState {
     optional: boolean;
     /** Number of required fields without a value, the fields of array items included. */
     missing: number;
-    /** Summary of the section's requirements, see `FormPageSectionStatus`. */
+    /** Where the section stands, see `FormPageSectionStatus`. */
     status: FormPageSectionStatus;
     /** True when a value of the section differs from the form's baseline. */
     dirty: boolean;

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

@@ -44,6 +44,8 @@ export interface FormFieldUi {
     hint?: FormUiClass;
     labelExtra?: FormUiClass;
     help?: FormUiClass;
+    disabledReason?: FormUiClass;
+    disabledReasonIcon?: FormUiClass;
     body?: FormUiClass;
     content?: FormUiClass;
     pending?: FormUiClass;
@@ -191,11 +193,27 @@ export interface FormOverlayUi {
     overlay?: FormUiClass;
     content?: FormUiClass;
 }
+/**
+ * How the sections of a form page are drawn:
+ *
+ * - `card`: each section is a bordered card on the gray canvas of the page (default)
+ * - `plain`: no box. A section is its heading, description, and fields on the page itself,
+ *   separated from the next by spacing and a hairline
+ */
+export type FormPageSurface = 'card' | 'plain';
+/**
+ * The `page` part of the form UI config: the surface of the sections and the `ui` slots of the
+ * page parts. Both follow the usual layering: app config, then schema `ui`, then the `ui` prop.
+ */
+export interface FormPageUiConfig extends FormUiPartConfig<FormPageUi> {
+    /** Defaults to `card`. */
+    surface?: FormPageSurface;
+}
 /**
  * Slots of a form page and its parts. Data attributes carry the live state, so a slot can
  * restyle one state: `data-active` on the current navigation entry, `data-state`
- * (`complete`, `invalid`, `pending`) on entries and indicators, `data-dirty` on modified
- * sections and entries.
+ * (`complete`, `invalid`, `pending`, `optional`) on entries, indicators, and sections,
+ * `data-dirty` on modified sections and entries.
  *
  * Sections and the navigation stay below the pinned header: the page gives each section its
  * `scroll-margin-top` and the navigation the `--nut-form-page-header` variable (the header's
@@ -209,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;
@@ -228,9 +251,10 @@ export interface FormPageUi {
     navigationIndicator?: FormUiClass;
     /** Check of a complete section in the indicator. */
     navigationIndicatorIcon?: FormUiClass;
-    /** Dot in the indicator of the current section while it is pending. */
+    /** Dot in the indicator of the current section while it is pending or optional. */
     navigationIndicatorMarker?: FormUiClass;
     navigationLabel?: FormUiClass;
+    /** The "Optional" tag of an entry whose optional section has nothing entered. */
     navigationOptional?: FormUiClass;
     navigationDirty?: FormUiClass;
     /** Wrapper under the entries, whose padding insets the summary. */
@@ -246,6 +270,7 @@ export interface FormPageUi {
     sectionHeader?: FormUiClass;
     sectionTitle?: FormUiClass;
     sectionDescription?: FormUiClass;
+    /** The "Optional" badge of an optional section with nothing entered. */
     sectionOptional?: FormUiClass;
     sectionActions?: FormUiClass;
     sectionReset?: FormUiClass;
@@ -288,5 +313,5 @@ export interface FormUiConfig {
     drawer?: FormUiPartConfig<FormOverlayUi>;
     fullscreen?: FormUiPartConfig<FormOverlayUi>;
     /** Form page rendered by `FormPage` and its parts. */
-    page?: FormUiPartConfig<FormPageUi>;
+    page?: FormPageUiConfig;
 }

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

@@ -0,0 +1,11 @@
+import type { FormField, FormFieldCallbackParams } from '../types/index.js';
+/**
+ * Whether the field's authored `disabled` callback holds. Engine-driven disabling (a pending form
+ * action, options still loading) is separate: it explains itself, so it never carries a reason.
+ */
+export declare function isFieldDisabledByCallback(field: FormField, params: FormFieldCallbackParams): boolean;
+/**
+ * The reason to show under a field while its `disabled` callback holds: the authored
+ * `disabledReason` text, or nothing when the field is enabled or the author gave no reason.
+ */
+export declare function resolveFieldDisabledReason(field: FormField, params: FormFieldCallbackParams): string | undefined;

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

@@ -0,0 +1,11 @@
+import { isFunction } from "./predicate.js";
+import { resolveFieldText } from "./text.js";
+export function isFieldDisabledByCallback(field, params) {
+  const disabled = Object.getOwnPropertyDescriptor(field, "disabled")?.value;
+  return isFunction(disabled) ? disabled(params) === true : false;
+}
+export function resolveFieldDisabledReason(field, params) {
+  if (!isFieldDisabledByCallback(field, params)) return void 0;
+  const reason = Object.getOwnPropertyDescriptor(field, "disabledReason")?.value;
+  return resolveFieldText(reason, params) || void 0;
+}

package/dist/runtime/form/utils/field-instance.js

@@ -67,6 +67,9 @@ export function fieldKindHas(kind, capability) {
   if (capability === "options") {
     return kind.options?.enabled === true;
   }
+  if (capability === "optionGroups") {
+    return kind.options?.groups === true;
+  }
   if (capability === "upload") {
     return kind.upload?.enabled === true;
   }