nuxt-ui-tools 1.2.0 → 1.4.0

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

@@ -1,10 +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';
-export interface FormRadioCardProps {
-    orientation?: 'horizontal' | 'vertical';
-}
-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, FormRadioCardProps> {
+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> {
     options: FormOptionsSource<TOption, TContext, TDeps, TValue | null>;
 }
 export type RadioCardFieldOutput<TField> = FieldOptionValue<TField> | NullableValue;

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

@@ -1,4 +1,4 @@
-export { defineFormField, defineFormFields, defineFormSchema } from './schema/index.js';
+export { defineFormField, defineFormFields, defineFormPageSchema, defineFormPageSection, defineFormSchema, } from './schema/index.js';
 export { useForm } from './composables/use-form.js';
 export { useFormUi } from './composables/use-form-ui.js';
 export { provideFormApi, useFormApi } from './composables/use-form-api.js';

package/dist/runtime/form/index.js

@@ -1,4 +1,10 @@
-export { defineFormField, defineFormFields, defineFormSchema } from "./schema/index.js";
+export {
+  defineFormField,
+  defineFormFields,
+  defineFormPageSchema,
+  defineFormPageSection,
+  defineFormSchema
+} from "./schema/index.js";
 export { useForm } from "./composables/use-form.js";
 export { useFormUi } from "./composables/use-form-ui.js";
 export { provideFormApi, useFormApi } from "./composables/use-form-api.js";

package/dist/runtime/form/schema/index.d.ts

@@ -81,4 +81,4 @@ export declare function defineFormField<const TField extends FormField>(field: T
  * Defines a reusable field group while preserving literal inference.
  */
 export declare function defineFormFields<const TFields extends readonly FormField[]>(fields: TFields): TFields;
-export {};
+export { defineFormPageSchema, defineFormPageSection } from './page.js';

package/dist/runtime/form/schema/index.js

@@ -7,3 +7,4 @@ export function defineFormField(field) {
 export function defineFormFields(fields) {
   return fields;
 }
+export { defineFormPageSchema, defineFormPageSection } from "./page.js";

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

@@ -0,0 +1,50 @@
+import type { FormContextData, FormContextDefinition, FormPageSchema, FormPageSchemaInput, FormPageSection } from '../types/index.js';
+/**
+ * Defines one section of a form page while preserving literal field inference, so each section
+ * can live in its own file as a plain typed function.
+ *
+ * @example
+ * ```ts
+ * export function billingSection({ hasActiveContract }: { hasActiveContract: boolean }) {
+ *   return defineFormPageSection({
+ *     key: 'billing',
+ *     label: () => t('account.sections.billing'),
+ *     fields: [
+ *       {
+ *         key: 'vtestId',
+ *         type: 'text',
+ *         label: 'VTEST ID',
+ *         // `accountType` belongs to another section: a page is one form, one state.
+ *         dependencies: ['accountType'],
+ *         required: ({ deps }) => hasActiveContract || 'accountType' in deps,
+ *       },
+ *     ],
+ *   })
+ * }
+ * ```
+ */
+export declare function defineFormPageSection<const TSection extends FormPageSection>(section: TSection): TSection;
+/**
+ * Defines a form page: one form whose fields are grouped in `sections`. Each section becomes a
+ * card of the page and an entry of its navigation; render it with `<UiFormPage :form />`.
+ *
+ * The result is a normal form schema. Its `fields` are the cards generated from the sections,
+ * so `useForm`, validation, cross-section dependencies, and the typed `formData` work as for any
+ * schema, and the same schema opens in a modal or drawer as a stack of cards.
+ *
+ * @example
+ * ```ts
+ * export function accountFormSchema({ account }: { account?: Account } = {}) {
+ *   return defineFormPageSchema({
+ *     header: { title: () => t(account ? 'account.edit' : 'account.create') },
+ *     controls: { dirtyCheck: Boolean(account) },
+ *     navigation: { title: () => t('account.sections.title') },
+ *     sections: [accountTypeSection(), identitySection(), billingSection({ hasActiveContract: false })],
+ *   })
+ * }
+ * ```
+ */
+export declare function defineFormPageSchema<const TContext extends FormContextDefinition, const TSections extends readonly FormPageSection<FormContextData<NoInfer<TContext>>>[]>(schema: FormPageSchemaInput<TContext, TSections> & {
+    context: TContext;
+}): FormPageSchema<FormPageSchemaInput<TContext, TSections>>;
+export declare function defineFormPageSchema<const TSections extends readonly FormPageSection<FormContextData<undefined>>[]>(schema: FormPageSchemaInput<undefined, TSections>): FormPageSchema<FormPageSchemaInput<undefined, TSections>>;

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

@@ -0,0 +1,25 @@
+import { isRecord } from "../utils/path.js";
+export function defineFormPageSection(section) {
+  return section;
+}
+export function defineFormPageSchema(schema) {
+  if (!isRecord(schema) || !Array.isArray(schema.sections)) {
+    return schema;
+  }
+  return { ...schema, fields: schema.sections.filter(isRecord).map(toSectionCard) };
+}
+const CARD_PROPERTIES = ["condition", "dependencies", "description"];
+function toSectionCard(section) {
+  const card = {
+    fields: section.fields,
+    key: section.key,
+    label: section.label,
+    type: "card"
+  };
+  for (const property of CARD_PROPERTIES) {
+    if (section[property] !== void 0) {
+      card[property] = section[property];
+    }
+  }
+  return card;
+}

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

@@ -15,6 +15,7 @@ export type * from './layout';
 export type * from './options';
 export type * from './options-runtime';
 export type * from './overlay';
+export type * from './page';
 export type * from './output';
 export type * from './runtime';
 export type * from './schema';

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

@@ -1,4 +1,4 @@
-import type { RemoteCursorOptionsPage, RemoteOptionsPage, RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
+import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { FormValue } from './/index.js';
 import type { FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
@@ -68,12 +68,6 @@ export interface FormOptionConfig<TOption, TContext = NonNullable<unknown>, TDep
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
-/** @deprecated Use `RemoteOptionsPage` from `#ui-tools/shared`. Kept for public type compatibility. */
-export type FormRemoteOptionsPage<TOption> = RemoteOptionsPage<TOption>;
-/** @deprecated Use `RemoteCursorOptionsPage` from `#ui-tools/shared`. Kept for public type compatibility. */
-export type FormRemoteCursorOptionsPage<TOption> = RemoteCursorOptionsPage<TOption>;
-/** @deprecated Use `RemoteOptionsResult` from `#ui-tools/shared`. Kept for public type compatibility. */
-export type FormRemoteOptionsResult<TOption> = RemoteOptionsResult<TOption>;
 export interface FormRemoteOptionsRequest<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue, TOption = FormValue> extends FormFieldCallbackParams<TContext, TDeps, TValue, TOption> {
     /** Current debounced search term. Empty when the menu lists unfiltered options. */
     search: string;
@@ -87,10 +81,6 @@ export interface FormRemoteSelectedRequest<TContext = NonNullable<unknown>, TDep
     values: readonly FormOptionValue[];
 }
 export type FormRemoteSource<TResult> = FormQueryOptions<TResult> | Promise<TResult>;
-/** @deprecated Use `RemoteOptionsPagination` from `#ui-tools/shared`. Kept for public type compatibility. */
-export type FormRemotePagination = RemoteOptionsPagination;
-/** @deprecated Use `RemoteOptionsSearch` from `#ui-tools/shared`. Kept for public type compatibility. */
-export type FormRemoteSearch = RemoteOptionsSearch;
 /**
  * Remote option configuration: server-side search, pagination, and selected-value hydration.
  */

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

@@ -0,0 +1,172 @@
+import type { FormValue } from './/index.js';
+import type { FormAction } from './actions.js';
+import type { FormApi, FormSubmitHandler } from './api.js';
+import type { FormFieldCallback } from './callbacks.js';
+import type { FormContextData, FormContextDefinition } from './context.js';
+import type { FormField } from './field.js';
+import type { FormLayoutConfig } from './layout.js';
+import type { FormControlsConfig, FormDrawerConfig, FormFullscreenConfig, FormHeaderConfig, FormModalConfig } from './schema.js';
+import type { FormUiConfig } from './ui.js';
+import type { FormText } from './utils.js';
+/**
+ * One section of a form page: a card in the page and an entry in its navigation.
+ *
+ * Every text accepts a function, so it can be translated:
+ * `label: () => t('account.sections.identity')`.
+ *
+ * @example
+ * ```ts
+ * export function identitySection() {
+ *   return defineFormPageSection({
+ *     key: 'identity',
+ *     label: 'Identity',
+ *     description: 'display name, legal entity and official identifiers',
+ *     fields: [
+ *       { key: 'name', type: 'text', label: 'Name', required: true },
+ *       { key: 'legalEntity', type: 'text', label: 'Legal entity', required: true },
+ *     ],
+ *   })
+ * }
+ * ```
+ */
+export interface FormPageSection<TContext = NonNullable<unknown>, TFields extends readonly FormField<TContext>[] = readonly FormField<TContext>[]> {
+    /**
+     * Names the section: its navigation entry, its scroll target, and the URL hash that opens the
+     * page on it (`#identity`). Also used as the section element's `id`, so keep it unique on the
+     * page. It does not prefix the keys of the section's fields.
+     */
+    key: string;
+    /** Title on the section card and in the navigation. */
+    label: FormText;
+    /** 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.
+     */
+    optional?: boolean;
+    /** Grid of the section's fields, merged over the schema `layout`. */
+    layout?: FormLayoutConfig;
+    /** Raw dependency paths read before evaluating `condition`. */
+    dependencies?: readonly (string | readonly [string, string])[];
+    /** Hides the section, its navigation entry, and its fields while it returns `false`. */
+    condition?: FormFieldCallback<boolean, TContext>;
+    /** Fields of the section. They write at the form root, as if the section were not there. */
+    fields: TFields;
+}
+/**
+ * Side navigation of a form page. Its entries are the page sections.
+ */
+export interface FormPageNavigationConfig {
+    /** Heading above the entries, e.g. `'Création'`. Accepts a function to translate it. */
+    title?: FormText;
+}
+/**
+ * Schema accepted by `defineFormPageSchema`: a form schema whose `sections` replace `fields`.
+ */
+export interface FormPageSchemaInput<TContext extends FormContextDefinition | undefined, TSections extends readonly FormPageSection<FormContextData<TContext>>[]> {
+    /** Stable key used by persistence, diagnostics, and test selectors. */
+    formKey?: string;
+    /** Page heading: `title`, `description`, and the `eyebrow` above the title. */
+    header?: FormHeaderConfig;
+    /** Form-scoped data sources exposed to fields as `ctx`. */
+    context?: TContext;
+    /** Default grid of every section. */
+    layout?: FormLayoutConfig;
+    /** Form-scoped presentation overrides, merged after app defaults. */
+    ui?: FormUiConfig;
+    /** Runtime lifecycle and validation controls. `dirtyCheck` rings the modified sections. */
+    controls?: FormControlsConfig;
+    /** Modal-shell sizing, used when the same schema opens in a modal. */
+    modal?: FormModalConfig;
+    /** Drawer-shell sizing, used when the same schema opens in a drawer. */
+    drawer?: FormDrawerConfig;
+    /** Fullscreen-shell behavior, used when the same schema opens fullscreen. */
+    fullscreen?: FormFullscreenConfig;
+    /** Page actions. Omit to render the built-in submit action. */
+    actions?: readonly FormAction[];
+    /** Runs after validation and before the external submit handler. Return `false` to cancel submit. */
+    onBeforeSubmit?: FormSubmitHandler<FormValue, never>;
+    /** Submit lifecycle hook. */
+    submit?: (params: {
+        value: FormValue;
+        api: FormApi;
+        ctx: FormContextData<TContext>;
+    }) => Promise<void> | void;
+    /** Side navigation of the page. */
+    navigation?: FormPageNavigationConfig;
+    /** Sections of the page, in navigation order. */
+    sections: TSections;
+}
+/**
+ * Card field generated from a section. It renders the section when the schema opens in an
+ * overlay, and its fields keep their root paths because a card adds no path segment.
+ */
+export type FormPageSectionCard<TSection> = TSection extends {
+    readonly key: infer TKey extends string;
+    readonly fields: infer TFields;
+} ? {
+    readonly type: 'card';
+    readonly key: TKey;
+    readonly fields: TFields;
+} : never;
+/** Card fields generated from the sections of a form page, in order. */
+export type FormPageSectionCards<TSections extends readonly FormValue[]> = {
+    readonly [TIndex in keyof TSections]: FormPageSectionCard<TSections[TIndex]>;
+};
+/**
+ * Schema returned by `defineFormPageSchema`: a normal form schema whose `fields` are the cards
+ * generated from `sections`, plus the `sections` and `navigation` that `FormPage` reads.
+ */
+export type FormPageSchema<TInput extends {
+    readonly sections: readonly FormValue[];
+}> = TInput & {
+    readonly fields: FormPageSectionCards<TInput['sections']>;
+};
+/** A section paired with the card generated for it, as the page runtime reads them. */
+export interface FormPageSectionEntry {
+    section: FormPageSection;
+    card: FormField;
+}
+/** How a form page scrolls to a section. */
+export interface FormPageScrollOptions {
+    /** Defaults to `smooth`, or `instant` when the user prefers reduced motion. */
+    behavior?: ScrollBehavior;
+    /** Records the section in the URL hash. Defaults to the page `hash` option. */
+    hash?: boolean;
+    /** Moves focus to the section title, for keyboard and screen reader users. */
+    focus?: boolean;
+}
+/**
+ * Where a section stands:
+ *
+ * - `invalid`: it shows at least one validation error
+ * - `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
+ */
+export type FormPageSectionStatus = 'invalid' | 'complete' | 'pending';
+/**
+ * Live state of a visible section, as the page navigation and section slots receive it.
+ */
+export interface FormPageSectionState {
+    /** Section key. */
+    key: string;
+    /** Position among the visible sections. */
+    index: number;
+    /** Resolved title. */
+    label: string;
+    /** Resolved supporting copy. */
+    description?: string;
+    /** True when the section is declared optional or has no required field. */
+    optional: boolean;
+    /** Number of required fields without a value. */
+    missing: number;
+    /** Summary of the section's requirements, see `FormPageSectionStatus`. */
+    status: FormPageSectionStatus;
+    /** True when a value of the section differs from the form's baseline. */
+    dirty: boolean;
+    /** Dirty paths inside the section. */
+    dirtyPaths: readonly string[];
+}

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

@@ -183,6 +183,64 @@ export interface FormOverlayUi {
     overlay?: FormUiClass;
     content?: FormUiClass;
 }
+/**
+ * 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.
+ *
+ * Two CSS variables place sections under the pinned header: `--nut-form-page-header` (its
+ * measured height, set by the page) and `--nut-form-page-gap` (the room below it, `24px` by
+ * default). Set them on an element around the navigation and sections, such as the root.
+ */
+export interface FormPageUi {
+    /** The `<form>` element, which scrolls on its own and is the container of the page queries. */
+    root?: FormUiClass;
+    /** Grid holding the navigation and the sections. */
+    body?: FormUiClass;
+    header?: FormUiClass;
+    headerContent?: FormUiClass;
+    heading?: FormUiClass;
+    eyebrow?: FormUiClass;
+    title?: FormUiClass;
+    /** Line under the title: the description and the unsaved-changes badge. */
+    meta?: FormUiClass;
+    unsaved?: FormUiClass;
+    actions?: FormUiClass;
+    navigation?: FormUiClass;
+    /** Holds the navigation title and the entries. */
+    navigationGroup?: FormUiClass;
+    navigationTitle?: FormUiClass;
+    navigationList?: FormUiClass;
+    /** List item around each entry. */
+    navigationEntry?: FormUiClass;
+    navigationItem?: FormUiClass;
+    navigationIndicator?: FormUiClass;
+    /** Check of a complete section in the indicator. */
+    navigationIndicatorIcon?: FormUiClass;
+    /** Dot in the indicator of the current section while it is pending. */
+    navigationIndicatorMarker?: FormUiClass;
+    navigationLabel?: FormUiClass;
+    navigationOptional?: FormUiClass;
+    navigationDirty?: FormUiClass;
+    /** Wrapper under the entries, whose padding insets the summary. */
+    navigationFooter?: FormUiClass;
+    /** The summary, with its top border: "3 sections left to complete". */
+    navigationSummary?: FormUiClass;
+    /** The bold "3 sections" of the summary. */
+    navigationSummaryCount?: FormUiClass;
+    sections?: FormUiClass;
+    /** Placeholder card shown while the schema context loads. */
+    sectionSkeleton?: FormUiClass;
+    section?: FormUiClass;
+    sectionHeader?: FormUiClass;
+    sectionTitle?: FormUiClass;
+    sectionDescription?: FormUiClass;
+    sectionOptional?: FormUiClass;
+    sectionActions?: FormUiClass;
+    sectionReset?: FormUiClass;
+    sectionBody?: FormUiClass;
+}
 export interface FormUiPartConfig<TUi> {
     ui?: TUi;
 }
@@ -219,4 +277,6 @@ export interface FormUiConfig {
     modal?: FormUiPartConfig<FormOverlayUi>;
     drawer?: FormUiPartConfig<FormOverlayUi>;
     fullscreen?: FormUiPartConfig<FormOverlayUi>;
+    /** Form page rendered by `FormPage` and its parts. */
+    page?: FormUiPartConfig<FormPageUi>;
 }

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

@@ -0,0 +1,15 @@
+import type { FormUiConfig, FormValidationMode, FormValue } from '../types/index.js';
+/** Reads the schema `controls` object. */
+export declare function getSchemaControls(schema: FormValue): any;
+/** Resolves `controls.syncInput`: `true`, a path list, or no synchronization. */
+export declare function getSchemaSyncInput(schema: FormValue): boolean | readonly string[];
+/** Resolves `controls.validate`, validating everything by default. */
+export declare function getSchemaValidationMode(schema: FormValue): FormValidationMode;
+/** Resolves `controls.autoFocus`: a raw field path, `true` for the first field, or `false`. */
+export declare function getSchemaAutoFocus(schema: FormValue): string | boolean;
+/** True when `controls.dirtyCheck` enables dirty metadata and reset affordances. */
+export declare function getSchemaDirtyCheck(schema: FormValue): boolean;
+/** Reads `controls.confirmNavOnDirty` as authored. */
+export declare function getSchemaDirtyNavigation(schema: FormValue): unknown;
+/** Reads the schema-level `ui` overrides. */
+export declare function getSchemaUi(schema: FormValue): FormUiConfig | undefined;

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

@@ -0,0 +1,38 @@
+import { isRecord } from "./path.js";
+import { isBoolean, isString, stringArray } from "./predicate.js";
+export function getSchemaControls(schema) {
+  if (!isRecord(schema)) {
+    return;
+  }
+  const controls = Object.getOwnPropertyDescriptor(schema, "controls")?.value;
+  return isRecord(controls) ? controls : void 0;
+}
+function getSchemaControl(schema, name) {
+  const controls = getSchemaControls(schema);
+  return controls ? Object.getOwnPropertyDescriptor(controls, name)?.value : void 0;
+}
+export function getSchemaSyncInput(schema) {
+  const value = getSchemaControl(schema, "syncInput");
+  return isBoolean(value) ? value : stringArray(value);
+}
+export function getSchemaValidationMode(schema) {
+  const value = getSchemaControl(schema, "validate");
+  return value === false || value === "required" || value === "validators" ? value : true;
+}
+export function getSchemaAutoFocus(schema) {
+  const value = getSchemaControl(schema, "autoFocus");
+  return isString(value) || isBoolean(value) ? value : false;
+}
+export function getSchemaDirtyCheck(schema) {
+  return getSchemaControl(schema, "dirtyCheck") === true;
+}
+export function getSchemaDirtyNavigation(schema) {
+  return getSchemaControl(schema, "confirmNavOnDirty");
+}
+export function getSchemaUi(schema) {
+  if (!isRecord(schema)) {
+    return void 0;
+  }
+  const value = Object.getOwnPropertyDescriptor(schema, "ui")?.value;
+  return isRecord(value) ? value : void 0;
+}

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

@@ -24,7 +24,7 @@ export async function focusFormFieldElement(fieldElement) {
   focusableElement.focus({ preventScroll: true });
   fieldElement.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
   await waitForFocusSettle();
-  return document.activeElement === focusableElement;
+  return focusableElement.ownerDocument.activeElement === focusableElement;
 }
 export async function focusFirstInvalidFormField(errors) {
   for (const error of errors) {

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

@@ -8,7 +8,9 @@ export function resolveFormLayoutConfig(base, override) {
   return {
     columns: override?.columns ?? base?.columns ?? FORM_LAYOUT_DEFAULTS.columns,
     fieldSpan: override?.fieldSpan ?? base?.fieldSpan ?? FORM_LAYOUT_DEFAULTS.fieldSpan,
-    gap: override?.gap ?? base?.gap ?? FORM_LAYOUT_DEFAULTS.gap
+    gap: override?.gap ?? base?.gap ?? FORM_LAYOUT_DEFAULTS.gap,
+    labelPosition: override?.labelPosition ?? base?.labelPosition,
+    labelWidth: override?.labelWidth ?? base?.labelWidth
   };
 }
 export function normalizeFormLayoutGap(value) {

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

@@ -0,0 +1,20 @@
+import type { FormObject, FormPageSectionEntry, FormPageSectionState, 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;
+/** True while the section's `condition` lets it render. */
+export declare function isFormPageSectionVisible(entry: FormPageSectionEntry, runtime: FormRuntime): boolean;
+/**
+ * Live state of one visible section: what it still misses, whether it shows errors, and what
+ * changed since the baseline.
+ */
+export declare function resolveFormPageSectionState(params: {
+    entry: FormPageSectionEntry;
+    index: number;
+    runtime: FormRuntime;
+    /** Input the form was opened with: a value it provides counts as filled in. */
+    input: FormObject | undefined;
+    /** False when the validation mode does not enforce required fields. */
+    requiredEnforced: boolean;
+}): FormPageSectionState;

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

@@ -0,0 +1,107 @@
+import { createFormFieldInstance } from "./field-instance.js";
+import { getPathValue, isRecord } from "./path.js";
+import { isBoolean, isFunction, isNumber, isString } from "./predicate.js";
+import {
+  fieldPath,
+  getChildFields,
+  getSchemaFields,
+  isEmptyValue,
+  isFlatPassthroughField,
+  isObjectContainerField,
+  resolveRequired
+} from "./state.js";
+import { resolveFormText } from "./text.js";
+export function getFormPageSections(schema) {
+  if (!isRecord(schema) || !Array.isArray(schema.sections)) {
+    return [];
+  }
+  const cards = getSchemaFields(schema);
+  return schema.sections.filter(isFormPageSection).flatMap((section) => {
+    const card = cards.find((field) => field.key === section.key);
+    return card ? [{ card, section }] : [];
+  });
+}
+export function getFormPageNavigationTitle(schema) {
+  if (!isRecord(schema) || !isRecord(schema.navigation)) {
+    return void 0;
+  }
+  const { title } = schema.navigation;
+  return isFormText(title) ? resolveFormText(title) : void 0;
+}
+export function isFormPageSectionVisible(entry, runtime) {
+  return !hasCondition(entry.card) || runtime.shouldRender(entry.card, [entry.card.key]);
+}
+export function resolveFormPageSectionState(params) {
+  const { entry, runtime } = params;
+  const leaves = collectVisibleLeaves(entry.section.fields, [], runtime);
+  const paths = leaves.map((leaf) => leaf.path.join("."));
+  const contains = (candidate) => paths.some((path) => isPathWithin(candidate, path));
+  const dirtyPaths = runtime.dirtyPaths.value.filter(contains);
+  const invalid = runtime.errors.value.some((error) => contains(error.path));
+  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 === true || required.length === 0;
+  const filled = !optional || leaves.some((leaf) => isProvided(leaf, runtime, dirtyPaths, params.input));
+  return {
+    description: resolveFormText(entry.section.description),
+    dirty: dirtyPaths.length > 0,
+    dirtyPaths,
+    index: params.index,
+    key: entry.section.key,
+    label: resolveFormText(entry.section.label) ?? entry.section.key,
+    missing,
+    optional,
+    status: invalid ? "invalid" : missing === 0 && filled ? "complete" : "pending"
+  };
+}
+function collectVisibleLeaves(fields, parentPath, runtime) {
+  return fields.flatMap((field) => {
+    if (field.ignore === true) {
+      return [];
+    }
+    const path = fieldPath(parentPath, field);
+    if (hasCondition(field) && !runtime.shouldRender(field, path)) {
+      return [];
+    }
+    if (createFormFieldInstance(field).state.is("stateless")) {
+      return [];
+    }
+    if (isFlatPassthroughField(field)) {
+      return collectVisibleLeaves(getChildFields(field), parentPath, runtime);
+    }
+    if (isObjectContainerField(field)) {
+      return collectVisibleLeaves(getChildFields(field), path, runtime);
+    }
+    return [{ field, path }];
+  });
+}
+function isRequiredLeaf(leaf, runtime) {
+  const required = Object.getOwnPropertyDescriptor(leaf.field, "required")?.value;
+  if (isBoolean(required)) {
+    return required;
+  }
+  const validation = Object.getOwnPropertyDescriptor(leaf.field, "validation")?.value;
+  if (!isFunction(required) && !isRecord(validation)) {
+    return false;
+  }
+  return resolveRequired(leaf.field, runtime.getFieldCallbackParams(leaf.path, leaf.field)) === true;
+}
+function isProvided(leaf, runtime, dirtyPaths, input) {
+  if (isEmptyValue(runtime.getValue(leaf.path))) {
+    return false;
+  }
+  const path = leaf.path.join(".");
+  return dirtyPaths.some((dirtyPath) => isPathWithin(dirtyPath, path)) || !isEmptyValue(getPathValue(input ?? {}, leaf.path));
+}
+function hasCondition(field) {
+  return isFunction(Object.getOwnPropertyDescriptor(field, "condition")?.value);
+}
+function isPathWithin(path, scope) {
+  return path === scope || path.startsWith(`${scope}.`);
+}
+function isFormPageSection(value) {
+  return isRecord(value) && isString(value.key) && isFormText(value.label) && Array.isArray(value.fields);
+}
+function isFormText(value) {
+  return isString(value) || isNumber(value) || isFunction(value);
+}

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

@@ -30,4 +30,6 @@ export declare function getMatrixRows(field: FormField): any[];
 export declare function resolveRequired(field: FormField, params: FormFieldCallbackParams): any;
 export declare function resolveRequiredMessage(field: FormField, fallback?: string): string;
 export declare function isEmptyValue(value: FormValue): boolean;
+/** Child fields of a container, with the fields of every tab for tabs. */
+export declare function getChildFields(field: FormField): FormField[];
 export declare function getArrayItemFields(field: FormField, item: FormObject): FormField[];

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

@@ -588,7 +588,7 @@ function isFormField(value) {
   const type = Object.getOwnPropertyDescriptor(value, "type")?.value;
   return isString(value.key) && isString(type) && isRegisteredFormFieldType(type);
 }
-function getChildFields(field) {
+export function getChildFields(field) {
   const tabs = Object.getOwnPropertyDescriptor(field, "tabs")?.value;
   if (Array.isArray(tabs)) {
     return tabs.flatMap((tab) => {

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

@@ -39,6 +39,7 @@ function mergeFormUiPair(current, next) {
     group: mergePart(current.group, next.group),
     matrix: mergePart(current.matrix, next.matrix),
     modal: mergePart(current.modal, next.modal),
+    page: mergePart(current.page, next.page),
     root: mergePart(current.root, next.root),
     tree: mergePart(current.tree, next.tree),
     treeSelect: mergePart(current.treeSelect, next.treeSelect)