nuxt-ui-tools 1.3.0 → 1.4.0

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

@@ -0,0 +1,31 @@
+/**
+ * Presentation of the radio and checkbox cards.
+ *
+ * @example
+ * ```ts
+ * // A fixed grid of cards, each with its icon in a tile above the label and a check in the
+ * // corner once selected.
+ * props: { columns: '1 md:2 lg:3', icon: 'tile', indicator: 'corner' }
+ * ```
+ */
+export interface FormChoiceCardProps {
+    /**
+     * Lays the cards out in a fixed grid of this many equal columns. Accepts breakpoints:
+     * `3` or `'1 md:2 lg:3'`. Without it, cards flow along `orientation`.
+     */
+    columns?: number | string;
+    /** Direction of the cards when they are not in a `columns` grid. */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Selection mark: the radio or checkbox before the content (`start`, the default), after it
+     * (`end`), none (`hidden`), or a check in the top corner of the selected cards (`corner`).
+     */
+    indicator?: 'start' | 'end' | 'hidden' | 'corner';
+    /**
+     * Where an option's `icon` shows: before its label (`inline`, the default), or in a tile above
+     * it (`tile`) that takes the selection color. Style the parts the engine renders with the
+     * `ui` slots `tile`, `tileIcon`, `optionIcon`, `check`, and `checkIcon`, next to the Nuxt UI
+     * slots of the group.
+     */
+    icon?: 'inline' | 'tile';
+}

package/dist/runtime/form/fields/choice-card/use-choice-card.d.ts

@@ -0,0 +1,22 @@
+import type { FormControlUi } from '../../types/index.js';
+import type { FormChoiceCardProps } from './types.js';
+/** Props the card fields render themselves, kept away from the Nuxt UI group. */
+export declare const CHOICE_CARD_PROPS: string[];
+/**
+ * Presentation of a radio or checkbox card group: the flowing row or fixed grid of cards, the
+ * selection mark, and where option icons go. Returns the props and `ui` slots for the Nuxt UI
+ * group, and what the card content renders (`tile`, `corner`).
+ */
+export declare function useChoiceCard(params: {
+    props: () => FormChoiceCardProps;
+    ui: () => FormControlUi | undefined;
+}): {
+    corner: import("vue").ComputedRef<boolean>;
+    indicator: import("vue").ComputedRef<"end" | "start" | "hidden" | undefined>;
+    orientation: import("vue").ComputedRef<"horizontal" | "vertical" | undefined>;
+    style: import("vue").ComputedRef<{
+        '--nut-choice-columns': string;
+    } | undefined>;
+    tile: import("vue").ComputedRef<boolean>;
+    ui: import("vue").ComputedRef<FormControlUi>;
+};

package/dist/runtime/form/fields/choice-card/use-choice-card.js

@@ -0,0 +1,52 @@
+import { computed } from "vue";
+import { useResponsiveValue } from "../../../shared/composables/use-responsive-value.js";
+import { mergeFormUiClass } from "../../utils/ui.js";
+import { CARD_SELECTED_RING } from "../card-selection.js";
+export const CHOICE_CARD_PROPS = ["columns", "icon", "indicator", "orientation"];
+export function useChoiceCard(params) {
+  const columnsValue = useResponsiveValue(() => String(params.props().columns ?? ""));
+  const columns = computed(() => {
+    const count = Math.trunc(Number(columnsValue.value));
+    return count > 0 ? count : void 0;
+  });
+  const corner = computed(() => params.props().indicator === "corner");
+  const tile = computed(() => params.props().icon === "tile");
+  const indicator = computed(() => {
+    const value = params.props().indicator;
+    return value === "corner" ? "hidden" : value;
+  });
+  const orientation = computed(() => params.props().orientation);
+  const style = computed(
+    () => columns.value ? { "--nut-choice-columns": String(columns.value) } : void 0
+  );
+  const ui = computed(() => {
+    const current = params.ui();
+    return {
+      ...current,
+      fieldset: mergeFormUiClass(
+        columns.value ? "grid grid-cols-[repeat(var(--nut-choice-columns),minmax(0,1fr))] gap-2.5" : `gap-2.5${orientation.value === "horizontal" ? " flex-wrap" : ""}`,
+        current?.fieldset
+      ),
+      item: mergeFormUiClass(
+        `border-default ${CARD_SELECTED_RING}`,
+        corner.value ? "relative" : void 0,
+        current?.item
+      ),
+      // A tile stacks above the title, and the description below it, with gaps.
+      label: mergeFormUiClass(
+        tile.value ? "flex flex-col items-start gap-2.5 font-semibold" : void 0,
+        current?.label
+      ),
+      // A hidden indicator centers the text: keep it aligned, and clear of an inline corner check.
+      wrapper: mergeFormUiClass(
+        tile.value ? "flex flex-col gap-1.5" : void 0,
+        [
+          indicator.value === "hidden" ? "ms-0 text-start" : "",
+          corner.value && !tile.value ? "pe-7" : ""
+        ].join(" "),
+        current?.wrapper
+      )
+    };
+  });
+  return { corner, indicator, orientation, style, tile, ui };
+}

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

@@ -1,20 +1,21 @@
 <script setup>
-import UIcon from "@nuxt/ui/components/Icon.vue";
 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 { isBoolean, isNumber, isString } from "../../utils/predicate";
-import { mergeFormUiClass } from "../../utils/ui";
-import { CARD_SELECTED_RING } from "../card-selection";
+import ChoiceCardLabel from "../choice-card/choice-card-label.vue";
+import { CHOICE_CARD_PROPS, useChoiceCard } from "../choice-card/use-choice-card";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
 const { fieldProps, form, controlProps, disabled, handleBlur, options } = useFieldControl(
   () => props.field,
-  () => props.path
+  () => props.path,
+  { omit: CHOICE_CARD_PROPS }
 );
+const cards = useChoiceCard({ props: () => fieldProps.value, ui: () => controlProps.value.ui });
 const model = computed({
   get: () => {
     const value = form.getValue(props.path);
@@ -26,14 +27,6 @@ const model = computed({
   set: (value) => form.setValue(props.path, value)
 });
 const items = computed(() => [...options.items.value]);
-const groupUi = computed(() => ({
-  ...controlProps.value.ui,
-  fieldset: mergeFormUiClass(
-    controlProps.value.ui?.fieldset,
-    fieldProps.value.orientation === "horizontal" ? "flex-wrap" : void 0
-  ),
-  item: mergeFormUiClass(CARD_SELECTED_RING, controlProps.value.ui?.item)
-}));
 </script>
 
 <template>
@@ -45,16 +38,22 @@ const groupUi = computed(() => ({
       label-key="label"
       variant="card"
       :items="items"
-      :orientation="fieldProps.orientation"
-      :ui="groupUi"
+      :orientation="cards.orientation.value"
+      :indicator="cards.indicator.value"
+      :ui="cards.ui.value"
+      :style="cards.style.value"
       :disabled="disabled"
       @blur="handleBlur"
     >
       <template #label="{ item }">
-        <span class="inline-flex items-center gap-2">
-          <UIcon v-if="item.icon" :name="item.icon" class="size-4 shrink-0" aria-hidden="true" />
-          <span>{{ item.label }}</span>
-        </span>
+        <ChoiceCardLabel
+          :label="item.label"
+          :icon="item.icon"
+          :tile="cards.tile.value"
+          :corner="cards.corner.value"
+          :selected="model === item.value"
+          :ui="cards.ui.value"
+        />
       </template>
     </URadioGroup>
   </FormFieldShell>

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