@atscript/vue-form 0.1.103 → 0.1.104

package/dist/as-form.vue-DH3phgWP.d.mts

@@ -0,0 +1,1425 @@
+import { c as TAsUnionContext, n as TAsChangeType, o as TAsComponentProps, s as TAsTypeComponents } from "./types-nuUi10Kl.mjs";
+import * as vue from "vue";
+import { Component, ComputedRef, MaybeRef, Ref, ShallowRef, WritableComputedRef } from "vue";
+import * as _atscript_ui0 from "@atscript/ui";
+import { ClientFactory, ClientFactory as ClientFactory$1, FormArrayFieldDef, FormDef, FormDiffOptions, FormDiffOptions as FormDiffOptions$1, FormFieldChange, FormFieldChange as FormFieldChange$1, FormFieldDef, FormRebaseOptions, FormRebaseOptions as FormRebaseOptions$1, FormTupleFieldDef, FormUnionFieldDef, FormUnionVariant, ResolvedValueHelp, ValueHelpInfo, getDefaultClientFactory, resetDefaultClientFactory, setDefaultClientFactory } from "@atscript/ui";
+//#region ../../node_modules/.pnpm/@atscript+typescript@0.1.77_@atscript+core@0.1.77_@emnapi+core@1.10.0_@emnapi+runtime@1_3bfa7f91a63047efd8c9ebad2f514f7c/node_modules/@atscript/typescript/dist/utils.d.ts
+interface TError {
+  path: string;
+  message: string;
+  details?: TError[];
+}
+/**
+ * A plugin function that can intercept validation.
+ *
+ * Return `true` to accept the value, `false` to reject it,
+ * or `undefined` to fall through to the default validation.
+ */
+type TValidatorPlugin = (ctx: TValidatorPluginContext, def: TAtscriptAnnotatedType, value: any) => boolean | undefined;
+/** Options for configuring {@link Validator} behavior. */
+interface TValidatorOptions {
+  partial: boolean | 'deep' | ((type: TAtscriptAnnotatedType<TAtscriptTypeObject>, path: string) => boolean);
+  replace?: (type: TAtscriptAnnotatedType, path: string) => TAtscriptAnnotatedType;
+  plugins: TValidatorPlugin[];
+  unknownProps: 'strip' | 'ignore' | 'error';
+  errorLimit: number;
+  skipList?: Set<string>;
+}
+/** Context exposed to {@link TValidatorPlugin} functions. */
+interface TValidatorPluginContext {
+  opts: Validator<any>['opts'];
+  validateAnnotatedType: Validator<any>['validateAnnotatedType'];
+  error: Validator<any>['error'];
+  path: Validator<any>['path'];
+  context: unknown;
+}
+/**
+ * Validates values against an {@link TAtscriptAnnotatedType} definition.
+ *
+ * `DataType` is automatically inferred from the type definition's phantom generic,
+ * enabling the {@link validate} method to act as a type guard.
+ *
+ * @example
+ * ```ts
+ * // From a generated interface class:
+ * const validator = new Validator(MyInterface)
+ * if (validator.validate(data, true)) {
+ *   data // narrowed to MyInterface
+ * }
+ *
+ * // Or use the built-in factory:
+ * MyInterface.validator().validate(data)
+ * ```
+ *
+ * @typeParam T - The annotated type definition.
+ * @typeParam DataType - The TypeScript type that `validate` narrows to (auto-inferred).
+ */
+declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+  protected readonly def: T;
+  protected opts: TValidatorOptions;
+  protected hasPlugins: boolean;
+  protected hasReplace: boolean;
+  private replaceCache?;
+  constructor(def: T, opts?: Partial<TValidatorOptions>);
+  /** Validation errors collected during the last {@link validate} call. */
+  errors: TError[];
+  protected stackErrors: Array<TError[] | null>;
+  protected pathSegments: string[];
+  protected depth: number;
+  protected limitExceeded: boolean;
+  protected context: unknown;
+  protected buildPath(): string;
+  protected push(name: string): void;
+  protected pop(saveErrors: boolean): TError[] | null | undefined;
+  protected clear(): void;
+  protected error(message: string, path?: string, details?: TError[]): void;
+  protected throw(): void;
+  /**
+   * Validates a value against the type definition.
+   *
+   * Acts as a TypeScript type guard — when it returns `true`, the value
+   * is narrowed to `DataType`.
+   *
+   * @param value - The value to validate.
+   * @param safe - If `true`, returns `false` on failure instead of throwing.
+   * @returns `true` if the value matches the type definition.
+   * @throws {ValidatorError} When validation fails and `safe` is not `true`.
+   */
+  validate<TT = DataType>(value: any, safe?: boolean, context?: unknown): value is TT;
+  protected validateSafe(def: TAtscriptAnnotatedType, value: any): boolean;
+  protected get path(): string;
+  protected validateAnnotatedType(def: TAtscriptAnnotatedType, value: any): boolean;
+  protected validateUnion(def: TAtscriptAnnotatedType<TAtscriptTypeComplex>, value: any): boolean;
+  protected validateIntersection(def: TAtscriptAnnotatedType<TAtscriptTypeComplex>, value: any): boolean;
+  protected validateTuple(def: TAtscriptAnnotatedType<TAtscriptTypeComplex>, value: any): boolean;
+  protected validateArray(def: TAtscriptAnnotatedType<TAtscriptTypeArray>, value: any): boolean;
+  protected validateObject(def: TAtscriptAnnotatedType<TAtscriptTypeObject>, value: any): boolean;
+  protected validatePrimitive(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: any): boolean;
+  protected validateString(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: string): boolean;
+  protected validateNumber(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: number): boolean;
+  protected validateBoolean(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: boolean): boolean;
+}
+/** Error thrown by {@link Validator.validate} when validation fails. Contains structured error details. */
+/** Type definition for union, intersection, or tuple types. */
+interface TAtscriptTypeComplex<DataType = unknown> {
+  kind: 'union' | 'intersection' | 'tuple';
+  items: TAtscriptAnnotatedType[];
+  tags: Set<AtscriptPrimitiveTags>;
+  /** @internal phantom — carries the DataType at the type level, never set at runtime */
+  __dataType?: DataType;
+}
+/** Type definition for array types. */
+interface TAtscriptTypeArray<DataType = unknown[]> {
+  kind: 'array';
+  of: TAtscriptAnnotatedType;
+  tags: Set<AtscriptPrimitiveTags>;
+  /** @internal phantom — carries the DataType at the type level, never set at runtime */
+  __dataType?: DataType;
+}
+/** Type definition for object types with named and pattern-matched properties. */
+interface TAtscriptTypeObject<K extends string = string, DataType = Record<K, unknown>> {
+  kind: 'object';
+  props: Map<K, TAtscriptAnnotatedType>;
+  propsPatterns: Array<{
+    pattern: RegExp;
+    def: TAtscriptAnnotatedType;
+  }>;
+  tags: Set<AtscriptPrimitiveTags>;
+  /** @internal phantom — carries the DataType at the type level, never set at runtime */
+  __dataType?: DataType;
+}
+/** Type definition for primitive/literal types (string, number, boolean, null, etc.). */
+interface TAtscriptTypeFinal<DataType = unknown> {
+  kind: '';
+  /**
+   * design type
+   */
+  designType: 'string' | 'number' | 'boolean' | 'undefined' | 'null' | 'object' | 'any' | 'never' | 'phantom' | 'decimal';
+  /**
+   * value for literals
+   */
+  value?: string | number | boolean;
+  tags: Set<AtscriptPrimitiveTags>;
+  /** @internal phantom — carries the DataType at the type level, never set at runtime */
+  __dataType?: DataType;
+}
+/**
+ * Extract DataType from a type def's phantom generic
+ */
+type InferDataType<T> = T extends {
+  __dataType?: infer D;
+} ? D : unknown;
+/**
+ * Extract the DataType from a {@link TAtscriptAnnotatedType}.
+ *
+ * Resolves the phantom `__dataType` carried by the type definition.
+ * When `__dataType` is `unknown` (unset), falls back to the constructor
+ * instance type if `T` is also a class (i.e. a generated interface).
+ *
+ * @example
+ * ```ts
+ * import type { TAtscriptDataType } from '@atscript/typescript/utils'
+ * import MyInterface from './my-interface.as'
+ *
+ * type Data = TAtscriptDataType<typeof MyInterface>
+ * ```
+ */
+type TAtscriptDataType<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> = T extends {
+  type: {
+    __dataType?: infer D;
+  };
+} ? unknown extends D ? T extends (new (...args: any[]) => infer I) ? I : unknown : D : unknown;
+/** Union of all possible type definition shapes. */
+type TAtscriptTypeDef<DataType = unknown> = TAtscriptTypeComplex<DataType> | TAtscriptTypeFinal<DataType> | TAtscriptTypeArray<DataType> | TAtscriptTypeObject<string, DataType>;
+/**
+ * Core annotated type — wraps a type definition with metadata and a validator factory.
+ *
+ * Generated `.as` files produce classes/namespaces that conform to this interface.
+ * The `DataType` phantom generic carries the TypeScript data shape for type-safe validation.
+ *
+ * @typeParam T - The underlying type definition (e.g. {@link TAtscriptTypeObject}).
+ * @typeParam DataType - The TypeScript type the validated data narrows to (auto-inferred from `T`).
+ */
+interface TAtscriptAnnotatedType<T extends TAtscriptTypeDef = TAtscriptTypeDef, DataType = InferDataType<T>> {
+  __is_atscript_annotated_type: true;
+  type: T;
+  validator(opts?: Partial<TValidatorOptions>): Validator<this, DataType>;
+  metadata: TMetadataMap<AtscriptMetadata>;
+  optional?: boolean;
+  id?: string;
+  ref?: {
+    type: () => TAtscriptAnnotatedType;
+    field: string;
+  };
+}
+/** An annotated type that is also a class constructor (i.e. a generated interface class). */
+/**
+ * Atscript Metadata Map with typed setters/getters
+ */
+interface TMetadataMap<O extends object> extends Map<keyof O, O[keyof O]> {
+  get<K extends keyof O>(key: K): O[K] | undefined;
+  get(key: string): unknown;
+  set<K extends keyof O>(key: K, value: O[K]): this;
+  has<K extends keyof O>(key: K): boolean;
+  has(key: string): boolean;
+}
+/** Fluent builder handle returned by {@link defineAnnotatedType}. */
+//#endregion
+//#region src/composables/create-as-form-def.d.ts
+/**
+ * Creates a reactive form definition and data object from an ATScript annotated type.
+ *
+ * @param type - An ATScript annotated type (imported from a `.as` file).
+ * @param context - Optional context object forwarded to `ui.fn.value` resolvers during data creation.
+ *   Only effective when `@atscript/ui-fns` is installed (dynamic resolver).
+ * @returns `{ def, formData }` — the FormDef and a Vue reactive data object with defaults applied
+ */
+declare function createAsFormDef<T extends TAtscriptAnnotatedType>(type: T, context?: Record<string, unknown>): {
+  def: _atscript_ui0.FormDef;
+  formData: {
+    value: vue.UnwrapRef<TAtscriptDataType<T>>;
+  };
+};
+//#endregion
+//#region src/composables/create-default-types.d.ts
+/**
+ * Returns a fresh type-to-component map pre-filled with all built-in defaults.
+ *
+ * Spread or assign additional entries to extend with custom field types:
+ * ```ts
+ * const types = { ...createDefaultTypes(), rating: MyRatingComponent }
+ * ```
+ */
+declare function createDefaultTypes(): TAsTypeComponents;
+//#endregion
+//#region src/composables/types.d.ts
+type TFormRule<TValue, TFormData, TContext> = (v: TValue, data?: TFormData, context?: TContext) => boolean | string;
+interface TFormFieldCallbacks {
+  validate: () => boolean | string;
+  clearErrors: () => void;
+  reset: () => void;
+  setExternalError: (msg?: string) => void;
+}
+interface TFormFieldRegistration {
+  path: () => string;
+  callbacks: TFormFieldCallbacks;
+}
+interface TFormState {
+  firstSubmitHappened: boolean;
+  firstValidation: "on-change" | "touched-on-blur" | "on-blur" | "on-submit" | "none";
+  /**
+   * Fields registered AFTER `firstSubmitHappened` flipped to true. They stay
+   * in this set until either the user edits the field (model watch removes
+   * the id) or the next submit fires (set is cleared). Live validation is
+   * suppressed for these fields so a freshly-added array item doesn't render
+   * red required-field errors before the user has had a chance to type.
+   */
+  freshFields: Set<symbol>;
+  register: (id: symbol, registration: TFormFieldRegistration) => void;
+  unregister: (id: symbol) => void;
+}
+//#endregion
+//#region src/composables/use-as-field.d.ts
+interface UseAsFieldOptions<TValue = any, TFormData = any, TContext = any> {
+  getValue: () => TValue;
+  setValue: (v: TValue) => void;
+  rules?: TFormRule<TValue, TFormData, TContext>[];
+  path: () => string;
+  /** Value to set on reset. Defaults to `''`. Use `[]` for arrays, `{}` for objects. */
+  resetValue?: TValue;
+}
+interface UseAsFieldReturn<TValue = any> {
+  model: WritableComputedRef<TValue>;
+  error: ComputedRef<string | undefined>;
+  onBlur: () => void;
+  /**
+   * Reactive "changed-since-baseline" flag for THIS field. `true` when the
+   * form has `track-changes` enabled AND the field at `opts.path()` differs
+   * from the tracker's baseline. Recomputes whenever the change list does
+   * (delegates to the injected {@link AsFormPatchHandle.isDirtyPath}).
+   *
+   * Always `false` when tracking is off (no patch handle injected) — the
+   * handle is injected OPTIONALLY, so reading `isDirty` never throws.
+   * Granularity matches the change list: object/section containers light up
+   * via their leaves' prefix, whole-array fields via exact match; an
+   * array-ITEM leaf stays `false` (the array container lights up instead).
+   */
+  isDirty: ComputedRef<boolean>;
+}
+declare function useAsField<TValue = any, TFormData = any, TContext = any>(opts: UseAsFieldOptions<TValue, TFormData, TContext>): UseAsFieldReturn<TValue>;
+//#endregion
+//#region src/composables/use-as-state.d.ts
+/** Custom form-level validator. Returns `Record<path, message>` (empty = passed). */
+type TFormSubmitValidator = () => Record<string, string>;
+interface UseAsStateReturn {
+  formState: TFormState;
+  clearErrors: () => void;
+  reset: () => Promise<void>;
+  submit: () => true | {
+    path: string;
+    message: string;
+  }[];
+  setErrors: (errors: Record<string, string>) => void;
+}
+declare function useAsState<TFormData, TContext>(opts: {
+  formData: MaybeRef<TFormData>;
+  formContext?: MaybeRef<TContext>;
+  firstValidation?: MaybeRef<TFormState["firstValidation"] | undefined>; /** When provided, replaces per-field iteration on submit. */
+  submitValidator?: TFormSubmitValidator;
+}): UseAsStateReturn;
+//#endregion
+//#region src/composables/use-as-form-patch.d.ts
+/**
+ * Result of {@link AsFormPatchHandle.rebaseOnto}. Aliases the `@atscript/ui`
+ * rebase shape (minus `next`, which is written into the live container rather
+ * than returned): the surviving local diff on top of the NEW baseline plus the
+ * conflict paths.
+ */
+interface RebaseOntoResult {
+  /** Paths changed on both sides to different values, plus ancestor-clear paths. */
+  conflicts: string[];
+  /** Local edits that survive on top of the new (upstream) baseline. */
+  reapplied: FormFieldChange[];
+}
+/**
+ * Change-tracking handle for a single `<AsForm>`. Exposed three ways:
+ *
+ * 1. injected via {@link useAsFormPatch} inside any descendant component,
+ * 2. spread into every `<AsForm>` slot (`isDirty` / `changes` / `getPatch` /
+ *    `getChanges` — so a footer slot can gate a Save button), and
+ * 3. `defineExpose`d on `<AsForm>` (so a parent template ref can call
+ *    `asForm.value.getPatch()`).
+ *
+ * Built on `@atscript/ui`'s `buildFormDiff`, which diffs the form's CURRENT
+ * data against a BASELINE snapshot and produces both a per-field change list
+ * and an `@atscript/db` patch object (keyed-array `$update`/`$insert`/`$remove`,
+ * `$cas` optimistic-concurrency sibling, revert-aware).
+ */
+interface AsFormPatchHandle {
+  /**
+   * Reactive dirtiness — `true` when current data differs from the baseline.
+   * Revert-aware: a value edited back to its baseline flips this back to
+   * `false`. Memoised by Vue; recomputes only when the form data changes.
+   */
+  isDirty: ComputedRef<boolean>;
+  /**
+   * Reactive per-field change list (revert-aware — reverted fields drop out).
+   * `before` / `after` hold live references into the baseline / current data.
+   */
+  changes: ComputedRef<FormFieldChange[]>;
+  /**
+   * Builds the `@atscript/db` patch object on demand against the baseline
+   * snapshot. Safe to call at submit time (a fresh re-snapshot point). Returns
+   * `{}` when nothing changed. Carries a top-level `$cas` sibling when the form
+   * has a `@db.column.version` column and `opts.cas` is on (default).
+   */
+  getPatch: (opts?: FormDiffOptions) => Record<string, unknown>;
+  /** Builds the per-field change list on demand (same data as `changes`). */
+  getChanges: () => FormFieldChange[];
+  /**
+   * Reactive per-field dirty predicate. `true` when the field at the dot-path
+   * `path` differs from the baseline. Reads the reactive {@link changes} list,
+   * so a per-field `isDirty` derived from this recomputes whenever the change
+   * list does.
+   *
+   * Granularity matches the change list (leaf-grained for scalars/objects,
+   * WHOLE-ARRAY for arrays): a field is dirty iff some change path equals
+   * `path` OR starts with `path + "."`. Object/section containers light up via
+   * the prefix branch; whole-array fields via exact match; an array-ITEM leaf
+   * (e.g. `items.0.qty`) returns `false` (the array container lights up
+   * instead — a known, documented limitation of the array diff). The empty
+   * root path `''` is dirty iff there are ANY changes. Backed by an O(1)
+   * `Set.has` against `@atscript/ui`'s `collectDirtyPaths` precompute, whose
+   * membership matches `isPathDirty` exactly (locked by an invariant test).
+   */
+  isDirtyPath: (path: string) => boolean;
+  /**
+   * Re-baseline to the current data. Call after a successful save so the form
+   * becomes clean again WITHOUT a remount. No-op when tracking is inactive.
+   */
+  rebase: () => void;
+  /**
+   * 3-way rebase onto a fresh upstream snapshot. Sets the baseline to
+   * `upstream` and rewrites the live form to `upstream` + the local diff
+   * (current vs. old baseline) reapplied on top:
+   *
+   * - fields the user never touched adopt `upstream`'s value,
+   * - local edits survive,
+   * - fields changed on both sides to a different value are conflicts, resolved
+   *   by `opts.conflict` (`'ours'` default keeps local, `'theirs'` takes
+   *   upstream).
+   *
+   * `upstream` is the WRAPPED form-data container (`{ value }`). The live form
+   * data is rewritten in a SINGLE mutation (the bound `:form-data` container
+   * identity is preserved, so the consumer's ref stays the same object). After
+   * the write the baseline becomes a deep clone of `upstream`, so a subsequent
+   * `getPatch()` carries exactly the surviving local diff (`reapplied`).
+   *
+   * Returns the conflict paths and the surviving local diff. No-op returning
+   * empty when tracking is inactive.
+   */
+  rebaseOnto: (upstream: Record<string, unknown>, opts?: FormRebaseOptions) => RebaseOntoResult;
+}
+/**
+ * Reactive read-only access to the form's change-tracking handle from any
+ * descendant of an `<AsForm track-changes>`. Mirrors the `useAsData` /
+ * `useAsPath` injector pattern.
+ *
+ * THROWS when called outside a form, or inside a form that did not enable
+ * `track-changes` — fail loud rather than silently report "not dirty".
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useAsFormPatch } from "@atscript/vue-form";
+ * const { isDirty, getPatch } = useAsFormPatch();
+ * </script>
+ * <template>
+ *   <button :disabled="!isDirty" @click="save(getPatch())">Save</button>
+ * </template>
+ * ```
+ */
+declare function useAsFormPatch(): AsFormPatchHandle;
+//#endregion
+//#region src/composables/use-as-form.d.ts
+/**
+ * Options for {@link useAsForm}. Each reactive prop is supplied as a
+ * **getter** so the composable can subscribe to its changes without owning
+ * a `Ref`. Pass component-level `defineProps` accessors verbatim:
+ *
+ * ```ts
+ * useAsForm({
+ *   def: () => props.def,
+ *   formData: () => props.formData,
+ *   types: () => props.types,
+ *   // ...
+ *   emits: { submit: (data) => emit("submit", data), ... },
+ * })
+ * ```
+ *
+ * Generic `TFormData` / `TFormContext` mirror the `<AsForm>` component
+ * generics. They flow through to emitted callbacks; if you build a custom
+ * form root with a known data shape, pin them at the call site.
+ */
+interface UseAsFormOptions<TFormData = unknown, TFormContext = unknown> {
+  /** Form definition produced by `createAsFormDef(type)`. Reactive. */
+  def: () => FormDef;
+  /**
+   * Externally-managed form data container `{ value: domainData }`. When
+   * unset, the composable creates an internal one initialized to `{}`.
+   */
+  formData?: () => TFormData | undefined;
+  /** Reactive form context — exposed to validators, scope, slots, and emits. */
+  formContext?: () => TFormContext | undefined;
+  /** First-validation strategy. Defaults to `"on-change"`. */
+  firstValidation?: () => TFormState["firstValidation"] | undefined;
+  /** Custom field components keyed by field name (matches `Props.components`). */
+  components?: () => Record<string, Component<TAsComponentProps>> | undefined;
+  /** Type-to-component map keyed by field type (matches `Props.types`). */
+  types: () => TAsTypeComponents;
+  /** Server-supplied errors keyed by absolute dotted path (`__form` for form-level). */
+  errors?: () => Record<string, string | undefined> | undefined;
+  /** Per-form value-help client factory. Falls back to the app-wide default when unset. */
+  clientFactory?: () => ClientFactory | undefined;
+  /** Suppress the root field's title (use when the chrome already shows the form's label). */
+  hideRootTitle?: () => boolean | undefined;
+  /**
+   * Busy-state flag. When `true`, the form is locked (inert + overlay) and the
+   * default submit button is disabled. `<AsWfForm>` wires this to its
+   * server round-trip so consumers can drop their own submit overrides.
+   */
+  loading?: () => boolean | undefined;
+  /**
+   * Enable change tracking. When `true`, the composable captures a deep-clone
+   * baseline of the form data (the moment it becomes available) and exposes a
+   * {@link AsFormPatchHandle} via `slotProps`, the return value (`patch`), and
+   * `provide(FORM_PATCH_KEY)` (read with `useAsFormPatch()`). When falsy
+   * (default), there is ZERO overhead — no baseline, no deep watch, and
+   * `useAsFormPatch()` throws. Reactive.
+   */
+  trackChanges?: () => boolean | undefined;
+  /**
+   * Outbound callbacks. Customer form roots typically wire these to
+   * `defineEmits`; advanced uses can pass plain functions.
+   */
+  emits?: {
+    submit?: (data: TFormData) => void;
+    error?: (errors: {
+      path: string;
+      message: string;
+    }[]) => void;
+    action?: (name: string, data: TFormData) => void;
+    unsupportedAction?: (name: string, data: TFormData) => void;
+    change?: (type: TAsChangeType, path: string, value: unknown, formData: TFormData) => void;
+  };
+}
+interface UseAsFormReturn<TFormData = unknown, TFormContext = unknown> {
+  /** Reactive form-data container `{ value: domainData }`. */
+  data: ComputedRef<TFormData>;
+  /** Effective external errors (post-dismissal), excluding `__form`. */
+  errors: ComputedRef<Record<string, string | undefined> | undefined>;
+  /** Form-level error message (post banner-dismissal). */
+  formError: ComputedRef<string | undefined>;
+  /** Errors discovered by the local validator on the most-recent submit. */
+  internalErrors: Ref<Record<string, string>>;
+  /**
+   * Reset internal validator + dismissal state and re-run field defaults. When
+   * `trackChanges` is enabled, also re-baselines the change tracker to the
+   * post-reset state (the form becomes clean again).
+   */
+  reset: () => Promise<void>;
+  /** Imperatively clear errors (matches `useAsState().clearErrors`). */
+  clearErrors: () => void;
+  /** Imperatively set external-error messages by path. */
+  setErrors: (errors: Record<string, string>) => void;
+  /** Trigger submit. Emits `submit` on success and `error` on validation failure. */
+  onSubmit: () => void;
+  /** Resolved submit-button text (`@ui.form.submit.text` / fn variant). */
+  submitText: ComputedRef<string>;
+  /** Resolved submit-button disabled state (`@ui.form.fn.submitDisabled`). */
+  submitDisabled: ComputedRef<boolean>;
+  /** Resolved form-level title (`@ui.form.fn.title` / `@meta.label`); may be `undefined`. */
+  title: ComputedRef<string | undefined>;
+  /** Resolved form-level description (`@ui.form.fn.description` / `@meta.description`). */
+  description: ComputedRef<string | undefined>;
+  /** Unified slot-props bag spread onto every `<AsForm>` slot. */
+  slotProps: ComputedRef<{
+    title: string | undefined;
+    description: string | undefined;
+    data: TFormData;
+    errors: Record<string, string | undefined> | undefined;
+    formError: string | undefined;
+    disabled: boolean;
+    loading: boolean;
+    submitText: string;
+    submit: () => void;
+    reset: () => Promise<void>;
+    clearErrors: () => void;
+    setErrors: (errors: Record<string, string>) => void;
+    dismissError: (path: string) => void;
+    dismissFormError: () => void;
+    formContext: TFormContext | undefined; /** True when `track-changes` is on AND data differs from baseline. */
+    isDirty: boolean; /** Revert-aware per-field change list (empty when tracking is off). */
+    changes: readonly FormFieldChange[]; /** Build the `@atscript/db` patch on demand (`{}` when tracking is off). */
+    getPatch: (opts?: FormDiffOptions) => Record<string, unknown>; /** Build the per-field change list on demand (`[]` when tracking is off). */
+    getChanges: () => FormFieldChange[]; /** Per-field dirty predicate (`false` for every path when tracking is off). */
+    isDirtyPath: (path: string) => boolean;
+  }>;
+  /**
+   * Change-tracking handle — present ONLY when `trackChanges` is enabled.
+   * `undefined` otherwise. Read it from descendants with `useAsFormPatch()`.
+   */
+  patch: AsFormPatchHandle | undefined;
+  /**
+   * Remount key for the field subtree. Bound as `:key` on the root `<AsField>`.
+   * Bumped by `patch.rebaseOnto` only when a rebase lands a different union
+   * variant, forcing the variant picker to re-detect. `0` otherwise.
+   */
+  remountKey: Ref<number>;
+  /** Dispatch an action — invoked by `<AsAction>`. */
+  invokeAction: (name: string) => void;
+  /** Dismiss a single external leaf error. */
+  dismissError: (path: string) => void;
+  /** Dismiss the form-level banner. */
+  dismissFormError: () => void;
+  /** Form-context getter (mirrors `options.formContext()`). */
+  formContext: ComputedRef<TFormContext | undefined>;
+  /** Internal change-dispatcher used by `<AsField>` and structured components. */
+  handleChange: (type: TAsChangeType, path: string, value: unknown) => void;
+}
+/**
+ * Composable backing `<AsForm>`. Owns the entire form state machine —
+ * data container, internal validator, external-error dismissal, action
+ * routing, change merging, descendant counts, auto-open, and all
+ * provide/inject wiring. Customers building a custom form root can
+ * call this directly and render their own `<form>` template.
+ *
+ * MUST be called from a component's `<script setup>` (it issues
+ * `provide()` calls that need an active component instance).
+ */
+declare function useAsForm<TFormData = unknown, TFormContext = unknown>(options: UseAsFormOptions<TFormData, TFormContext>): UseAsFormReturn<TFormData, TFormContext>;
+//#endregion
+//#region src/composables/use-as-external-errors.d.ts
+/**
+ * Source of externally-supplied (server) errors. Reading this getter
+ * inside a Vue reactive scope subscribes the composable to identity
+ * changes — when the source returns a *different* object reference
+ * (typically a fresh server response), all locally-applied dismissals
+ * reset automatically.
+ */
+interface UseAsExternalErrorsOptions {
+  source: () => Record<string, string | undefined> | undefined;
+}
+interface UseAsExternalErrorsReturn {
+  /**
+   * Errors map after leaf-path dismissals applied. The `__form` key is
+   * always omitted — render form-level errors via `formError`. Returns
+   * `undefined` when the source itself is `undefined` (no errors at all),
+   * so consumers can preserve the original "errors prop unset" semantics.
+   */
+  effective: ComputedRef<Record<string, string | undefined> | undefined>;
+  /** Top-level `__form` error (post banner-dismissal). `undefined` while dismissed or absent. */
+  formError: ComputedRef<string | undefined>;
+  /** Whether the form-level banner is currently dismissed. */
+  isFormDismissed: ComputedRef<boolean>;
+  /** Mark a leaf-field path as dismissed locally. Idempotent. */
+  dismissAt: (path: string) => void;
+  /** Dismiss the form-level banner. */
+  dismissForm: () => void;
+  /** Reset all dismissals (rarely needed; identity-change does this for you). */
+  reset: () => void;
+}
+/**
+ * Local dismissal state for externally-supplied errors.
+ *
+ * - `dismissAt(path)` hides a leaf error until either the user un-dismisses
+ *   it or a *fresh* errors object arrives (new identity).
+ * - `dismissForm()` hides the `__form` banner. Same identity-reset rule, but
+ *   never cleared by leaf calls.
+ * - In-place mutation of the source object does NOT reset dismissals; only
+ *   identity changes do. A fresh response (`errors.value = { ... }`) re-arms
+ *   everything, while in-place tweaks (rare) deliberately preserve them.
+ *
+ * The composable is pure — it does NOT call `provide()`. The owning form
+ * composable wires `dismissAt` into the form's inject contract.
+ */
+declare function useAsExternalErrors(options: UseAsExternalErrorsOptions): UseAsExternalErrorsReturn;
+//#endregion
+//#region src/composables/use-as-array.d.ts
+interface UseAsArrayReturn {
+  arrayValue: ComputedRef<unknown[]>;
+  itemKeys: string[];
+  isUnion: boolean;
+  unionVariants: FormUnionVariant[];
+  isOptional: boolean;
+  isEmpty: ComputedRef<boolean>;
+  getItemField: (index: number, name?: string) => FormFieldDef;
+  addItem: (variantIndex?: number) => void;
+  removeItem: (index: number) => void;
+  clear: () => void;
+  canAdd: ComputedRef<boolean>;
+  canRemove: ComputedRef<boolean>;
+}
+/**
+ * Composable for managing array field state.
+ *
+ * Manages stable keys, add/remove with constraints, and item field resolution.
+ * Union item types are handled transparently — AsUnion manages variant state locally.
+ * Used by the default `AsArray` component and available for custom array components.
+ */
+declare function useAsArray(field: FormArrayFieldDef, disabled?: ComputedRef<boolean>): UseAsArrayReturn;
+//#endregion
+//#region src/composables/use-as-tuple.d.ts
+interface UseAsTupleReturn {
+  itemFields: FormFieldDef[];
+  positionLabeled: boolean[];
+  isOptional: boolean;
+  isEmpty: ComputedRef<boolean>;
+  clear: () => void;
+  fillMissing: () => void;
+}
+/** Composable for managing tuple field state. Fixed-length, position-typed; auto-fills missing positions on mount unless optional. */
+declare function useAsTuple(field: FormTupleFieldDef): UseAsTupleReturn;
+//#endregion
+//#region src/composables/use-as-union.d.ts
+interface UseAsUnionReturn {
+  unionField: ComputedRef<FormUnionFieldDef | undefined>;
+  hasMultipleVariants: ComputedRef<boolean>;
+  localUnionIndex: Ref<number>;
+  innerField: ComputedRef<FormFieldDef | undefined>;
+  changeVariant: (newIndex: number) => void;
+  optionalEnabled: ComputedRef<boolean>;
+}
+/** Composable for union field state. Switching variants stashes per-index data so toggling back restores user's work instead of fresh defaults. */
+declare function useAsUnion(props: TAsComponentProps): UseAsUnionReturn;
+//#endregion
+//#region src/composables/use-form-context.d.ts
+/**
+ * Consume and clear the union context injection.
+ *
+ * Structured components (object, tuple, array, field-shell) call this to
+ * read the union context provided by `AsUnion` and immediately clear it
+ * so nested children don't inherit it.
+ */
+declare function useAsUnionVariant(): TAsUnionContext | undefined;
+/** Split a label into base + optional `#N` suffix for two-part rendering. */
+declare function formatIndexedLabelParts(label: string | undefined, arrayIndex: number | undefined): {
+  base: string;
+  suffix?: string;
+} | undefined;
+//#endregion
+//#region src/composables/use-as-value-help.d.ts
+interface UseAsValueHelpOptions {
+  info: ValueHelpInfo;
+  model: {
+    value: unknown;
+  };
+  onBlur: () => void;
+}
+type UseAsValueHelpStatus = "loading" | "ready" | "error";
+interface UseAsValueHelpReturn {
+  resolved: ShallowRef<ResolvedValueHelp | null>;
+  status: Ref<UseAsValueHelpStatus>;
+  searchText: Ref<string>;
+  results: ShallowRef<Record<string, unknown>[]>;
+  searching: Ref<boolean>;
+  labelIsFkValue: ComputedRef<boolean>;
+  kickoff: () => Promise<void>;
+  selectItem: (item: Record<string, unknown>) => void;
+  clear: () => void;
+}
+declare function useAsValueHelp(options: UseAsValueHelpOptions): UseAsValueHelpReturn;
+//#endregion
+//#region src/composables/use-as-dropdown.d.ts
+declare function useAsDropdown(containerRef: Ref<HTMLElement | null>): {
+  isOpen: Ref<boolean, boolean>;
+  toggle: () => void;
+  close: () => void;
+  select: (callback: () => void) => void;
+};
+//#endregion
+//#region src/composables/use-as-nested-sections-store.d.ts
+/**
+ * Reactive open/closed registry for collapsible object sections rendered
+ * by `AsObject`. Provided once per `<AsForm>` so the entire form shares a
+ * single store; consumers (page chrome, devtools, dialogs) can `inject`
+ * the store via `useAsNestedSectionsStore()` to drive Expand-all /
+ * Collapse-all UI without prop drilling.
+ *
+ * **Default state is closed.** IDs only enter `open` when explicitly
+ * expanded (user click, native `<details>` toggle, programmatic
+ * `setOpen` / `expandAll`). The native `<details>` toggle event syncs
+ * back via `setOpen(id, open)` (idempotent, so browser find-in-page
+ * auto-opens don't fight the store).
+ */
+interface AsNestedSectionsStore {
+  open: Ref<Set<string>>;
+  register: (id: string) => void;
+  unregister: (id: string) => void;
+  toggle: (id: string) => void;
+  setOpen: (id: string, open: boolean) => void;
+  isOpen: (id: string) => boolean;
+  expandAll: () => void;
+  collapseAll: () => void;
+  allOpen: () => boolean;
+}
+/**
+ * Create and provide a `AsNestedSectionsStore` to the current Vue subtree.
+ * Called automatically by `<AsForm>`, but exposed for cases where you
+ * want to scope a separate store (e.g. multiple independent forms in one
+ * page that should keep their open/closed state independent, or to drive
+ * page-level Expand-all / Collapse-all UI from above the form).
+ */
+declare function provideAsNestedSectionsStore(): AsNestedSectionsStore;
+/**
+ * Inject the nested-sections store provided by an ancestor `<AsForm>`
+ * (or by an explicit `provideAsNestedSectionsStore()` call). Returns
+ * `undefined` if no store is in scope.
+ */
+declare function useAsNestedSectionsStore(): AsNestedSectionsStore | undefined;
+//#endregion
+//#region src/composables/focus-after-toggle.d.ts
+/** Run an action, then focus the first focusable input descendant of `scope`. */
+declare function focusFirstAfter(action: () => void, scope: () => HTMLElement | null | undefined, ticks?: number): Promise<void>;
+/**
+ * Run an action, then focus the first focusable input that wasn't present
+ * before the action. Used by array Add buttons so the user lands on the
+ * just-added row's first input regardless of how many items already exist.
+ * Falls back to first focusable when nothing existed before (the typical
+ * "enable optional + add first item" flow).
+ */
+declare function focusNewFocusableAfter(action: () => void, scope: () => HTMLElement | null | undefined, ticks?: number): Promise<void>;
+/** Sugar over `focusFirstAfter` scoped to a template ref. */
+declare function useAsFocusFirstAfter(onToggleOptional?: (enabled: boolean) => void): {
+  rootRef: Ref<HTMLElement | null>;
+  runAndFocus: (action: () => void, ticks?: number) => void;
+  runAndFocusNew: (action: () => void, ticks?: number) => void;
+  enableOptional: () => void;
+};
+//#endregion
+//#region src/composables/use-as-optional-add-flow.d.ts
+/**
+ * Options for `useAsOptionalAddFlow`.
+ *
+ * The composable consolidates the "toggle optional → register with the
+ * nested-sections store → focus first new field" choreography that
+ * structured-field defaults (AsObject, AsArray, AsTuple, AsUnion) repeat
+ * every time the user clicks an empty-state Add affordance, an Add Item
+ * button, or a variant picker.
+ */
+interface UseAsOptionalAddFlowOptions {
+  /**
+   * Absolute dotted path to the field — used as the nested-sections-store
+   * key. Read via a getter so the composable always reads the latest value
+   * (the path can change when the field is rendered inside a union and the
+   * variant switches).
+   */
+  path: () => string | undefined;
+}
+interface UseAsOptionalAddFlowReturn {
+  /**
+   * Wrap a user-supplied action so that running it also expands the
+   * containing section in the nested-sections store. Pass the wrapped
+   * action to `AsCollapsible#runAndFocusNew` (which owns its own focus
+   * scope) so the focus query lands on the freshly mounted subtree.
+   *
+   * The wrapper is a no-op for the store-register step when no store is
+   * provided in scope (e.g. a custom default mounted standalone) — focus
+   * still happens via the host's `runAndFocusNew`.
+   */
+  composeAction: (action: () => void) => () => void;
+  /**
+   * Sugar for the case where the call site does not have an
+   * `AsCollapsible` to delegate focus to (e.g. AsUnion's empty-state
+   * picker, which mounts its own `<div>`). Wraps the action with
+   * store-open registration, then runs it inside `focusNewFocusableAfter`.
+   *
+   * Returns the same Promise `focusNewFocusableAfter` returns so callers
+   * can `await` if they need to.
+   */
+  runAndFocusNew: (scope: () => HTMLElement | null | undefined, action: () => void, ticks?: number) => Promise<void>;
+}
+/**
+ * Choreography composable for "enable-optional + add + focus-first-new"
+ * flows. The four built-in structured-field defaults consume it; custom
+ * implementations of object/array/tuple/union components can use it too
+ * to get the same UX (smooth focus handoff after an empty-state click)
+ * without re-implementing the choreography.
+ *
+ * Pairs with:
+ *   - {@link useAsFocusFirstAfter} — focus mechanics (used by AsCollapsible)
+ *   - {@link useAsNestedSectionsStore} — open/closed state registry
+ *
+ * Typical use, inside an `as-object.vue` swap component:
+ * ```ts
+ * const { composeAction } = useAsOptionalAddFlow({ path: () => props.path });
+ * function handleAddData() {
+ *   collapsibleRef.value?.runAndFocusNew(
+ *     composeAction(() => props.onToggleOptional?.(true)),
+ *     2,
+ *   );
+ * }
+ * ```
+ */
+declare function useAsOptionalAddFlow(options: UseAsOptionalAddFlowOptions): UseAsOptionalAddFlowReturn;
+//#endregion
+//#region src/composables/use-as-tri-state-checkbox.d.ts
+/**
+ * Options for `useAsTriStateCheckbox`.
+ *
+ * Consolidates the "checked / unchecked / indeterminate" mechanics for
+ * boolean fields whose model can be `undefined` (optional booleans, or
+ * checkboxes that round-trip from a SQL NULL). HTML5's `indeterminate`
+ * is a property on the DOM element — not a reflectable attribute — so
+ * the composable wires it via a `watchEffect`.
+ */
+interface UseAsTriStateCheckboxOptions {
+  /**
+   * Reactive getter for the current model value. `undefined` renders the
+   * indeterminate look; `true` / `false` render checked / unchecked.
+   */
+  modelValue: () => boolean | undefined;
+  /**
+   * Called when the user toggles the checkbox. Receives the new value as
+   * read off the input's `checked` property after the click.
+   */
+  onCommit: (value: boolean) => void;
+}
+interface UseAsTriStateCheckboxReturn {
+  /**
+   * Bind to `<input type="checkbox" :checked>`. Equivalent to
+   * `modelValue() === true`.
+   */
+  checked: ComputedRef<boolean>;
+  /**
+   * `true` when the model is `undefined` — render the indeterminate
+   * look (the composable also wires the DOM property via `watchEffect`).
+   */
+  indeterminate: ComputedRef<boolean>;
+  /**
+   * Template ref for the `<input>` element. The composable observes it
+   * and writes the `indeterminate` property whenever the model becomes
+   * `undefined`.
+   */
+  inputRef: Ref<HTMLInputElement | null>;
+  /** Bind to `@change`. Reads `e.target.checked` and forwards to `onCommit`. */
+  onChange: (e: Event) => void;
+}
+/**
+ * Tri-state checkbox helper. The visible state is derived from the
+ * model: `true` checked, `false` unchecked, `undefined` indeterminate.
+ * Clicking commits a boolean — never `undefined` — because browsers do
+ * not emit a "tri-state click". The "back to undefined" path stays a
+ * separate optional-clear affordance owned by the host component.
+ *
+ * Use this composable in a custom checkbox swap component to inherit the
+ * same a11y / DOM-sync behaviour as the built-in `AsCheckbox` without
+ * re-implementing the `watchEffect` plumbing or remembering that
+ * `indeterminate` is a property, not an attribute.
+ */
+declare function useAsTriStateCheckbox(options: UseAsTriStateCheckboxOptions): UseAsTriStateCheckboxReturn;
+//#endregion
+//#region src/composables/use-as-locale.d.ts
+declare function provideAsLocale(getter: () => string | undefined): void;
+interface UseAsLocaleReturn {
+  /** Resolved locale; `undefined` when no provider is present (runtime locale). */
+  locale: ComputedRef<string | undefined>;
+}
+declare function useAsLocale(): UseAsLocaleReturn;
+//#endregion
+//#region src/composables/use-as-decimal.d.ts
+interface UseAsDecimalOptions {
+  /** Read the current value. Storage shape is preserved on commit. */
+  modelValue: () => string | number | null | undefined;
+  /**
+   * Effective display + edit scale. Composables truncate user-typed values
+   * to this so a paste of "10.99" into a JPY field doesn't propagate the
+   * lost ".99". Resolution lives at AsField — see TAsComponentProps.scale.
+   */
+  scale?: () => number | undefined;
+  /**
+   * Storage cap (DB column scale). Outgoing strings are padded to this
+   * regardless of `scale` — display can be tighter than storage. When
+   * absent, falls back to `scale`.
+   */
+  storageScale?: () => number | undefined;
+  /** Locale override; defaults to `useAsLocale()` then runtime locale. */
+  locale?: () => string | undefined;
+  /** Commit handler — receives the new value in the same shape as `modelValue()`. */
+  onCommit: (value: string | number | null) => void;
+}
+interface UseAsDecimalReturn {
+  /** Effective display + edit scale. Defaults to 2 when neither scale nor storageScale provided. */
+  scale: ComputedRef<number>;
+  /** Storage cap (always populated; falls back to effective scale, then 2). */
+  storageScale: ComputedRef<number>;
+  decimalSeparator: ComputedRef<string>;
+  thousandsSeparator: ComputedRef<string>;
+  /** Single-input renderers: locale-formatted decimal "1,234.50" / "1 234,50". */
+  displayValue: ComputedRef<string>;
+  /** Canonical decimal "1234.50": no thousands, "." separator, padded to effective scale. */
+  rawValue: ComputedRef<string>;
+  /** Split renderers: integer is grouped per locale for display. */
+  parts: ComputedRef<{
+    sign: "" | "-";
+    integer: string;
+    decimal: string;
+  }>;
+  /** Renderer received a complete typed value (single-input swap). */
+  setFromInput: (raw: string) => void;
+  /** Renderer captured the two halves separately (default two-input SFC). */
+  setFromParts: (sign: "" | "-", integer: string, decimal: string) => void;
+}
+/**
+ * Reactive composable for decimal-typed inputs (the `AsDecimal` SFC and
+ * customer swaps built against `TAsComponentProps`).
+ *
+ * Currency-agnostic: the SFC owns prefix/suffix render concerns and
+ * resolves the effective scale via the `scale` prop set by AsField. This
+ * composable just operates on the model with the scale given to it.
+ *
+ * Storage shape is preserved on commit — string `modelValue` commits a
+ * string padded to `storageScale`; number `modelValue` commits a number.
+ * A change to the effective `scale` getter that shrinks it below the
+ * model's actual precision triggers a re-round + re-commit (the same
+ * "currency-change" behaviour as before).
+ */
+declare function useAsDecimal(opts: UseAsDecimalOptions): UseAsDecimalReturn;
+//#endregion
+//#region src/composables/use-as-number.d.ts
+interface UseAsNumberOptions {
+  /** Read the current value. May be a string when authored externally; commit is always a `number` or `null`. */
+  modelValue: () => string | number | null | undefined;
+  /** Locale override; defaults to `useAsLocale()` then runtime locale. */
+  locale?: () => string | undefined;
+  /** Commit handler — receives a parsed `number`, or `null` for empty input. */
+  onCommit: (value: number | null) => void;
+}
+interface UseAsNumberReturn {
+  decimalSeparator: ComputedRef<string>;
+  /**
+   * Single-input renderers: raw model value with the locale decimal
+   * separator swap. No Intl grouping, no padding, no truncation — numbers
+   * aren't precision-critical the way decimals are.
+   */
+  displayValue: ComputedRef<string>;
+  /** Canonical decimal ("." separator). Verbatim from the model — no scale enforcement. */
+  rawValue: ComputedRef<string>;
+  /** Renderer received a complete typed value. */
+  setFromInput: (raw: string) => void;
+}
+/**
+ * Reactive composable that powers the default `AsNumber` SFC. Single-
+ * input shape — currency-agnostic, scale-agnostic, just a plain number
+ * with optional prefix/suffix chrome owned by the SFC.
+ *
+ * Commit shape is always a `number` (or `null` for empty input).
+ * atscript `number` fields are primitive `number` in the model — there
+ * is no precision-preservation reason to ship a string the way decimals
+ * do. The SFC owns prefix/suffix render concerns; this composable only
+ * knows about the value.
+ */
+declare function useAsNumber(opts: UseAsNumberOptions): UseAsNumberReturn;
+//#endregion
+//#region src/composables/use-as-dual-input.d.ts
+/**
+ * Keyboard plumbing for the bank-UX two-input pattern (integer + decimal
+ * halves joined by a separator pill). Extracted from the original
+ * AsAmount SFC so AsDecimal and any customer two-input renderer can
+ * share the same arrow-bridge / digit-overwrite / paste-split behaviour.
+ *
+ * This composable is render-agnostic — the SFC owns the layout, the
+ * shell chrome and the value model wiring. The composable just exposes
+ * the input refs, edit-state, focus handlers and event handlers wired
+ * to a `setFromParts` / `setFromInput` callback pair.
+ */
+interface UseAsDualInputOptions {
+  /** Effective scale (max digits in the decimal half). 0 → no decimal half. */
+  scale: () => number;
+  /** Locale-aware decimal separator (used for bridge-key detection). */
+  decimalSeparator: () => string;
+  /** Read the current parts. The composable owns NO model state. */
+  parts: () => {
+    sign: "" | "-";
+    integer: string;
+    decimal: string;
+  };
+  /** Read the canonical "X.YZ" string — used by paste/bridge to know current state. */
+  rawValue: () => string;
+  /** Commit a fresh split. Pure callback into the parent's state machine. */
+  setFromParts: (sign: "" | "-", integer: string, decimal: string) => void;
+  /** Commit a raw typed string (for paste). */
+  setFromInput: (raw: string) => void;
+  /** Called from `onBlurAll` after focus leaves both inputs. */
+  onBlur?: () => void;
+}
+interface UseAsDualInputReturn {
+  integerInput: Ref<HTMLInputElement | null>;
+  decimalInput: Ref<HTMLInputElement | null>;
+  /** Display string for the integer half — un-grouped while focused, grouped on blur. */
+  integerDisplay: ComputedRef<string>;
+  /** Display string for the decimal half — owns the suppression rules. */
+  decimalDisplay: ComputedRef<string>;
+  /** True while either input has focus. */
+  focusActive: Ref<boolean>;
+  onIntegerFocus: (e?: FocusEvent) => void;
+  onDecimalFocus: (e?: FocusEvent) => void;
+  onBlurAll: (e: FocusEvent) => void;
+  onIntegerInput: (e: Event) => void;
+  onIntegerKeydown: (e: KeyboardEvent) => void;
+  onIntegerPaste: (e: ClipboardEvent) => void;
+  onDecimalInput: (e: Event) => void;
+  onDecimalKeydown: (e: KeyboardEvent) => void;
+  onDecimalPaste: (e: ClipboardEvent) => void;
+}
+declare function useAsDualInput(opts: UseAsDualInputOptions): UseAsDualInputReturn;
+//#endregion
+//#region src/composables/use-as-date.d.ts
+/**
+ * Storage convention — atscript marks date-bearing fields with the
+ * `number.timestamp` primitive (epoch-ms numbers). The default form
+ * components mirror the cell-side rule: accept `Date | number | string`
+ * for read, commit back as `number` (epoch-ms) when storage is numeric,
+ * else commit the raw ISO string.
+ *
+ * `<input type="date">` uses `YYYY-MM-DD`,
+ * `<input type="datetime-local">` uses `YYYY-MM-DDTHH:mm`,
+ * `<input type="time">` uses `HH:mm`. The HTML5 spec treats these as
+ * locale-agnostic strings — we must produce them deterministically.
+ */
+type ModelValue = number | string | Date | null | undefined;
+interface UseAsDateOptions {
+  modelValue: () => ModelValue;
+  /** Variant: `'date'` (default), `'datetime'`, `'time'`. Drives both parse and serialize. */
+  kind: "date" | "datetime" | "time";
+  /** Commit the parsed value. Numeric epoch-ms when the previous value was numeric, ISO string otherwise. `null` clears. */
+  onCommit: (value: number | string | null) => void;
+}
+interface UseAsDateReturn {
+  /** HTML5 input type — `'date' | 'datetime-local' | 'time'`. */
+  inputType: "date" | "datetime-local" | "time";
+  /** Bind to `<input :value>`. Empty string when no model. */
+  displayValue: ComputedRef<string>;
+  /** Bind to `@change` / `@input`. Parses the HTML5 string into the storage type. */
+  setFromInput: (raw: string) => void;
+}
+/**
+ * Composable backing `AsDate` / `AsDatetime` / `AsTime`. Pick the variant
+ * via `kind`. Conversion direction:
+ *
+ * - `'date'`: epoch-ms ↔ `YYYY-MM-DD` (local TZ).
+ *   Empty input commits `null`. If previous value was a `string`,
+ *   commits a string (`YYYY-MM-DD`); otherwise commits epoch-ms (UTC
+ *   midnight on the picked date in local TZ — same as `new Date(str)`).
+ * - `'datetime'`: epoch-ms ↔ `YYYY-MM-DDTHH:mm` (local TZ).
+ * - `'time'`: prev-string ↔ `HH:mm`. Numeric storage isn't meaningful
+ *   for naked time-of-day, so we commit a string.
+ */
+declare function useAsDate(opts: UseAsDateOptions): UseAsDateReturn;
+//#endregion
+//#region src/composables/use-as-path.d.ts
+interface UseAsPathReturn {
+  path: ComputedRef<string>;
+}
+/**
+ * Reactive read-only access to the absolute dotted path prefix at the
+ * current point in the `<AsForm>` tree. Returns `''` when called outside
+ * a form.
+ */
+declare function useAsPath(): UseAsPathReturn;
+//#endregion
+//#region src/composables/use-as-type-map.d.ts
+interface UseAsTypeMapReturn {
+  types: ComputedRef<Record<string, Component>>;
+}
+/**
+ * Reactive read-only access to the type-to-component map provided by the
+ * nearest `<AsForm>`. Returns an empty map when called outside a form so
+ * call sites do not need a null-check.
+ */
+declare function useAsTypeMap(): UseAsTypeMapReturn;
+//#endregion
+//#region src/composables/use-as-data.d.ts
+interface UseAsDataReturn {
+  /** Domain data (the unwrapped inner value of the form's `{ value }` container). */
+  rootData: ComputedRef<unknown>;
+  /** Read the value at an absolute dotted path inside the form. */
+  getValueAt: (path: string) => ComputedRef<unknown>;
+  /** Read a sibling field's value relative to the current `useAsPath()` prefix. */
+  siblingValue: <T = unknown>(name: string) => ComputedRef<T | undefined>;
+}
+/**
+ * Reactive read-only access to form data at any point in the
+ * `<AsForm>` tree. Outside a form, all readers return `undefined`.
+ *
+ * Call sites get a `ComputedRef` so they can compose it directly with
+ * other reactive primitives without an extra `computed()` wrapper.
+ */
+declare function useAsData(): UseAsDataReturn;
+//#endregion
+//#region src/composables/use-as-error-dismiss.d.ts
+/**
+ * Imperative dismissal of an external (server-supplied) error at a given
+ * absolute path. Calling this is equivalent to the user editing that
+ * field — useful for custom field components that commit a value through
+ * a side-channel (e.g. a date picker dialog) and want to hide the
+ * server's error before the next round-trip.
+ */
+type AsErrorDismiss = (path: string) => void;
+/**
+ * Returns the `dismissExternalAt` callback provided by the nearest
+ * ancestor `<AsForm>`. Outside a form the result is a no-op so calling
+ * it from a leaf component does not throw.
+ */
+declare function useAsErrorDismiss(): AsErrorDismiss;
+//#endregion
+//#region src/components/as-form.vue.d.ts
+interface Props<TF, TC> {
+  def: FormDef;
+  formData?: TF;
+  formContext?: TC;
+  firstValidation?: TFormState["firstValidation"];
+  components?: Record<string, Component<TAsComponentProps>>;
+  /**
+   * Type-to-component map for field rendering. Maps field types to Vue components.
+   * Must include entries for all built-in field types. Use `createDefaultTypes()`
+   * for a pre-filled map, or supply your own.
+   */
+  types: TAsTypeComponents;
+  errors?: Record<string, string | undefined>;
+  /**
+   * Per-form client factory override. Creates `Client` instances from URL paths
+   * for FK value-help pickers inside this form. Falls back to the app-wide
+   * default (`setDefaultClientFactory`) and then to the built-in `new Client(url)`
+   * factory when unset.
+   */
+  clientFactory?: ClientFactory;
+  /**
+   * Suppress the root field's title rendering. Use when the form is mounted
+   * inside a chrome that already shows the form's `@meta.label` (e.g. a
+   * dialog header). Nested fields keep their own headings.
+   */
+  hideRootTitle?: boolean;
+  /**
+   * Suppress the default submit button. Use when the host chrome owns the
+   * submit affordance (e.g. a dialog footer with its own submit button
+   * wired via HTML5 `<button form="...">`). Vue 3 treats an empty
+   * `<template #form.submit />` as "slot not provided" and falls back to
+   * the default button — this prop is the explicit way to skip it.
+   */
+  hideSubmit?: boolean;
+  /**
+   * When true, freezes the form: the body becomes `inert` (blocks pointer
+   * events + keyboard focus) and a loading overlay paints over the entire
+   * form area. Used by `<AsWfForm>` to lock interaction during a server
+   * round-trip so the user can't edit a field whose response is racing in.
+   * Visual is shared with `<AsTable>`'s query overlay via vunor
+   * `inner-loading`.
+   */
+  loading?: boolean;
+  /**
+   * Enable change tracking. When set, the form captures a deep-clone baseline
+   * of its data and surfaces both a changed-fields list and an `@atscript/db`
+   * patch object. The tracking surface (`isDirty` / `changes` / `getPatch` /
+   * `getChanges`) is spread into every slot AND exposed on the component
+   * instance (template ref → `asForm.value.getPatch()`); descendants read it
+   * with `useAsFormPatch()`. Off by default — zero overhead when unset.
+   */
+  trackChanges?: boolean;
+}
+declare const __VLS_export: <TFormData = any, TFormContext = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: vue.PublicProps & __VLS_PrettifyLocal<Props<TFormData, TFormContext> & {
+    onError?: ((errors: {
+      path: string;
+      message: string;
+    }[]) => any) | undefined;
+    onAction?: ((name: string, data: TFormData) => any) | undefined;
+    onSubmit?: ((data: TFormData) => any) | undefined;
+    "onUnsupported-action"?: ((name: string, data: TFormData) => any) | undefined;
+    onChange?: ((type: TAsChangeType, path: string, value: unknown, formData: TFormData) => any) | undefined;
+  }> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: vue.ShallowUnwrapRef<{
+    submit: () => void;
+    reset: () => Promise<void>; /** True when `track-changes` is on AND data differs from baseline. */
+    readonly isDirty: boolean; /** Revert-aware per-field change list (empty when tracking is off). */
+    readonly changes: FormFieldChange[]; /** Build the `@atscript/db` patch object on demand (`{}` when off). */
+    getPatch: ((opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>) | (() => {}); /** Build the per-field change list on demand (`[]` when off). */
+    getChanges: () => FormFieldChange[];
+    /**
+     * Per-field dirty predicate — `true` when the field at `path` differs from
+     * the baseline (`false` for every path when tracking is off).
+     */
+    isDirtyPath: (path: string) => boolean; /** Re-baseline to current data after a successful save (no-op when off). */
+    rebase: () => void;
+    /**
+     * 3-way rebase onto a fresh upstream snapshot (sets baseline := upstream,
+     * reapplies the local diff). Pure no-op returning empty when tracking is off
+     * — NO side effects, mirroring `rebase`/`getPatch`.
+     */
+    rebaseOnto: (upstream: Record<string, unknown>, opts?: _atscript_ui0.FormRebaseOptions) => RebaseOntoResult;
+  }>) => void;
+  attrs: any;
+  slots: {
+    'form.header'?: (props: {
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.before'?: (props: {
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.after'?: (props: {
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.error'?: (props: {
+      message: string;
+      dismiss: () => void;
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.submit'?: (props: {
+      text: string;
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.footer'?: (props: {
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  } & {
+    'form.loading'?: (props: {
+      title: string | undefined;
+      description: string | undefined;
+      data: TFormData;
+      errors: Record<string, string | undefined> | undefined;
+      formError: string | undefined;
+      disabled: boolean;
+      loading: boolean;
+      submitText: string;
+      submit: () => void;
+      reset: () => Promise<void>;
+      clearErrors: () => void;
+      setErrors: (errors: Record<string, string>) => void;
+      dismissError: (path: string) => void;
+      dismissFormError: () => void;
+      formContext: TFormContext | undefined;
+      isDirty: boolean;
+      changes: readonly FormFieldChange[];
+      getPatch: (opts?: _atscript_ui0.FormDiffOptions) => Record<string, unknown>;
+      getChanges: () => FormFieldChange[];
+      isDirtyPath: (path: string) => boolean;
+    }) => any;
+  };
+  emit: {
+    (e: "submit", data: TFormData): void;
+    (e: "error", errors: {
+      path: string;
+      message: string;
+    }[]): void;
+    (e: "action", name: string, data: TFormData): void;
+    (e: "unsupported-action", name: string, data: TFormData): void;
+    (e: "change", type: TAsChangeType, path: string, value: unknown, formData: TFormData): void;
+  };
+}>) => vue.VNode & {
+  __ctx?: Awaited<typeof __VLS_setup>;
+};
+declare const _default: typeof __VLS_export;
+type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K] } : { [K in keyof T as K]: T[K] }) & {};
+//#endregion
+export { UseAsTupleReturn as $, UseAsLocaleReturn as A, focusNewFocusableAfter as B, useAsDualInput as C, createAsFormDef as Ct, UseAsDecimalOptions as D, useAsNumber as E, useAsTriStateCheckbox as F, useAsDropdown as G, AsNestedSectionsStore as H, UseAsOptionalAddFlowOptions as I, useAsValueHelp as J, UseAsValueHelpOptions as K, UseAsOptionalAddFlowReturn as L, useAsLocale as M, UseAsTriStateCheckboxOptions as N, UseAsDecimalReturn as O, UseAsTriStateCheckboxReturn as P, useAsUnion as Q, useAsOptionalAddFlow as R, UseAsDualInputReturn as S, createDefaultTypes as St, UseAsNumberReturn as T, provideAsNestedSectionsStore as U, useAsFocusFirstAfter as V, useAsNestedSectionsStore as W, useAsUnionVariant as X, formatIndexedLabelParts as Y, UseAsUnionReturn as Z, useAsPath as _, useAsField as _t, FormFieldChange$1 as a, useAsExternalErrors as at, useAsDate as b, TFormRule as bt, resetDefaultClientFactory as c, useAsForm as ct, useAsErrorDismiss as d, useAsFormPatch as dt, useAsTuple as et, UseAsDataReturn as f, TFormSubmitValidator as ft, UseAsPathReturn as g, UseAsFieldReturn as gt, useAsTypeMap as h, UseAsFieldOptions as ht, FormDiffOptions$1 as i, UseAsExternalErrorsReturn as it, provideAsLocale as j, useAsDecimal as k, setDefaultClientFactory as l, AsFormPatchHandle as lt, UseAsTypeMapReturn as m, useAsState as mt, _default as n, useAsArray as nt, FormRebaseOptions$1 as o, UseAsFormOptions as ot, useAsData as p, UseAsStateReturn as pt, UseAsValueHelpReturn as q, ClientFactory$1 as r, UseAsExternalErrorsOptions as rt, getDefaultClientFactory as s, UseAsFormReturn as st, Props as t, UseAsArrayReturn as tt, AsErrorDismiss as u, RebaseOntoResult as ut, UseAsDateOptions as v, TFormFieldCallbacks as vt, UseAsNumberOptions as w, UseAsDualInputOptions as x, TFormState as xt, UseAsDateReturn as y, TFormFieldRegistration as yt, focusFirstAfter as z };