nuxt-ui-tools 1.17.0 → 1.18.0

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

@@ -3,9 +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 { 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";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
@@ -15,7 +17,11 @@ const { fieldProps, form, controlProps, disabled, handleBlur, options } = useFie
   () => props.path,
   { omit: CHOICE_CARD_PROPS }
 );
-const cards = useChoiceCard({ props: () => fieldProps.value, ui: () => controlProps.value.ui });
+const cards = useChoiceCard({
+  kind: "radio",
+  props: () => fieldProps.value,
+  ui: () => controlProps.value.ui
+});
 const model = computed({
   get: () => {
     const value = form.getValue(props.path);
@@ -26,36 +32,60 @@ const model = computed({
   },
   set: (value) => form.setValue(props.path, value)
 });
-const items = computed(() => [...options.items.value]);
+const descriptionByKey = computed(
+  () => new Map(options.items.value.map((item) => [formOptionKey(item.value), item.description]))
+);
+const items = computed(
+  () => options.items.value.map(
+    (item) => cards.compact.value ? { ...item, description: void 0 } : item
+  )
+);
+const groups = computed(() => groupChoiceCardItems(items.value));
+function selectionOf(group) {
+  return group.items.some((item) => item.value === model.value) ? model.value : void 0;
+}
+function select(value) {
+  if (isString(value) || isNumber(value) || isBoolean(value)) model.value = value;
+}
 </script>
 
 <template>
   <FormFieldShell :field="field" :path="path">
-    <URadioGroup
-      v-model="model"
-      v-bind="controlProps"
-      value-key="value"
-      label-key="label"
-      variant="card"
-      :items="items"
-      :orientation="cards.orientation.value"
-      :indicator="cards.indicator.value"
-      :ui="cards.ui.value"
-      :style="cards.style.value"
-      :disabled="disabled"
-      @blur="handleBlur"
-    >
-      <template #label="{ item }">
-        <ChoiceCardLabel
-          :label="item.label"
-          :icon="item.icon"
-          :value="item.value"
-          :tile="cards.tile.value"
-          :mark="cards.mark.value"
-          :selected="model === item.value"
-          :ui="cards.ui.value"
-        />
-      </template>
-    </URadioGroup>
+    <div :class="cards.groupsClass.value">
+      <URadioGroup
+        v-for="(group, index) in groups"
+        :key="group.key"
+        :model-value="selectionOf(group)"
+        v-bind="choiceCardGroupAttrs(controlProps, index)"
+        value-key="value"
+        label-key="label"
+        variant="card"
+        :legend="group.heading"
+        :items="group.items"
+        :orientation="cards.orientation.value"
+        :indicator="cards.indicator.value"
+        :ui="cards.ui.value"
+        :style="cards.style.value"
+        :disabled="disabled"
+        @update:model-value="select"
+        @blur="handleBlur"
+      >
+        <template #label="{ item }">
+          <ChoiceCardLabel
+            :label="item.label"
+            :description="
+  cards.compact.value ? descriptionByKey.get(formOptionKey(item.value)) : void 0
+"
+            :icon="item.icon"
+            :value="item.value"
+            :tile="cards.tile.value"
+            :compact="cards.compact.value"
+            :mark="cards.mark.value"
+            :selected="model === item.value"
+            :ui="cards.ui.value"
+          />
+        </template>
+      </URadioGroup>
+    </div>
   </FormFieldShell>
 </template>

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

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

package/dist/runtime/form/fields/radio-card/config.js

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

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 { FormOptionItem, FormOptionValue, FormOptionsSource } from '../../types/options.js';
-import type { FormChoiceCardProps } from '../choice-card/types.js';
-export interface FormRadioCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'radio-card', TValue | null, TContext, TDeps, FormChoiceCardProps> {
+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 {
     options: FormOptionsSource<TOption, TContext, TDeps, TValue | null>;
 }
 export type RadioCardFieldOutput<TField> = FieldOptionValue<TField> | NullableValue;

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/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
@@ -228,9 +246,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 +265,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 +308,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;
   }

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

@@ -1,8 +1,13 @@
-import type { FormValue, FormFieldCallbackParams, FormOptionItem, FormOptionValue } from '../types/index.js';
+import type { FormValue, FormField, FormFieldCallbackParams, FormOptionItem, FormOptionValue } from '../types/index.js';
 export interface FormOptionKeys {
     value?: string;
     label?: string;
     children?: string;
+    /**
+     * Property holding the heading an option is listed under. Options are not grouped without it:
+     * a `group` property is never read unless it is mapped here.
+     */
+    group?: string;
 }
 export interface ResolvedFormOption {
     value: FormOptionValue;
@@ -10,12 +15,28 @@ export interface ResolvedFormOption {
     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 declare function normalizeOptionItem(option: FormValue, keys?: FormOptionKeys): ResolvedFormOption;
 export declare function normalizeOptionItems(options: readonly FormValue[] | undefined, keys?: FormOptionKeys): ResolvedFormOption[];
+/**
+ * The `options` of a field as authored: its array, function or query source, whether given
+ * directly or inside a `source` property.
+ */
+export declare function readOptionSource(field: FormField): FormValue;
+/**
+ * Property the options of a field hold their heading in, for the field kinds that list options
+ * under headings. The field's `groupKey` names it, read statically from the definition like
+ * `labelKey` and `valueKey`. Without it, options written inline in the schema group by their
+ * `group`, the way a literal option is authored. The records a function, a promise or a query
+ * returns belong to the author's data, so a `group` they happen to carry is not read until
+ * `groupKey` maps it. `groupKey: false` opts out.
+ */
+export declare function resolveOptionGroupKey(field: FormField): string | undefined;
 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[];

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

@@ -1,12 +1,15 @@
+import { createFormFieldInstance } from "./field-instance.js";
 import { isRecord } from "./path.js";
 import { isBoolean, isFunction, isNumber, isString, isUndefined } from "./predicate.js";
 import { resolveFormText } from "./text.js";
+const DEFAULT_GROUP_KEY = "group";
 export function normalizeOptionItem(option, keys = {}) {
   if (isRecord(option)) {
     const rawValue = readOptionProperty(option, keys.value ?? "value");
     const fallbackValue = isUndefined(rawValue) ? option.key : rawValue;
     const rawChildren = readOptionProperty(option, keys.children ?? "children");
     const rawDescription = readOptionProperty(option, "description");
+    const rawGroup = keys.group ? readOptionProperty(option, keys.group) : void 0;
     const children = Array.isArray(rawChildren) ? rawChildren.map((child) => normalizeOptionItem(child, keys)) : void 0;
     const lazy = option.isLeaf === false || option.hasChildren === true;
     const value = normalizeOptionValue(fallbackValue);
@@ -14,6 +17,7 @@ export function normalizeOptionItem(option, keys = {}) {
     const normalized = {
       description: isFormText(rawDescription) ? resolveFormText(rawDescription) : void 0,
       disabled: option.disabled === true,
+      group: isFormText(rawGroup) ? resolveFormText(rawGroup) : void 0,
       icon: isString(rawIcon) ? rawIcon : void 0,
       label: resolveFormText(readOptionProperty(option, keys.label ?? "label")) ?? String(value),
       value
@@ -36,6 +40,17 @@ export function normalizeOptionItem(option, keys = {}) {
 export function normalizeOptionItems(options, keys = {}) {
   return (options ?? []).map((option) => normalizeOptionItem(option, keys));
 }
+export function readOptionSource(field) {
+  const options = Object.getOwnPropertyDescriptor(field, "options")?.value;
+  return isRecord(options) && "source" in options ? options.source : options;
+}
+export function resolveOptionGroupKey(field) {
+  if (!createFormFieldInstance(field).capability.has("optionGroups")) return void 0;
+  const mapped = Object.getOwnPropertyDescriptor(field, "groupKey")?.value;
+  if (mapped === false) return void 0;
+  if (isString(mapped) && mapped) return mapped;
+  return Array.isArray(readOptionSource(field)) ? DEFAULT_GROUP_KEY : void 0;
+}
 export const LOAD_MORE_OPTION_VALUE = "__nut:load-more__";
 export function isLoadMoreOption(item) {
   return isRecord(item) && item.value === LOAD_MORE_OPTION_VALUE;

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

@@ -0,0 +1,21 @@
+import type { FormPageSurface, FormValue } from '../types/index.js';
+/**
+ * What a surface sets on the parts of a form page it restyles. These are the default classes of
+ * each slot: the `FormPageUi` slots merge over them.
+ */
+export interface FormPageSurfaceClasses {
+    /** Background the sections sit on. */
+    root: string;
+    /** Gap between the sections. */
+    sections: string;
+    /** The box of a card, or the spacing, hairline, and modified marker of a plain section. */
+    section: string;
+    /** Where the description sits against the title. */
+    sectionDescription: string;
+    /** Placeholder shown while the schema context loads. */
+    sectionSkeleton: string;
+}
+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;
+export declare function getFormPageSurfaceClasses(surface: FormPageSurface): FormPageSurfaceClasses;

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

@@ -0,0 +1,27 @@
+import { isString } from "./predicate.js";
+export const DEFAULT_FORM_PAGE_SURFACE = "card";
+const FORM_PAGE_SURFACES = {
+  card: {
+    root: "bg-muted",
+    section: "gap-[18px] rounded-xl border border-default bg-default px-5 pt-5 pb-6 transition-[border-color,box-shadow] duration-200 @3xl/form-page:px-6 @3xl/form-page:pt-[22px] data-[dirty]:border-primary data-[dirty]:ring-4 data-[dirty]:ring-primary/20 data-[dirty]:ring-inset",
+    sectionDescription: "order-last basis-full @3xl/form-page:order-none @3xl/form-page:basis-auto",
+    sectionSkeleton: "rounded-xl border border-default bg-default px-6 pt-[22px] pb-6",
+    sections: "gap-[18px]"
+  },
+  plain: {
+    root: "bg-default",
+    section: "relative gap-[18px] border-t border-default py-8 first:border-t-0 first:pt-0 last:pb-0 before:pointer-events-none before:absolute before:inset-y-8 before:-start-3 before:w-0.5 before:rounded-full before:transition-colors first:before:top-0 last:before:bottom-0 data-[dirty]:before:bg-primary",
+    sectionDescription: "order-last basis-full",
+    sectionSkeleton: "border-t border-default py-8 first:border-t-0 first:pt-0",
+    sections: "gap-0"
+  }
+};
+export function resolveFormPageSurface(value) {
+  return isFormPageSurface(value) ? value : DEFAULT_FORM_PAGE_SURFACE;
+}
+export function getFormPageSurfaceClasses(surface) {
+  return FORM_PAGE_SURFACES[surface];
+}
+function isFormPageSurface(value) {
+  return isString(value) && Object.hasOwn(FORM_PAGE_SURFACES, value);
+}

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

@@ -1,10 +1,30 @@
-import type { FormObject, FormPageSectionEntry, FormPageSectionState, FormRuntime, FormValue } from '../types/index.js';
+import type { FormObject, FormPageSectionEntry, FormPageSectionState, FormPageSectionStatus, FormRuntime, FormValue } from '../types/index.js';
 /** Pairs each section of a page schema with the card `defineFormPageSchema` generated for it. */
 export declare function getFormPageSections(schema: FormValue): readonly FormPageSectionEntry[];
 /** Resolved heading of the page navigation. */
 export declare function getFormPageNavigationTitle(schema: FormValue): string | undefined;
+/**
+ * Number of visible sections the navigation needs to show. Zero, the default, shows it whatever
+ * the number of sections; anything that is not a count above one means the same.
+ */
+export declare function getFormPageNavigationMinSections(schema: FormValue): number;
 /** True while the section's `condition` lets it render. */
 export declare function isFormPageSectionVisible(entry: FormPageSectionEntry, runtime: FormRuntime): boolean;
+/**
+ * Where a section stands, from what it shows and what it still misses. An optional section nothing
+ * was entered in is `optional`, not `pending`: the user has nothing to do there.
+ */
+export declare function resolveFormPageSectionStatus(params: {
+    /** The section shows a validation error, which needs the user to leave a field or submit. */
+    invalid: boolean;
+    /** Number of required fields without a value. */
+    missing: number;
+    optional: boolean;
+    /** The user entered a value, or the form input brought one. Only read for an optional section. */
+    provided: boolean;
+}): FormPageSectionStatus;
+/** True while the section keeps the form from being submitted: the sections left to complete. */
+export declare function isFormPageSectionBlocking(section: Pick<FormPageSectionState, 'status'>): boolean;
 /**
  * Live state of one visible section: what it still misses, whether it shows errors, and what
  * changed since the baseline.

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

@@ -13,6 +13,12 @@ import {
   resolveRequired
 } from "./state.js";
 import { resolveFormText } from "./text.js";
+const BLOCKS_SUBMIT = {
+  complete: false,
+  invalid: true,
+  optional: false,
+  pending: true
+};
 export function getFormPageSections(schema) {
   if (!isRecord(schema) || !Array.isArray(schema.sections)) {
     return [];
@@ -30,9 +36,25 @@ export function getFormPageNavigationTitle(schema) {
   const { title } = schema.navigation;
   return isFormText(title) ? resolveFormText(title) : void 0;
 }
+export function getFormPageNavigationMinSections(schema) {
+  if (!isRecord(schema) || !isRecord(schema.navigation)) {
+    return 0;
+  }
+  const { minSections } = schema.navigation;
+  return isNumber(minSections) && minSections > 1 ? Math.trunc(minSections) : 0;
+}
 export function isFormPageSectionVisible(entry, runtime) {
   return !hasCondition(entry.card) || runtime.shouldRender(entry.card, [entry.card.key]);
 }
+export function resolveFormPageSectionStatus(params) {
+  if (params.invalid) return "invalid";
+  if (params.missing > 0) return "pending";
+  if (params.optional && !params.provided) return "optional";
+  return "complete";
+}
+export function isFormPageSectionBlocking(section) {
+  return BLOCKS_SUBMIT[section.status];
+}
 export function resolveFormPageSectionState(params) {
   const { entry, runtime } = params;
   const leaves = collectVisibleLeaves(entry.section.fields, [], runtime);
@@ -43,7 +65,7 @@ export function resolveFormPageSectionState(params) {
   const required = params.requiredEnforced ? leaves.filter((leaf) => isRequiredLeaf(leaf, runtime)) : [];
   const missing = required.filter((leaf) => isEmptyValue(runtime.getValue(leaf.path))).length;
   const optional = entry.section.optional ?? required.every((leaf) => leaf.item);
-  const filled = !optional || leaves.some((leaf) => isProvided(leaf, runtime, dirtyPaths, params.input));
+  const provided = optional && leaves.some((leaf) => isProvided(leaf, runtime, dirtyPaths, params.input));
   return {
     description: resolveFormText(entry.section.description),
     dirty: dirtyPaths.length > 0,
@@ -53,7 +75,7 @@ export function resolveFormPageSectionState(params) {
     label: resolveFormText(entry.section.label) ?? entry.section.key,
     missing,
     optional,
-    status: invalid ? "invalid" : missing === 0 && filled ? "complete" : "pending"
+    status: resolveFormPageSectionStatus({ invalid, missing, optional, provided })
   };
 }
 function collectVisibleLeaves(fields, parentPath, runtime, item = false) {