@atscript/vue-form 0.1.58

package/dist/index.d.mts

@@ -0,0 +1,966 @@
+import _default$6 from "./as-field.mjs";
+import { a as TFormRule, i as TFormFieldRegistration, n as _default$8, o as TFormState, r as TFormFieldCallbacks } from "./as-form.vue-DRrb_yoj.mjs";
+import { a as TAsTypeComponents, i as TAsComponentProps, n as TAsChangeType, o as TAsUnionContext, r as TAsComponentEmits, t as TAsBaseComponentProps } from "./types-Czm-Gtud.mjs";
+import _default$10 from "./as-iterator.mjs";
+import { t as _default } from "./as-action.vue-CmY3eil1.mjs";
+import { t as _default$1 } from "./as-array.vue-C5r_ycIa.mjs";
+import { t as _default$2 } from "./as-checkbox.vue-BL53Xjmi.mjs";
+import { t as _default$3 } from "./as-date.vue-C5JaS3Sd.mjs";
+import { t as _default$4 } from "./as-datetime.vue-ClsSnJSV.mjs";
+import { t as _default$5 } from "./as-decimal.vue-CSCtYRRa.mjs";
+import { t as _default$7 } from "./as-field-shell.vue-Ddnp8KxY.mjs";
+import { t as _default$9 } from "./as-input.vue-fUhcvfv2.mjs";
+import { t as _default$11 } from "./as-number.vue-Bk-W7Vwv.mjs";
+import { t as _default$12 } from "./as-object.vue-Cg52b61-.mjs";
+import { t as _default$13 } from "./as-paragraph.vue-C3FgTEt5.mjs";
+import { t as _default$14 } from "./as-radio.vue-D_fweoN1.mjs";
+import { t as _default$15 } from "./as-ref.vue-Cr5jeNDn.mjs";
+import { t as _default$16 } from "./as-select.vue-RYpbZbKt.mjs";
+import { t as _default$17 } from "./as-time.vue-huLx2B4l.mjs";
+import { t as _default$18 } from "./as-tuple.vue-CQhzOJsn.mjs";
+import { t as _default$19 } from "./as-union.vue-BjlDPZn0.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, FormFieldDef, FormTupleFieldDef, FormUnionFieldDef, FormUnionVariant, ResolvedValueHelp, ValueHelpInfo, getDefaultClientFactory, resetDefaultClientFactory, setDefaultClientFactory } from "@atscript/ui";
+//#region ../../node_modules/.pnpm/@atscript+typescript@0.1.54_@atscript+core@0.1.54_@emnapi+core@1.9.2_@emnapi+runtime@1._3fc5d9e55a098ea8857b831f6196090c/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/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;
+}
+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.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$1 | undefined;
+  /** Suppress the root field's title (use when the chrome already shows the form's label). */
+  hideRootTitle?: () => 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. */
+  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>;
+  /** 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
+export { _default as AsAction, _default$1 as AsArray, _default$2 as AsCheckbox, _default$3 as AsDate, _default$4 as AsDatetime, _default$5 as AsDecimal, type AsErrorDismiss, _default$6 as AsField, _default$7 as AsFieldShell, _default$8 as AsForm, _default$9 as AsInput, _default$10 as AsIterator, type AsNestedSectionsStore, _default$11 as AsNumber, _default$12 as AsObject, _default$13 as AsParagraph, _default$14 as AsRadio, _default$15 as AsRef, _default$16 as AsSelect, _default$17 as AsTime, _default$18 as AsTuple, _default$19 as AsUnion, type ClientFactory, type TAsBaseComponentProps, type TAsChangeType, type TAsComponentEmits, type TAsComponentProps, type TAsTypeComponents, type TAsUnionContext, type TFormFieldCallbacks, type TFormFieldRegistration, type TFormRule, type TFormState, type TFormSubmitValidator, type UseAsArrayReturn, type UseAsDataReturn, type UseAsDateOptions, type UseAsDateReturn, type UseAsDecimalOptions, type UseAsDecimalReturn, type UseAsDualInputOptions, type UseAsDualInputReturn, type UseAsExternalErrorsOptions, type UseAsExternalErrorsReturn, type UseAsFieldOptions, type UseAsFieldReturn, type UseAsFormOptions, type UseAsFormReturn, type UseAsLocaleReturn, type UseAsNumberOptions, type UseAsNumberReturn, type UseAsOptionalAddFlowOptions, type UseAsOptionalAddFlowReturn, type UseAsPathReturn, type UseAsStateReturn, type UseAsTriStateCheckboxOptions, type UseAsTriStateCheckboxReturn, type UseAsTupleReturn, type UseAsTypeMapReturn, type UseAsUnionReturn, type UseAsValueHelpOptions, type UseAsValueHelpReturn, createAsFormDef, createDefaultTypes, focusFirstAfter, focusNewFocusableAfter, formatIndexedLabelParts, getDefaultClientFactory, provideAsLocale, provideAsNestedSectionsStore, resetDefaultClientFactory, setDefaultClientFactory, useAsArray, useAsData, useAsDate, useAsDecimal, useAsDropdown, useAsDualInput, useAsErrorDismiss, useAsExternalErrors, useAsField, useAsFocusFirstAfter, useAsForm, useAsLocale, useAsNestedSectionsStore, useAsNumber, useAsOptionalAddFlow, useAsPath, useAsState, useAsTriStateCheckbox, useAsTuple, useAsTypeMap, useAsUnion, useAsUnionVariant, useAsValueHelp };