nuxt-ui-tools 0.1.0

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

@@ -0,0 +1,167 @@
+import type { FormFieldType } from './field-base.js';
+export type FormDensity = 'compact' | 'default' | 'comfortable';
+export type FormControlSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export type FormUiClass = string;
+export interface FormControlUi {
+    [slot: string]: FormUiClass | undefined;
+}
+export interface FormFieldControlConfig {
+    size?: FormControlSize;
+    class?: FormUiClass;
+    ui?: FormControlUi;
+}
+export type FormFieldControlConfigs = Partial<Record<FormFieldType, FormFieldControlConfig>> & {
+    [type: string]: FormFieldControlConfig | undefined;
+};
+export interface FormRootUi {
+    root?: FormUiClass;
+    header?: FormUiClass;
+    headerContent?: FormUiClass;
+    heading?: FormUiClass;
+    title?: FormUiClass;
+    stepper?: FormUiClass;
+    step?: FormUiClass;
+    viewport?: FormUiClass;
+    grid?: FormUiClass;
+    skeleton?: FormUiClass;
+    skeletonField?: FormUiClass;
+    skeletonLabel?: FormUiClass;
+    skeletonControl?: FormUiClass;
+    footer?: FormUiClass;
+    close?: FormUiClass;
+}
+/** Slots forwarded to UFormField plus form-engine-owned body controls. */
+export interface FormFieldUi {
+    root?: FormUiClass;
+    wrapper?: FormUiClass;
+    labelWrapper?: FormUiClass;
+    label?: FormUiClass;
+    container?: FormUiClass;
+    description?: FormUiClass;
+    error?: FormUiClass;
+    hint?: FormUiClass;
+    help?: FormUiClass;
+    body?: FormUiClass;
+    content?: FormUiClass;
+    collapsible?: FormUiClass;
+    collapseTrigger?: FormUiClass;
+    reset?: FormUiClass;
+}
+export interface FormActionsUi {
+    root?: FormUiClass;
+    left?: FormUiClass;
+    right?: FormUiClass;
+    button?: FormUiClass;
+}
+/** Slots for a group and its underlying UFieldGroup. */
+export interface FormGroupUi {
+    root?: FormUiClass;
+    base?: FormUiClass;
+}
+export interface FormTreeSelectUi {
+    root?: FormUiClass;
+    trigger?: FormUiClass;
+    triggerLabel?: FormUiClass;
+    content?: FormUiClass;
+    search?: FormUiClass;
+    tree?: FormUiClass;
+    empty?: FormUiClass;
+}
+/** Slots for the inline tree and its underlying Nuxt UI tree. */
+export interface FormTreeUi {
+    root?: FormUiClass;
+    item?: FormUiClass;
+    itemWithChildren?: FormUiClass;
+    listWithChildren?: FormUiClass;
+    link?: FormUiClass;
+    linkLeadingIcon?: FormUiClass;
+    linkLabel?: FormUiClass;
+    linkTrailing?: FormUiClass;
+    linkTrailingIcon?: FormUiClass;
+    selectionControl?: FormUiClass;
+}
+export interface FormMatrixUi {
+    root?: FormUiClass;
+    table?: FormUiClass;
+    head?: FormUiClass;
+    headerRow?: FormUiClass;
+    corner?: FormUiClass;
+    columnHeader?: FormUiClass;
+    body?: FormUiClass;
+    row?: FormUiClass;
+    rowHeader?: FormUiClass;
+    cell?: FormUiClass;
+    control?: FormUiClass;
+}
+export interface FormArrayListUi {
+    root?: FormUiClass;
+    header?: FormUiClass;
+    title?: FormUiClass;
+    description?: FormUiClass;
+    empty?: FormUiClass;
+    tabs?: FormUiClass;
+    tab?: FormUiClass;
+    item?: FormUiClass;
+    itemHeader?: FormUiClass;
+    itemTitle?: FormUiClass;
+    itemActions?: FormUiClass;
+    variant?: FormUiClass;
+    fields?: FormUiClass;
+    list?: FormUiClass;
+    add?: FormUiClass;
+    action?: FormUiClass;
+}
+export interface FormArrayTableUi {
+    root?: FormUiClass;
+    viewport?: FormUiClass;
+    table?: FormUiClass;
+    head?: FormUiClass;
+    headerRow?: FormUiClass;
+    headerCell?: FormUiClass;
+    actionsHeader?: FormUiClass;
+    body?: FormUiClass;
+    row?: FormUiClass;
+    cell?: FormUiClass;
+    control?: FormUiClass;
+    actionsCell?: FormUiClass;
+    empty?: FormUiClass;
+    add?: FormUiClass;
+    action?: FormUiClass;
+}
+export interface FormOverlayUi {
+    overlay?: FormUiClass;
+    content?: FormUiClass;
+}
+export interface FormUiPartConfig<TUi> {
+    ui?: TUi;
+}
+/**
+ * Form-engine presentation defaults.
+ *
+ * Values from `app.config.nuxtUiTools.form` are merged first, then schema `ui`, then the
+ * rendered form's `ui` prop. Individual field `props` remain the final override for the
+ * underlying Nuxt UI control.
+ */
+export interface FormUiConfig {
+    /** Maps the whole form to a consistent control size. */
+    density?: FormDensity;
+    /** Explicit control-size override. */
+    control?: {
+        size?: FormControlSize;
+        ui?: FormControlUi;
+    };
+    /** Defaults for every control of a field kind, applied after shared control defaults. */
+    fields?: FormFieldControlConfigs;
+    root?: FormUiPartConfig<FormRootUi>;
+    field?: FormUiPartConfig<FormFieldUi>;
+    actions?: FormUiPartConfig<FormActionsUi>;
+    group?: FormUiPartConfig<FormGroupUi>;
+    tree?: FormUiPartConfig<FormTreeUi>;
+    treeSelect?: FormUiPartConfig<FormTreeSelectUi>;
+    matrix?: FormUiPartConfig<FormMatrixUi>;
+    arrayList?: FormUiPartConfig<FormArrayListUi>;
+    arrayTable?: FormUiPartConfig<FormArrayTableUi>;
+    modal?: FormUiPartConfig<FormOverlayUi>;
+    drawer?: FormUiPartConfig<FormOverlayUi>;
+    fullscreen?: FormUiPartConfig<FormOverlayUi>;
+}

package/dist/runtime/form/types/upload-runtime.d.ts

@@ -0,0 +1,6 @@
+export interface FormUploadRuntimeState {
+    start: () => Promise<void>;
+    cancel: () => Promise<void>;
+    retry: () => Promise<void>;
+    remove: (value?: unknown) => Promise<void>;
+}

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

@@ -0,0 +1,64 @@
+import type { DataTag, QueryKey } from '@tanstack/vue-query';
+import type { GenericObject, LazyRenderableValue, LazyTextValue, MaybePromise } from '../../shared/types/utils.js';
+/**
+ * Values that can be returned directly or resolved asynchronously by the form runtime.
+ */
+export type FormMaybePromise<TValue> = MaybePromise<TValue>;
+/**
+ * User-facing text accepted by form schema properties.
+ *
+ * Lazy functions are intentionally argument-free so labels remain easy to translate from
+ * i18n composables without forcing every text property into the field callback model.
+ */
+export type FormText = LazyTextValue;
+/**
+ * Content rendered by stateless or decorative fields.
+ */
+export type FormRenderable = LazyRenderableValue;
+/**
+ * Generic object used for UI-library props and other intentionally open extension bags.
+ */
+export type FormObject = GenericObject;
+/**
+ * A value that can be static or derived from the current field callback context.
+ */
+export type FormDynamic<TValue, TParams> = TValue | ((params: TParams) => TValue);
+/**
+ * Describes the normalized state of an async resource exposed on form context.
+ */
+export interface FormAsyncResource<TValue, TError = unknown> {
+    /** Last successfully resolved value. `undefined` means no usable data is available yet. */
+    value: TValue | undefined;
+    /** Error returned by the async source, if the current resource is in an error state. */
+    error: TError | null;
+    /** True while the first value is loading. */
+    pending: boolean;
+    /** True while the resource is refreshing after at least one value was already resolved. */
+    fetching: boolean;
+    /** True when consumers should show a blocking loader for this resource. */
+    loading: boolean;
+    /** Refreshes the resource when the source supports refresh/refetch. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Describes the normalized state of a synchronous context value.
+ */
+export interface FormSyncResource<TValue> {
+    /** Current value. */
+    value: TValue;
+}
+type FormFunctionResult<TValue> = TValue extends (...params: infer _TParams) => infer TResult ? TResult : never;
+type FormQuerySelectedValue<TValue> = TValue extends {
+    select?: infer TSelect;
+} ? FormFunctionResult<Exclude<TSelect, undefined>> : never;
+type FormQueryFunctionValue<TValue> = TValue extends {
+    queryFn?: infer TQueryFn;
+} ? Awaited<FormFunctionResult<Exclude<TQueryFn, undefined>>> : never;
+type FormQueryResource<TValue, TQueryKey> = [FormQuerySelectedValue<TValue>] extends [never] ? TQueryKey extends DataTag<QueryKey, infer TResolved, infer TError> ? FormAsyncResource<TResolved, TError> : FormAsyncResource<FormQueryFunctionValue<TValue>> : FormAsyncResource<FormQuerySelectedValue<TValue>>;
+/**
+ * Converts a raw context source return value into the resource exposed as `ctx`.
+ */
+export type FormContextResource<TValue> = [TValue] extends [Promise<infer TResolved>] ? FormAsyncResource<TResolved> : [TValue] extends [{
+    queryKey: infer TQueryKey;
+}] ? FormQueryResource<TValue, TQueryKey> : FormSyncResource<TValue>;
+export {};

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

@@ -0,0 +1,64 @@
+import type { FormFieldCallback } from './callbacks.js';
+import type { FormMaybePromise, FormText } from './utils.js';
+/**
+ * Result returned by a form validation rule.
+ */
+export type FormValidationResult = boolean | string | null | undefined;
+/**
+ * A single validation rule.
+ */
+export interface FormValidationRule<TValue = unknown, TContext = {}, TDeps = {}> {
+    /** Stable rule name used for debugging, i18n, and external error mapping. */
+    name: string;
+    /** Returns true for valid values, false/string for invalid values. */
+    validate: FormFieldCallback<FormMaybePromise<FormValidationResult>, TContext, TDeps, TValue>;
+    /** Default message used when `validate` returns false. */
+    message?: FormText;
+}
+/**
+ * Controls when a field starts running validation while the user edits it.
+ *
+ * - `blur`: default Vuelidate-style behavior. The first edit stays quiet, the first blur
+ *   marks the field as validation-dirty, and later edits validate live.
+ * - `input`: validates as soon as the value changes.
+ * - `submit`: only validates through explicit form/step submit validation.
+ */
+export type FormValidationTrigger = 'blur' | 'input' | 'submit';
+/** Selects which authored validation layers are evaluated. */
+export type FormValidationMode = boolean | 'required' | 'rules';
+/**
+ * Concrete validation error stored by the form runtime.
+ */
+export interface FormValidationError {
+    /** Raw field path. */
+    path: string;
+    /** Resolved message safe to display in the UI. */
+    message: string;
+}
+/**
+ * Options accepted by form-level validation calls.
+ */
+export interface FormValidationOptions {
+    /**
+     * Focuses the first focusable invalid field after validation fails.
+     *
+     * @example
+     * ```ts
+     * await form.validate({ focus: true })
+     * ```
+     */
+    focus?: boolean;
+}
+/**
+ * Field validation configuration.
+ */
+export interface FormValidationConfig<TValue = unknown, TContext = {}, TDeps = {}> {
+    /** Defines when the field starts showing validation feedback while editing. */
+    trigger?: FormValidationTrigger;
+    /** Marks the field as required. */
+    required?: boolean | FormFieldCallback<boolean, TContext, TDeps, TValue>;
+    /** Message used by the default required rule. */
+    requiredMessage?: FormText;
+    /** Additional field rules. */
+    rules?: readonly FormValidationRule<TValue, TContext, TDeps>[];
+}

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

@@ -0,0 +1,2 @@
+import type { FormApi, FormRuntime } from '../types/index.js';
+export declare function createPublicFormApi(runtime: FormRuntime): FormApi;

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

@@ -0,0 +1,12 @@
+export function createPublicFormApi(runtime) {
+  return {
+    get: runtime.getValue,
+    set: runtime.setValue,
+    validate: runtime.validate,
+    focus: runtime.focusField,
+    submit: async () => {
+      await runtime.submit();
+    },
+    reset: runtime.reset
+  };
+}

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

@@ -0,0 +1,2 @@
+import type { FormObject } from '../types/index.js';
+export declare function syncFormArrayItems(target: unknown, source: readonly FormObject[]): boolean;

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

@@ -0,0 +1,19 @@
+import { cloneFormValue, isRecord } from "./path.js";
+export function syncFormArrayItems(target, source) {
+  if (!Array.isArray(target)) return false;
+  const snapshots = source.map((item) => {
+    const cloned = cloneFormValue(item);
+    return isRecord(cloned) ? cloned : {};
+  });
+  for (const [index, snapshot] of snapshots.entries()) {
+    const current = target[index];
+    if (!isRecord(current)) {
+      target[index] = snapshot;
+      continue;
+    }
+    for (const key of Object.keys(current)) if (!(key in snapshot)) delete current[key];
+    for (const [key, value] of Object.entries(snapshot)) current[key] = value;
+  }
+  target.splice(snapshots.length);
+  return true;
+}

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

@@ -0,0 +1,6 @@
+import type { FormField, FormObject } from '../types/index.js';
+export declare function resolveFieldDependencies(params: {
+    field: FormField;
+    state: FormObject;
+    parentPath: readonly string[];
+}): import("../../shared/index.js").GenericObject;

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

@@ -0,0 +1,23 @@
+import { getScopedPathValue } from "./path.js";
+export function resolveFieldDependencies(params) {
+  const output = {};
+  const dependencies = Object.getOwnPropertyDescriptor(params.field, "dependencies")?.value;
+  if (!Array.isArray(dependencies)) return output;
+  for (const dependency of dependencies) {
+    const normalized = normalizeFieldDependency(dependency);
+    if (!normalized) continue;
+    output[normalized.target] = getScopedPathValue(
+      params.state,
+      normalized.source,
+      params.parentPath
+    );
+  }
+  return output;
+}
+function normalizeFieldDependency(value) {
+  if (typeof value === "string") return { source: value, target: value };
+  if (!Array.isArray(value)) return null;
+  const [source, target] = value;
+  if (typeof source !== "string" || typeof target !== "string") return null;
+  return { source, target };
+}

package/dist/runtime/form/utils/field-instance.d.ts

@@ -0,0 +1,68 @@
+import type { FormField, FormFieldCapability, FormFieldKindDefinition, FormFieldState, FormFieldType } from '../types/index.js';
+export type FormFieldKind = FormFieldKindDefinition;
+export type { FormFieldCapability, FormFieldState };
+/**
+ * Internal public instance for checking authored field behavior against the field-kind registry.
+ *
+ * Runtime code should prefer this over ad hoc checks such as `field.type === 'select'`
+ * when the question is about capabilities or state model.
+ *
+ * @example
+ * ```ts
+ * const field = createFormFieldInstance(rawField)
+ *
+ * field.type.is('select')
+ * field.is('stateful')
+ * field.has('options')
+ * field.state.is('stateless')
+ * field.capability.has('options')
+ * field.capability.hasAll(['label', 'validation'])
+ * ```
+ */
+export interface FormFieldInstance<TField extends FormField = FormField> {
+    /** Authored field object from the schema. */
+    raw: TField;
+    /** Checks the runtime state model. Shorthand for `field.state.is(...)`. */
+    is: (state: FormFieldState) => boolean;
+    /** Checks whether the runtime state model matches at least one state. */
+    isAny: (states: readonly FormFieldState[]) => boolean;
+    /** Checks whether the field kind declares a capability. Shorthand for `field.capability.has(...)`. */
+    has: (capability: FormFieldCapability) => boolean;
+    /** Checks whether the field kind declares at least one capability. */
+    hasAny: (capabilities: readonly FormFieldCapability[]) => boolean;
+    /** Checks whether the field kind declares every capability. */
+    hasAll: (capabilities: readonly FormFieldCapability[]) => boolean;
+    /** Field type checks. */
+    type: {
+        /** Authored field type. */
+        value: TField['type'];
+        /** Checks the authored field type. */
+        is: (type: FormFieldType) => boolean;
+        /** Checks whether the authored field type matches at least one type. */
+        isAny: (types: readonly FormFieldType[]) => boolean;
+    };
+    /** Field-kind definition resolved from the registry. */
+    config: FormFieldKind | null;
+    /** Field state-model checks. */
+    state: {
+        /** Runtime state model resolved from the field-kind registry. */
+        value: FormFieldState | null;
+        /** Checks the runtime state model. */
+        is: (state: FormFieldState) => boolean;
+        /** Checks whether the runtime state model matches at least one state. */
+        isAny: (states: readonly FormFieldState[]) => boolean;
+    };
+    /** Field capability checks backed by the field-kind registry. */
+    capability: {
+        /** Checks whether the field kind declares a capability. */
+        has: (capability: FormFieldCapability) => boolean;
+        /** Checks whether the field kind declares at least one capability. */
+        hasAny: (capabilities: readonly FormFieldCapability[]) => boolean;
+        /** Checks whether the field kind declares every capability. */
+        hasAll: (capabilities: readonly FormFieldCapability[]) => boolean;
+    };
+}
+export declare function createFormFieldInstance<const TField extends FormField>(raw: TField): FormFieldInstance<TField>;
+export declare function getFormFieldKind(type: FormFieldType | string): FormFieldKind | null;
+export declare function isRegisteredFormFieldType(type: string): type is FormFieldType;
+export declare function fieldKindHas(kind: FormFieldKind, capability: FormFieldCapability): boolean;

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

@@ -0,0 +1,57 @@
+import { formFieldKinds } from "../fields/index.js";
+export function createFormFieldInstance(raw) {
+  const config = getFormFieldKind(raw.type);
+  const state = config?.state ?? null;
+  function has(capability) {
+    return config ? fieldKindHas(config, capability) : false;
+  }
+  function is(expectedState) {
+    return state === expectedState;
+  }
+  return {
+    raw,
+    is,
+    isAny: (states) => states.some(is),
+    has,
+    hasAny: (capabilities) => capabilities.some(has),
+    hasAll: (capabilities) => capabilities.every(has),
+    type: {
+      value: raw.type,
+      is: (type) => raw.type === type,
+      isAny: (types) => types.some((type) => raw.type === type)
+    },
+    config,
+    state: {
+      value: state,
+      is,
+      isAny: (states) => states.some(is)
+    },
+    capability: {
+      has,
+      hasAny: (capabilities) => capabilities.some(has),
+      hasAll: (capabilities) => capabilities.every(has)
+    }
+  };
+}
+export function getFormFieldKind(type) {
+  return formFieldKinds.find((kind) => kind.type === type) ?? null;
+}
+export function isRegisteredFormFieldType(type) {
+  return getFormFieldKind(type) !== null;
+}
+export function fieldKindHas(kind, capability) {
+  if (capability === "value") return kind.state === "stateful";
+  if (capability === "children") return kind.state === "passthrough";
+  if (capability === "label") return kind.ui?.label === true;
+  if (capability === "description") return kind.ui?.description === true;
+  if (capability === "hint") return kind.ui?.hint === true;
+  if (capability === "layout") return kind.layout?.item === true || kind.layout?.container === true;
+  if (capability === "itemLayout") return kind.layout?.item === true;
+  if (capability === "containerLayout") return kind.layout?.container === true;
+  if (capability === "options") return kind.options?.enabled === true;
+  if (capability === "upload") return kind.upload?.enabled === true;
+  if (capability === "validation") return kind.validation === true;
+  if (capability === "transform") return kind.transform === true;
+  if (capability === "submit") return kind.state === "stateful";
+  return false;
+}

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

@@ -0,0 +1,17 @@
+import type { FormFieldKindDefinition } from '../types/index.js';
+/**
+ * Defines a form field kind and preserves its literal type for the registry.
+ *
+ * @example
+ * ```ts
+ * export const textFieldKind = defineFormFieldKind({
+ *   type: 'text',
+ *   state: 'stateful',
+ *   ui: { label: true, description: true, hint: true },
+ *   layout: { item: true },
+ *   validation: true,
+ *   transform: true,
+ * })
+ * ```
+ */
+export declare function defineFormFieldKind<const TDefinition extends FormFieldKindDefinition>(definition: TDefinition): TDefinition;

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

@@ -0,0 +1,3 @@
+export function defineFormFieldKind(definition) {
+  return definition;
+}

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

@@ -0,0 +1,5 @@
+import type { FormValidationError } from '../types/index.js';
+export declare function normalizeFormFocusPath(path: string | readonly string[]): string;
+export declare function focusFormField(path: string | readonly string[]): Promise<boolean>;
+export declare function focusFormFieldElement(fieldElement: HTMLElement | null): Promise<boolean>;
+export declare function focusFirstInvalidFormField(errors: readonly FormValidationError[]): Promise<boolean>;

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

@@ -0,0 +1,47 @@
+const focusableSelector = [
+  'input:not([disabled]):not([type="hidden"])',
+  "textarea:not([disabled])",
+  "select:not([disabled])",
+  "button:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(",");
+export function normalizeFormFocusPath(path) {
+  return typeof path === "string" ? path : path.join(".");
+}
+export async function focusFormField(path) {
+  if (typeof document === "undefined") return false;
+  const fieldElement = findFieldElement(normalizeFormFocusPath(path));
+  return focusFormFieldElement(fieldElement);
+}
+export async function focusFormFieldElement(fieldElement) {
+  const focusableElement = fieldElement ? findFocusableElement(fieldElement) : null;
+  if (!fieldElement || !focusableElement) return false;
+  focusableElement.focus({ preventScroll: true });
+  fieldElement.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
+  await waitForFocusSettle();
+  return document.activeElement === focusableElement;
+}
+export async function focusFirstInvalidFormField(errors) {
+  for (const error of errors) {
+    const focused = await focusFormField(error.path);
+    if (focused) return true;
+  }
+  return false;
+}
+function findFieldElement(path) {
+  return Array.from(document.querySelectorAll("[data-form-field]")).find(
+    (element) => element.dataset.formField === path
+  ) ?? null;
+}
+function findFocusableElement(element) {
+  if (element.matches(focusableSelector) && isFocusableElement(element)) return element;
+  return Array.from(element.querySelectorAll(focusableSelector)).find(isFocusableElement) ?? null;
+}
+function isFocusableElement(element) {
+  if (element.hasAttribute("disabled")) return false;
+  if (element.getAttribute("aria-hidden") === "true") return false;
+  return true;
+}
+function waitForFocusSettle() {
+  return new Promise((resolve) => window.setTimeout(resolve, 120));
+}

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

@@ -0,0 +1,10 @@
+import type { FormLayoutConfig } from '../types/index.js';
+export declare const FORM_LAYOUT_DEFAULTS: {
+    readonly columns: 8;
+    readonly fieldSpan: "8 md:4";
+    readonly gap: 16;
+};
+export declare function resolveFormLayoutConfig(base: FormLayoutConfig | undefined, override?: FormLayoutConfig): FormLayoutConfig;
+export declare function normalizeFormLayoutGap(value: number | string | undefined): string;
+export declare function normalizeFormGridColumnsStyle(value: string): string;
+export declare function normalizeFormGridColumnSpanStyle(value: string): string;

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

@@ -0,0 +1,31 @@
+export const FORM_LAYOUT_DEFAULTS = {
+  columns: 8,
+  fieldSpan: "8 md:4",
+  gap: 16
+};
+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
+  };
+}
+export function normalizeFormLayoutGap(value) {
+  const gap = value ?? FORM_LAYOUT_DEFAULTS.gap;
+  if (typeof gap === "number") return `${gap}px`;
+  return gap;
+}
+export function normalizeFormGridColumnsStyle(value) {
+  const columns = normalizePositiveInteger(value, FORM_LAYOUT_DEFAULTS.columns);
+  return `grid-template-columns: repeat(${columns}, minmax(0, 1fr))`;
+}
+export function normalizeFormGridColumnSpanStyle(value) {
+  if (value === "full") return "grid-column: 1 / -1";
+  const span = normalizePositiveInteger(value, 1);
+  return `grid-column: span ${span} / span ${span}`;
+}
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.trunc(parsed));
+}

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

@@ -0,0 +1,11 @@
+import type { FormFieldCallbackParams, FormOptionItem, FormOptionValue } from '../types/index.js';
+export interface ResolvedFormOption {
+    value: FormOptionValue;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+    children?: readonly ResolvedFormOption[];
+}
+export declare function normalizeOptionItem(option: unknown): ResolvedFormOption;
+export declare function normalizeOptionItems(options: readonly unknown[] | undefined): ResolvedFormOption[];
+export declare function resolveOptionSource(source: unknown, params: FormFieldCallbackParams): readonly FormOptionItem[];