@atscript/ui 0.1.58

package/dist/index.d.cts

@@ -0,0 +1,862 @@
+import { TAtscriptAnnotatedType, TAtscriptDataType, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin } from "@atscript/typescript/utils";
+import { Client, TCrudOp, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionLevel, TDbActionProcessor } from "@atscript/db-client";
+
+//#region src/shared/annotation-keys.d.ts
+declare const UI_TYPE: "ui.type";
+declare const UI_FORM_PLACEHOLDER: "ui.form.placeholder";
+declare const UI_FORM_HINT: "ui.form.hint";
+declare const UI_FORM_CLASSES: "ui.form.classes";
+declare const UI_FORM_STYLES: "ui.form.styles";
+declare const UI_FORM_AUTOCOMPLETE: "ui.form.autocomplete";
+declare const UI_FORM_DISABLED: "ui.form.disabled";
+declare const UI_FORM_OPTIONS: "ui.form.options";
+declare const UI_FORM_ORDER: "ui.form.order";
+declare const UI_FORM_TYPE: "ui.form.type";
+declare const UI_FORM_COMPONENT: "ui.form.component";
+declare const UI_FORM_HIDDEN: "ui.form.hidden";
+declare const UI_FORM_ATTR: "ui.form.attr";
+declare const UI_FORM_GRID_COL_SPAN: "ui.form.grid.colSpan";
+declare const UI_FORM_GRID_ROW_SPAN: "ui.form.grid.rowSpan";
+declare const UI_FORM_SUBMIT_TEXT: "ui.form.submit.text";
+declare const UI_FORM_LABEL_SINGULAR: "ui.form.label.singular";
+declare const UI_FORM_ACTION: "ui.form.action";
+declare const UI_FORM_PREFIX: "ui.form.prefix";
+declare const UI_FORM_PREFIX_REF: "ui.form.prefix.ref";
+declare const UI_FORM_PREFIX_ICON: "ui.form.prefix.icon";
+declare const UI_FORM_SUFFIX: "ui.form.suffix";
+declare const UI_FORM_SUFFIX_REF: "ui.form.suffix.ref";
+declare const UI_FORM_SUFFIX_ICON: "ui.form.suffix.icon";
+declare const UI_TABLE_WIDTH: "ui.table.width";
+declare const UI_TABLE_COMPONENT: "ui.table.component";
+declare const UI_TABLE_HIDDEN: "ui.table.hidden";
+declare const UI_TABLE_ATTR: "ui.table.attr";
+declare const UI_TABLE_CLASSES: "ui.table.classes";
+declare const UI_TABLE_STYLES: "ui.table.styles";
+declare const UI_TABLE_TYPE: "ui.table.type";
+declare const UI_TABLE_ORDER: "ui.table.order";
+declare const UI_DICT_LABEL: "ui.dict.label";
+declare const UI_DICT_DESCR: "ui.dict.descr";
+declare const UI_DICT_ATTR: "ui.dict.attr";
+declare const UI_DICT_FILTERABLE: "ui.dict.filterable";
+declare const UI_DICT_SORTABLE: "ui.dict.sortable";
+declare const UI_DICT_SEARCHABLE: "ui.dict.searchable";
+declare const DB_REL_FK: "db.rel.FK";
+declare const DB_HTTP_PATH: "db.http.path";
+declare const DB_AMOUNT_CURRENCY: "db.amount.currency";
+declare const DB_AMOUNT_CURRENCY_REF: "db.amount.currency.ref";
+declare const DB_UNIT: "db.unit";
+declare const DB_UNIT_REF: "db.unit.ref";
+declare const DB_COLUMN_PRECISION: "db.column.precision";
+declare const WF_ACTION_WITH_DATA: "wf.action.withData";
+declare const META_LABEL: "meta.label";
+declare const META_ID: "meta.id";
+declare const META_DESCRIPTION: "meta.description";
+declare const META_READONLY: "meta.readonly";
+declare const META_REQUIRED: "meta.required";
+declare const META_DEFAULT: "meta.default";
+declare const META_SENSITIVE: "meta.sensitive";
+declare const EXPECT_MAX_LENGTH: "expect.maxLength";
+declare const UI_FORM_FN_PREFIX: "ui.form.fn.";
+declare const UI_FORM_FN_LABEL: "ui.form.fn.label";
+declare const UI_FORM_FN_PLACEHOLDER: "ui.form.fn.placeholder";
+declare const UI_FORM_FN_DESCRIPTION: "ui.form.fn.description";
+declare const UI_FORM_FN_HINT: "ui.form.fn.hint";
+declare const UI_FORM_FN_HIDDEN: "ui.form.fn.hidden";
+declare const UI_FORM_FN_DISABLED: "ui.form.fn.disabled";
+declare const UI_FORM_FN_READONLY: "ui.form.fn.readonly";
+declare const UI_FORM_FN_OPTIONS: "ui.form.fn.options";
+declare const UI_FORM_FN_ATTR: "ui.form.fn.attr";
+declare const UI_FORM_FN_VALUE: "ui.form.fn.value";
+declare const UI_FORM_FN_CLASSES: "ui.form.fn.classes";
+declare const UI_FORM_FN_STYLES: "ui.form.fn.styles";
+declare const UI_FORM_FN_TITLE: "ui.form.fn.title";
+declare const UI_FORM_FN_SUBMIT_TEXT: "ui.form.fn.submit.text";
+declare const UI_FORM_FN_SUBMIT_DISABLED: "ui.form.fn.submit.disabled";
+declare const UI_TABLE_FN_PREFIX: "ui.table.fn.";
+declare const UI_TABLE_FN_ATTR: "ui.table.fn.attr";
+declare const UI_TABLE_FN_CLASSES: "ui.table.fn.classes";
+declare const UI_TABLE_FN_STYLES: "ui.table.fn.styles";
+declare const UI_FORM_VALIDATE: "ui.form.validate";
+//#endregion
+//#region src/value-help/types.d.ts
+/** An option for select/radio fields — either a plain string or a `{ key, label }` pair. */
+type TFormEntryOptions = {
+  key: string;
+  label: string;
+} | string;
+/**
+ * Minimal sync probe output for a value-help–eligible prop.
+ *
+ * Emitted by `extractValueHelp(prop)` at def-construction time. Consumers use
+ * `url` to key the lazy resolver (`resolveValueHelp(url)`) that fetches the
+ * target's own `/meta` endpoint and returns the field-role details.
+ */
+interface ValueHelpInfo {
+  /** HTTP path to the value-help target (from the target's `@db.http.path`). */
+  url: string;
+  /**
+   * Field on the target that this FK references (from `prop.ref.field`, e.g. "id").
+   * This is the value committed to the FK field when the user picks a row.
+   */
+  targetField: string;
+}
+//#endregion
+//#region src/form/types.d.ts
+/** Form action metadata — the action id and display label. */
+interface TFormAction {
+  id: string;
+  label: string;
+}
+/**
+ * A single form field definition — thin pointer to the ATScript prop.
+ *
+ * All metadata (label, disabled, options, etc.) lives in `prop.metadata`
+ * and is resolved on demand via resolve utilities.
+ */
+interface FormFieldDef {
+  /** Dot-separated path relative to the parent data context. `''` = root. */
+  path: string;
+  prop: TAtscriptAnnotatedType;
+  /**
+   * Render-key the renderer dispatches on. For structured kinds (array,
+   * object, tuple, multi-variant union) this stays the kind name so that
+   * `isArrayField`/`isObjectField`/`isUnionField`/`isTupleField` keep
+   * working downstream (validator resetValue, child path provide, AsArray
+   * recursion). Primitives may store an `@ui.form.type`/`@ui.type`
+   * override here directly — for those there is no structural behaviour
+   * to preserve.
+   */
+  type: string;
+  /**
+   * Optional `@ui.form.type` (or `@ui.type`) override for structured
+   * kinds. When set, the renderer looks this up in the `types` map FIRST
+   * and falls back to `type` only when the map has no entry. Letting the
+   * override live in a separate field keeps the structural type guards
+   * (`isArrayField` et al.) on `type` honest while still allowing a
+   * consumer to attach a flat custom widget to e.g. a `string[]`.
+   */
+  customType?: string;
+  phantom: boolean;
+  name: string;
+  /** True when no `ui.fn.*` metadata keys exist. Vue perf flag. */
+  allStatic: boolean;
+}
+/**
+ * Complete form definition — produced by createFormDef().
+ * Form-level metadata (title, submit) resolved on demand via resolveFormProp.
+ */
+interface FormDef {
+  type: TAtscriptAnnotatedType;
+  /** Root field representing the entire form. For interface types this is `type='object'`; for single-type forms it is a leaf field. */
+  rootField: FormFieldDef;
+  fields: FormFieldDef[];
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+}
+/** One branch of a union type — used by union fields and union array items. */
+interface FormUnionVariant {
+  /** Display label — from @meta.label or auto-generated (e.g. "1. String") */
+  label: string;
+  /** The annotated type for this variant */
+  type: TAtscriptAnnotatedType;
+  /** Pre-built FormDef for object variants (undefined for primitives) */
+  def?: FormDef;
+  /** Pre-built field def for primitive variants (undefined for objects) */
+  itemField?: FormFieldDef;
+  /** Design type for primitive variants ('string', 'number', 'boolean') */
+  designType?: string;
+}
+/** Extended field def for array-typed fields. */
+interface FormArrayFieldDef extends FormFieldDef {
+  /** ATScript annotated type of array items (from TAtscriptTypeArray.of) */
+  itemType: TAtscriptAnnotatedType;
+  /** Pre-built template field def for items (path=''). */
+  itemField: FormFieldDef;
+}
+/** Extended field def for object (interface/type) nested fields. */
+interface FormObjectFieldDef extends FormFieldDef {
+  /** Pre-built FormDef for the nested object's fields */
+  objectDef: FormDef;
+}
+/** Extended field def for union fields — standalone union props and union array items. */
+interface FormUnionFieldDef extends FormFieldDef {
+  /** Available union branches. */
+  unionVariants: FormUnionVariant[];
+}
+/** Extended field def for tuple fields — fixed-length with typed positions. */
+interface FormTupleFieldDef extends FormFieldDef {
+  /** Pre-built field defs, one per tuple position. */
+  itemFields: FormFieldDef[];
+}
+/** Type guard: checks if a field def is an array field. */
+declare function isArrayField(field: FormFieldDef): field is FormArrayFieldDef;
+/** Type guard: checks if a field def is an object field. */
+declare function isObjectField(field: FormFieldDef): field is FormObjectFieldDef;
+/** Type guard: checks if a field def is a union field. */
+declare function isUnionField(field: FormFieldDef): field is FormUnionFieldDef;
+/** Type guard: checks if a field def is a tuple field. */
+declare function isTupleField(field: FormFieldDef): field is FormTupleFieldDef;
+//#endregion
+//#region src/form/create-form-def.d.ts
+/**
+ * Converts an ATScript annotated type into a FormDef.
+ *
+ * - **Object types** (`kind === 'object'`): produces an object root with nested fields.
+ * - **Non-object types** (primitive, array, union, etc.): produces a single leaf root field
+ *   with `path: ''`.
+ */
+declare function createFormDef(type: TAtscriptAnnotatedType): FormDef;
+/**
+ * Builds union variant definitions from a union annotated type.
+ * Iterates top-level items directly — one variant per item.
+ */
+declare function buildUnionVariants(typeDef: TAtscriptAnnotatedType): FormUnionVariant[];
+//#endregion
+//#region src/shared/field-resolver.d.ts
+/** Options for field and form property resolution. */
+interface TResolveOptions<T> {
+  /** When true, any non-undefined static value is returned as `true` (for boolean flags like ui.disabled). */
+  staticAsBoolean?: boolean;
+  /** Transform the raw static value before returning. */
+  transform?: (raw: unknown) => T;
+}
+/**
+ * Pluggable resolver interface for field/form metadata.
+ * @atscript/ui provides a static implementation (reads only static annotation values).
+ * ui-fns extends it with dynamic `new Function` compilation for `ui.fn.*` keys.
+ */
+interface FieldResolver {
+  /** Resolve a field-level metadata property. */
+  resolveFieldProp<T>(prop: TAtscriptAnnotatedType, fnKey: string, staticKey: string | undefined, scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+  /** Resolve a form-level metadata property. */
+  resolveFormProp<T>(type: TAtscriptAnnotatedType, fnKey: string, staticKey: string | undefined, scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+  /** Check if a prop has dynamic annotations (ui.fn.*). */
+  hasComputedAnnotations(prop: TAtscriptAnnotatedType): boolean;
+}
+/** Static resolver — ignores fn keys, reads only static metadata. */
+declare class StaticFieldResolver implements FieldResolver {
+  resolveFieldProp<T>(prop: TAtscriptAnnotatedType, _fnKey: string, staticKey: string | undefined, _scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+  resolveFormProp<T>(type: TAtscriptAnnotatedType, _fnKey: string, staticKey: string | undefined, _scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+  hasComputedAnnotations(_prop: TAtscriptAnnotatedType): boolean;
+}
+/** Resolves a static metadata value. Exported for reuse by dynamic resolvers. */
+declare function resolveStatic<T>(metadata: TAtscriptAnnotatedType["metadata"], staticKey: string | undefined, opts?: TResolveOptions<T>): T | undefined;
+/** Default static resolver instance. */
+declare const defaultResolver: StaticFieldResolver;
+/** Replace the active resolver (called by ui-fns to install dynamic resolution). */
+declare function setResolver(resolver: FieldResolver): void;
+/** Get the current active resolver. */
+declare function getResolver(): FieldResolver;
+/** Resolve a field-level metadata property via the active resolver. */
+declare function resolveFieldProp<T>(prop: TAtscriptAnnotatedType, fnKey: string, staticKey: string | undefined, scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+/** Resolve a form-level metadata property via the active resolver. */
+declare function resolveFormProp<T>(type: TAtscriptAnnotatedType, fnKey: string, staticKey: string | undefined, scope: Record<string, unknown>, opts?: TResolveOptions<T>): T | undefined;
+/** Check if a prop has dynamic annotations via the active resolver. */
+declare function hasComputedAnnotations(prop: TAtscriptAnnotatedType): boolean;
+/**
+ * Reads a static metadata value from an ATScript prop.
+ * Typed overload for known AtscriptMetadata keys; falls back to `unknown` for other keys.
+ */
+declare function getFieldMeta<K extends keyof AtscriptMetadata>(prop: TAtscriptAnnotatedType, key: K): AtscriptMetadata[K] | undefined;
+declare function getFieldMeta(prop: TAtscriptAnnotatedType, key: string): unknown;
+/** Ensures a value is an array — returns as-is if already one, wraps in `[x]` otherwise. */
+declare function asArray<T>(x: T | T[]): T[];
+/**
+ * Parses static `ui.attr` metadata into a key-value record.
+ * Exported so ui-fns can reuse this without duplicating the parsing logic.
+ */
+declare function parseStaticAttrs(staticAttrs: unknown): Record<string, unknown> | undefined;
+/** Per-surface attr key pair — defaults to the form-side keys. */
+interface TResolveAttrsKeys {
+  staticKey?: string;
+  fnKey?: string;
+}
+/**
+ * Resolves `<staticKey>` + `<fnKey>` attr metadata on demand.
+ * Defaults read `ui.form.attr` + `ui.form.fn.attr`; pass `{ staticKey, fnKey }` to read
+ * the table-side pair (`ui.table.attr` + `ui.table.fn.attr`) or any other surface.
+ */
+declare function resolveAttrs(prop: TAtscriptAnnotatedType, scope: Record<string, unknown>, keys?: TResolveAttrsKeys): Record<string, unknown> | undefined;
+//#endregion
+//#region src/value-help/resolve.d.ts
+/**
+ * Field-role + capability metadata for a value-help target, lazily resolved
+ * from the target's own `/meta` endpoint.
+ */
+interface ResolvedValueHelp {
+  url: string;
+  primaryKeys: string[];
+  labelField: string;
+  descrField: string | undefined;
+  attrFields: string[];
+  filterableFields: string[];
+  sortableFields: string[];
+  searchable: boolean;
+  targetType: TAtscriptAnnotatedType;
+}
+/**
+ * Lazily fetch and extract value-help metadata for the given URL.
+ *
+ * - Issues exactly one `GET {url}/meta` per URL across the session (shared via meta-cache).
+ * - Concurrent callers with the same URL share the in-flight promise.
+ * - If the underlying fetch rejects, the cache entry is evicted so a later
+ *   retry performs a fresh fetch.
+ */
+declare function resolveValueHelp(url: string): Promise<ResolvedValueHelp>;
+/** Thin alias over `resetMetaCache` — retained so existing test code keeps working. */
+declare function resetValueHelpCache(): void;
+//#endregion
+//#region src/value-help/value-help-client.d.ts
+interface ValueHelpSearchOptions {
+  /** Search term. Empty or undefined returns all records. */
+  text?: string;
+  /** "form" = PK + label + descr; "filter" = all dict fields including attrs. Default: "form". */
+  mode?: "form" | "filter";
+  /** Max results. Default: 20. */
+  limit?: number;
+  /** Override the computed select fields. */
+  select?: string[];
+}
+interface ValueHelpResult {
+  items: Record<string, unknown>[];
+}
+/**
+ * Value-help query client. Wraps a `Client` from `@atscript/db-client`
+ * with FK-specific search logic (regex fallback for non-searchable tables,
+ * $select scoping).
+ *
+ * Consumers resolve the target's metadata once via `resolveValueHelp(url)`
+ * and pass the resulting `ResolvedValueHelp` to `search()`. Label resolution
+ * for cells is deliberately unsupported — cells always display raw ids.
+ */
+declare class ValueHelpClient {
+  private readonly _client;
+  constructor(client: Client);
+  /**
+   * Search the target with value-help semantics.
+   *
+   * - If target is searchable → sends `$search` (server full-text)
+   * - If not searchable → sends `$or` regex across select fields + exact PK match
+   */
+  search(resolved: ResolvedValueHelp, opts?: ValueHelpSearchOptions): Promise<ValueHelpResult>;
+}
+//#endregion
+//#region src/value-help/dict-paths.d.ts
+/**
+ * Paths that make up the "dict view" of a value-help target:
+ * PKs + label + descr + attr fields. Used by filter dialogs to clamp
+ * visible columns to the dictionary subset.
+ */
+declare function valueHelpDictPaths(resolved: ResolvedValueHelp): Set<string>;
+//#endregion
+//#region src/value-help/extract-literals.d.ts
+/**
+ * Extracts options from a union of literal types (e.g. 'a' | 'b' | 'c').
+ * Returns undefined if the type is not a pure union of literals.
+ *
+ * Handles nested unions created by flattenAnnotatedType, which recurses
+ * into union items and produces synthetic unions containing both individual
+ * literals and the original union type as nested items.
+ */
+declare function extractLiteralOptions(prop: TAtscriptAnnotatedType): {
+  key: string;
+  label: string;
+}[] | undefined;
+/** Returns true when the annotated type is a union composed entirely of literal values. */
+declare function isPureLiteralUnion(prop: TAtscriptAnnotatedType): boolean;
+//#endregion
+//#region src/value-help/extract-ref.d.ts
+/**
+ * Synchronous probe. Returns `{ url, targetField }` iff:
+ *   1. the prop carries `@db.rel.FK`,
+ *   2. the prop has a `.ref`,
+ *   3. the ref's target metadata carries `@db.http.path`.
+ */
+declare function extractValueHelp(prop: TAtscriptAnnotatedType): ValueHelpInfo | undefined;
+//#endregion
+//#region src/value-help/resolve-options.d.ts
+/** Extracts the key from an option entry. */
+declare function optKey(opt: TFormEntryOptions): string;
+/** Extracts the display label from an option entry. */
+declare function optLabel(opt: TFormEntryOptions): string;
+/**
+ * Converts raw option annotation value to a normalized array.
+ */
+declare function parseStaticOptions(raw: unknown): TFormEntryOptions[];
+/**
+ * Resolves options from metadata with a fallback chain:
+ * 1. `@ui.form.fn.options` (dynamic, compiled by ui-fns)
+ * 2. `@ui.form.options` (static annotation)
+ * 3. Literal union type extraction (auto-derived from type)
+ * 4. Future: dictionary / value-help lookup
+ */
+declare function resolveOptions(prop: TAtscriptAnnotatedType, scope: Record<string, unknown>): TFormEntryOptions[] | undefined;
+//#endregion
+//#region src/form/path-utils.d.ts
+/**
+ * Gets a nested value by dot-separated path.
+ * Always dereferences `obj.value` first (form data is wrapped in `{ value: domainData }`).
+ * When `path` is empty, returns the root domain data (`obj.value`).
+ */
+declare function getByPath(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Sets a nested value by dot-separated path.
+ * Always dereferences `obj.value` first (form data is wrapped in `{ value: domainData }`).
+ * When `path` is empty, sets the root domain data (`obj.value = value`).
+ * Creates intermediate objects if they do not exist.
+ */
+declare function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
+/** Value resolver function type — created once per form, reused across calls. */
+type TFormValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown;
+declare function createFormValueResolver(data?: Record<string, unknown>, context?: Record<string, unknown>): TFormValueResolver;
+declare function createFormData<T extends TAtscriptAnnotatedType>(type: T, resolver?: TFormValueResolver): {
+  value: TAtscriptDataType<T>;
+};
+declare function detectUnionVariant(value: unknown, variants: FormUnionVariant[]): number;
+//#endregion
+//#region src/form/validate.d.ts
+/** Per-call options for the form validator function. */
+interface TFormValidatorCallOptions {
+  data: Record<string, unknown>;
+  context?: Record<string, unknown>;
+}
+/** Replace the default validator plugins applied to every form/field validator. */
+declare function setDefaultValidatorPlugins(plugins: TValidatorPlugin[]): void;
+/** Get the currently registered default validator plugins. */
+declare function getDefaultValidatorPlugins(): TValidatorPlugin[];
+/**
+ * Returns a reusable validator function for a whole FormDef.
+ *
+ * Validator is created once and reused on every call.
+ * ATScript's @expect.* validation runs automatically.
+ * For custom `ui.fn.*` validators, install ui-fns and pass its plugin via `opts.plugins`.
+ */
+declare function getFormValidator(def: FormDef, opts?: Partial<TValidatorOptions>): (callOpts: TFormValidatorCallOptions) => Record<string, string>;
+/** Options for createFieldValidator. */
+interface TFieldValidatorOptions {
+  /** Only report errors at the root path (for structure/array container validation). */
+  rootOnly?: boolean;
+}
+/**
+ * Creates a cached validator function for a single ATScript prop.
+ *
+ * The `Validator` instance is created lazily on first call and reused.
+ * Returns `true` when valid, or the first error message string when invalid.
+ */
+declare function createFieldValidator(prop: TAtscriptAnnotatedType, opts?: TFieldValidatorOptions): (value: unknown, externalCtx?: {
+  data: unknown;
+  context: unknown;
+}) => true | string;
+//#endregion
+//#region src/form/error-utils.d.ts
+/**
+ * Framework-agnostic helpers for working with form-error maps keyed by
+ * dotted path. Used by AsForm to drive error badges and auto-open
+ * collapsed sections; safe to share with React (or any other) bindings.
+ *
+ * Convention:
+ *   - Keys are dotted paths (`a.b.c`); empty string and `__form` denote
+ *     the form-level error.
+ *   - Values may be `string | undefined`; falsy entries are dropped on
+ *     merge.
+ */
+/**
+ * Merge any number of partial error maps into a single dense
+ * `Record<path, message>`. Falsy values are skipped — later sources do
+ * NOT overwrite earlier ones with an empty value.
+ */
+declare function mergeErrorMaps(...maps: Array<Record<string, string | undefined> | undefined>): Record<string, string>;
+/**
+ * Yield every ancestor prefix of a dotted path, longest-first
+ * (`a.b.c` → `a.b.c`, `a.b`, `a`). Returns the path itself first so
+ * callers can include it in the iteration without a special case.
+ *
+ * Empty paths and the form-level key (`__form`) yield nothing.
+ */
+declare function iteratePathAncestors(path: string): Generator<string>;
+/**
+ * Build an indexed `Map<absolutePath, descendantErrorCount>` so each
+ * struct in the tree can render an error-count badge in O(1).
+ *
+ * For every error path, the count is incremented on the path itself
+ * AND every dotted-path ancestor — so a struct at `a.b` reports the
+ * total of all errors at `a.b` or below.
+ */
+declare function buildDescendantErrorCounts(errors: Record<string, string | undefined>): Map<string, number>;
+//#endregion
+//#region src/form/grid.d.ts
+/** Grid layout parsing for `@ui.form.grid.colSpan` / `@ui.form.grid.rowSpan`. */
+declare const DEFAULT_COL_SPAN = 12;
+declare const DEFAULT_ROW_SPAN = 1;
+/** Accepts "1"-"12" and the aliases "full" (12), "half" (6), "third" (4). */
+declare function parseColSpan(raw: string | undefined): number | undefined;
+/** Accepts numeric strings "1"+; rejects "0", negatives, decimals, aliases. */
+declare function parseRowSpan(raw: string | undefined): number | undefined;
+interface GridSpec {
+  col: {
+    desktop: number;
+    narrow: number;
+  };
+  row: {
+    desktop: number;
+    narrow: number;
+  };
+}
+/**
+ * Shape returned by `getFieldMeta(prop, UI_FORM_GRID_COL_SPAN | …ROW_SPAN)` —
+ * atscript codegen produces a struct from named multi-arg annotation specs.
+ */
+interface GridSpanArgs {
+  desktop: string;
+  narrow?: string;
+}
+/**
+ * Resolve a field's grid footprint. Narrow defaults to full-width / single-row
+ * regardless of the desktop value, so authors can opt into a narrow override
+ * via the second annotation arg without it inheriting an unintended desktop span.
+ */
+declare function resolveGridSpec(colSpan: GridSpanArgs | undefined, rowSpan: GridSpanArgs | undefined): GridSpec;
+/**
+ * Build the UnoCSS class string for a field's grid footprint.
+ *
+ * - Skips desktop classes that match the default (`as-grid-item` already
+ *   covers `col-span-full row-span-1`).
+ * - Skips narrow overrides that match the desktop value (no override needed).
+ * - The narrow variant uses the custom `as-narrow:` prefix, which the
+ *   atscript-ui UnoCSS preset rewrites to `@container as-grid (max-width:
+ *   480px) { ... }`. The parent grid is registered as
+ *   `container-name: as-grid` via the `as-form-grid` shortcut, so the
+ *   rule resolves against the actual grid's inline size — not the viewport.
+ *
+ * Returned string is space-separated, ready to drop into a Vue class binding.
+ */
+declare function buildGridClasses(spec: GridSpec): string;
+//#endregion
+//#region src/form/labels.d.ts
+/** Singular label for an array field (used by AsArray for "Add <singular>"). */
+declare function resolveSingularLabel(meta: TAtscriptAnnotatedType | undefined): string;
+//#endregion
+//#region src/form/measurement.d.ts
+/**
+ * Resolved measurement annotations — currency / unit-of-measure / numeric
+ * precision. Read once at form/table-def construction time and surfaced as
+ * already-resolved values so downstream renderers (cells, default form
+ * components, custom inputs) never re-read annotation metadata.
+ */
+interface MeasurementInfo {
+  /** Literal currency code from `@db.amount.currency 'EUR'`. */
+  currencyCode?: string;
+  /** Sibling-field path from `@db.amount.currency.ref 'fieldName'`. */
+  currencyRefField?: string;
+  /** Literal unit-of-measure from `@db.unit 'kg'`. */
+  unitCode?: string;
+  /** Sibling-field path from `@db.unit.ref 'fieldName'`. */
+  unitRefField?: string;
+  /** Decimal scale (fraction digits) — second arg of `@db.column.precision precision, scale`. */
+  precisionScale?: number;
+}
+/**
+ * Read measurement annotations off a single field prop. Returns `undefined`
+ * for any annotation that's absent — callers can spread the result into a
+ * larger record.
+ */
+declare function extractMeasurement(prop: TAtscriptAnnotatedType): MeasurementInfo;
+//#endregion
+//#region src/form/decimal-format.d.ts
+/**
+ * Framework-agnostic decimal formatting + parsing helpers shared by
+ * `@atscript/vue-table` (read-only cell display) and `@atscript/vue-form`
+ * (editable amount/measure inputs). Symmetric output is the contract —
+ * a value rendered in a cell must read identically when displayed in
+ * the form composables, modulo currency / unit adornment.
+ *
+ * The functions here are intentionally pure (no `Number()` round-trips
+ * in the storage value path) — decimal-as-string correctness depends on
+ * not bouncing through floats.
+ */
+interface CurrencyDisplay {
+  /** Narrow symbol: "$" / "€" / "US$" depending on locale. Falls back to code on Intl failure. */
+  symbol: string;
+  /** Whether the symbol typically sits left or right of the amount. */
+  position: "prefix" | "suffix";
+}
+interface DecimalParts {
+  sign: "" | "-";
+  /** Integer part, no thousands separator, no leading zeros beyond "0". */
+  integer: string;
+  /** Decimal part as captured, no separator. Empty string if absent. */
+  decimal: string;
+}
+interface FormatDecimalOptions {
+  value: string | number | null | undefined;
+  /** Scale used for display (typically the effective scale, not DB scale). Trailing zeros pad. */
+  scale?: number;
+  locale?: string;
+  /** When set → Intl.NumberFormat with style:currency. Symbol/grouping handled by Intl. */
+  currency?: string;
+  /** When set (and no currency) → "<formatted> <unit>". */
+  unit?: string;
+  /** Whether to group thousands. Defaults to true. */
+  useGrouping?: boolean;
+}
+/** "." in en-US, "," in fr-FR. Returns "." when locale is undefined. */
+declare function getDecimalSeparator(locale?: string): string;
+/**
+ * "," in en-US, NNBSP (U+202F) in fr-FR. Returns "" when no grouping is
+ * applied (or when Intl rejects the locale).
+ */
+declare function getThousandsSeparator(locale?: string): string;
+declare function getCurrencyDisplayParts(code: string, locale?: string): CurrencyDisplay;
+/**
+ * Currency's natural decimal count via Intl. JPY=0, USD/EUR=2, BHD/KWD=3.
+ * Returns `undefined` for codes Intl doesn't know — caller falls back to
+ * `dbPrecisionScale`.
+ */
+declare function getCurrencyDecimals(code: string, locale?: string): number | undefined;
+/**
+ * Parse a user-typed decimal string. Returns the canonical decimal
+ * (no thousands separator, "." as decimal separator) or `null` if invalid.
+ * Accepts both "." and "," as the decimal separator (locale-aware).
+ * Strips the locale thousands separator. Preserves sign. Does NOT
+ * enforce scale.
+ */
+declare function parseDecimalInput(raw: string, locale?: string): string | null;
+/**
+ * Enforce a fractional-digit count by truncating or padding. String-only —
+ * no float arithmetic. Default behaviour truncates (no rounding) so digits
+ * the user typed can't silently shift. Pass `roundHalfUp: true` to round.
+ *
+ *   enforceScale("12.345", 2) → "12.34"  (truncate)
+ *   enforceScale("12.3", 4)   → "12.3000" (pad)
+ *   enforceScale("12", 0)     → "12"
+ *   enforceScale("12.99", 0)  → "12" (no rounding)
+ */
+declare function enforceScale(s: string, scale: number | undefined, opts?: {
+  roundHalfUp?: boolean;
+}): string;
+declare function splitDecimalString(s: string): DecimalParts;
+declare function joinDecimalString(parts: DecimalParts): string;
+declare function formatDecimalForDisplay(opts: FormatDecimalOptions): string;
+/**
+ * Insert the locale's thousands separator into a plain integer string.
+ * Pure string-based — no float math, handles arbitrary length.
+ */
+declare function groupInteger(integer: string, locale?: string): string;
+//#endregion
+//#region src/table/types.d.ts
+/** Search index metadata from the server. */
+interface SearchIndexInfo {
+  name: string;
+  description?: string;
+  type?: "text" | "vector";
+}
+/** Relation summary in meta response. */
+interface RelationInfo {
+  name: string;
+  direction: "to" | "from" | "via";
+  isArray: boolean;
+}
+/** Per-field capability flags. */
+interface FieldMeta {
+  sortable: boolean;
+  filterable: boolean;
+}
+/** Meta response from moost-db `/meta` endpoint. */
+interface MetaResponse {
+  searchable: boolean;
+  vectorSearchable: boolean;
+  searchIndexes: SearchIndexInfo[];
+  primaryKeys: string[];
+  /**
+   * Preferred row identifier (UI/wire addressing). From
+   * `@db.table.preferredId.uniqueIndex` — defaults to `primaryKeys` when the
+   * server omits it (older servers / stub fixtures). Drives identifier object
+   * construction for action POSTs and `'navigate'` URL `$1` substitution.
+   */
+  preferredId: string[];
+  crud: TCrudPermissions$1;
+  actions: TDbActionInfo$1[];
+  relations: RelationInfo[];
+  fields: Record<string, FieldMeta>;
+  type: TSerializedAnnotatedType;
+}
+/**
+ * Server-declared actions grouped by `level`. Built by `createTableDef` from
+ * `meta.actions[]` — sorted within each group by `(order ?? 0)` then
+ * declaration order. `default.{table,row,rows}` is the first `default: true`
+ * entry per level (or `undefined`). The synthesised `__remove` UI action is
+ * never selected as a default.
+ */
+interface TableActionsModel {
+  table: TDbActionInfo$1[];
+  row: TDbActionInfo$1[];
+  rows: TDbActionInfo$1[];
+  default: {
+    table?: TDbActionInfo$1;
+    row?: TDbActionInfo$1;
+    rows?: TDbActionInfo$1;
+  };
+}
+/** Complete table definition — produced by createTableDef(). */
+interface TableDef {
+  type: TAtscriptAnnotatedType;
+  columns: ColumnDef[];
+  /**
+   * Flattened type tree (path → annotated prop). Empty Map for non-object roots.
+   * Excludes phantom types. Consumers (e.g. cell-resolver) read this instead
+   * of re-walking the type.
+   */
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  primaryKeys: string[];
+  /** Preferred row identifier — see `MetaResponse.preferredId`. */
+  preferredId: string[];
+  /** Per-op CRUD permissions advertised in `/meta`. Key absent → denied. */
+  crud: TCrudPermissions$1;
+  canRemove: boolean;
+  /** Server-declared actions, grouped by level with defaults pre-resolved. */
+  actions: TableActionsModel;
+  searchable: boolean;
+  vectorSearchable: boolean;
+  searchIndexes: SearchIndexInfo[];
+  relations: RelationInfo[];
+}
+/** A single column definition — built from field metadata + annotations. */
+interface ColumnDef {
+  /** Field path in dot-notation (e.g. 'address.city'). */
+  path: string;
+  /** Display label — from @meta.label or humanized path. */
+  label: string;
+  /** Display type — from @ui.table.type, then @ui.type, then inferred from designType. */
+  type: string;
+  /** Named component override from @ui.table.component — looked up in the table components map. */
+  component?: string;
+  /** Whether this column supports sorting. */
+  sortable: boolean;
+  /** Whether this column supports filtering. */
+  filterable: boolean;
+  /**
+   * Whether the column accepts `null` values (atscript prop is `optional`).
+   * Drives operator-picker availability — `null` / `notNull` are dropped
+   * for non-nullable columns since they can never match.
+   */
+  nullable: boolean;
+  /** Whether this column is visible by default. */
+  visible: boolean;
+  /** Default column width from @ui.table.width. */
+  width?: string;
+  /** Maximum length constraint from @expect.maxLen — used to derive default column width. */
+  maxLen?: number;
+  /** Initial column ordering from @ui.table.order (lower = first). */
+  order: number;
+  /** Enumerated options for union literal types (e.g. 'a' | 'b' | 'c'). */
+  options?: {
+    key: string;
+    label: string;
+  }[];
+  /** Value-help info for FK columns (from extractValueHelp). */
+  valueHelpInfo?: ValueHelpInfo;
+  /** Literal currency code from `@db.amount.currency 'EUR'`. */
+  currencyCode?: string;
+  /** Sibling field path from `@db.amount.currency.ref 'fieldName'`. */
+  currencyRefField?: string;
+  /** Literal unit-of-measure from `@db.unit 'kg'`. */
+  unitCode?: string;
+  /** Sibling field path from `@db.unit.ref 'fieldName'`. */
+  unitRefField?: string;
+  /** Decimal scale (fraction digits) — second arg of `@db.column.precision precision, scale`. */
+  precisionScale?: number;
+  /**
+   * Synthesised, locked-chrome column. When `true`: header-cell column-menu
+   * skipped, resize handle skipped, drag-reorder excluded, NOT in the
+   * `columnNames` v-model. Used for the row-actions pseudo-column
+   * (`path: '__actions'`).
+   */
+  fixed?: boolean;
+}
+/** A single sort directive. */
+interface SortControl {
+  field: string;
+  direction: "asc" | "desc";
+}
+/** Pagination state. */
+interface PaginationControl {
+  page: number;
+  itemsPerPage: number;
+}
+/** Reactive query state for a table — mirrors @uniqu/core controls. */
+interface TableQueryState {
+  sort?: SortControl[];
+  pagination?: PaginationControl;
+  search?: string;
+  filters?: Record<string, unknown>;
+}
+//#endregion
+//#region src/table/create-table-def.d.ts
+/**
+ * Builds a TableDef from a moost-db MetaResponse.
+ *
+ * 1. Deserializes `meta.type` into a live TAtscriptAnnotatedType
+ * 2. Flattens to discover all field paths
+ * 3. Builds ColumnDef per field using annotations + meta.fields capabilities
+ * 4. Sorts by @ui.table.order
+ */
+declare function createTableDef(meta: MetaResponse, preDeserializedType?: TAtscriptAnnotatedType): TableDef;
+//#endregion
+//#region src/client-factory.d.ts
+/**
+ * Factory that creates a `Client` for a given URL.
+ *
+ * Single contract shared by every atscript-ui primitive that needs to talk
+ * to an atscript-db-compatible endpoint: table composables, FK value-help,
+ * and any future consumer. Produces a `Client` configured with whatever
+ * transport / auth wiring the host application wants.
+ */
+type ClientFactory = (url: string) => Client;
+/**
+ * Override the app-wide default factory. Call once at startup (e.g. in
+ * `entry-client.ts`) to wire shared fetch, credentials, error handling, etc.
+ * Every table, value-help picker, and other client consumer will pick it up.
+ */
+declare function setDefaultClientFactory(factory: ClientFactory): void;
+/** Current app-wide default factory. Falls back to `new Client(url)`. */
+declare function getDefaultClientFactory(): ClientFactory;
+/** Reset the default factory to the built-in one (primarily for tests). */
+declare function resetDefaultClientFactory(): void;
+//#endregion
+//#region src/shared/meta-cache.d.ts
+/**
+ * Shared per-URL cache. A single entry holds the `Client` instance, the raw
+ * `/meta` promise, the deserialized type, and lazily-populated derived shapes
+ * (`ResolvedValueHelp` for value-help, `TableDef` for tables). Both
+ * `resolveValueHelp` and `useTable` route through it so a given URL triggers
+ * at most one network round-trip and one `deserializeAnnotatedType`.
+ */
+interface MetaCacheEntry {
+  client: Client;
+  meta: Promise<MetaResponse>;
+  type: Promise<TAtscriptAnnotatedType>;
+  resolved?: Promise<ResolvedValueHelp>;
+  tableDef?: Promise<TableDef>;
+}
+/**
+ * Get or create the cache entry for `url`. First caller's `factory` seeds the
+ * `Client`; subsequent callers reuse it. On `meta` rejection, the entry is
+ * evicted so the next call retries.
+ */
+declare function getMetaEntry(url: string, factory?: ClientFactory): MetaCacheEntry;
+declare function resetMetaCache(): void;
+//#endregion
+//#region src/shared/str.d.ts
+/** Safely convert an unknown value to a string without triggering no-base-to-string lint errors. */
+declare function str(value: unknown): string;
+//#endregion
+//#region src/table/column-resolver.d.ts
+/** Get visible columns only, already sorted by order. */
+declare function getVisibleColumns(def: TableDef): ColumnDef[];
+/** Get sortable columns. */
+declare function getSortableColumns(def: TableDef): ColumnDef[];
+/** Get filterable columns. */
+declare function getFilterableColumns(def: TableDef): ColumnDef[];
+/** Find a column by path. */
+declare function getColumn(def: TableDef, path: string): ColumnDef | undefined;
+//#endregion
+export { type ClientFactory, type ColumnDef, type CurrencyDisplay, DB_AMOUNT_CURRENCY, DB_AMOUNT_CURRENCY_REF, DB_COLUMN_PRECISION, DB_HTTP_PATH, DB_REL_FK, DB_UNIT, DB_UNIT_REF, DEFAULT_COL_SPAN, DEFAULT_ROW_SPAN, type DecimalParts, EXPECT_MAX_LENGTH, type FieldMeta, type FieldResolver, type FormArrayFieldDef, type FormDef, type FormFieldDef, type FormObjectFieldDef, type FormTupleFieldDef, type FormUnionFieldDef, type FormUnionVariant, type FormatDecimalOptions, type GridSpanArgs, type GridSpec, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, type MeasurementInfo, type MetaCacheEntry, type MetaResponse, type PaginationControl, type RelationInfo, type ResolvedValueHelp, type SearchIndexInfo, type SortControl, StaticFieldResolver, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TFieldValidatorOptions, type TFormAction, type TFormEntryOptions, type TFormValidatorCallOptions, type TFormValueResolver, type TResolveOptions, type TableActionsModel, type TableDef, type TableQueryState, UI_DICT_ATTR, UI_DICT_DESCR, UI_DICT_FILTERABLE, UI_DICT_LABEL, UI_DICT_SEARCHABLE, UI_DICT_SORTABLE, UI_FORM_ACTION, UI_FORM_ATTR, UI_FORM_AUTOCOMPLETE, UI_FORM_CLASSES, UI_FORM_COMPONENT, UI_FORM_DISABLED, UI_FORM_FN_ATTR, UI_FORM_FN_CLASSES, UI_FORM_FN_DESCRIPTION, UI_FORM_FN_DISABLED, UI_FORM_FN_HIDDEN, UI_FORM_FN_HINT, UI_FORM_FN_LABEL, UI_FORM_FN_OPTIONS, UI_FORM_FN_PLACEHOLDER, UI_FORM_FN_PREFIX, UI_FORM_FN_READONLY, UI_FORM_FN_STYLES, UI_FORM_FN_SUBMIT_DISABLED, UI_FORM_FN_SUBMIT_TEXT, UI_FORM_FN_TITLE, UI_FORM_FN_VALUE, UI_FORM_GRID_COL_SPAN, UI_FORM_GRID_ROW_SPAN, UI_FORM_HIDDEN, UI_FORM_HINT, UI_FORM_LABEL_SINGULAR, UI_FORM_OPTIONS, UI_FORM_ORDER, UI_FORM_PLACEHOLDER, UI_FORM_PREFIX, UI_FORM_PREFIX_ICON, UI_FORM_PREFIX_REF, UI_FORM_STYLES, UI_FORM_SUBMIT_TEXT, UI_FORM_SUFFIX, UI_FORM_SUFFIX_ICON, UI_FORM_SUFFIX_REF, UI_FORM_TYPE, UI_FORM_VALIDATE, UI_TABLE_ATTR, UI_TABLE_CLASSES, UI_TABLE_COMPONENT, UI_TABLE_FN_ATTR, UI_TABLE_FN_CLASSES, UI_TABLE_FN_PREFIX, UI_TABLE_FN_STYLES, UI_TABLE_HIDDEN, UI_TABLE_ORDER, UI_TABLE_STYLES, UI_TABLE_TYPE, UI_TABLE_WIDTH, UI_TYPE, ValueHelpClient, type ValueHelpInfo, type ValueHelpResult, type ValueHelpSearchOptions, WF_ACTION_WITH_DATA, asArray, buildDescendantErrorCounts, buildGridClasses, buildUnionVariants, createFieldValidator, createFormData, createFormDef, createFormValueResolver, createTableDef, defaultResolver, detectUnionVariant, enforceScale, extractLiteralOptions, extractMeasurement, extractValueHelp, formatDecimalForDisplay, getByPath, getColumn, getCurrencyDecimals, getCurrencyDisplayParts, getDecimalSeparator, getDefaultClientFactory, getDefaultValidatorPlugins, getFieldMeta, getFilterableColumns, getFormValidator, getMetaEntry, getResolver, getSortableColumns, getThousandsSeparator, getVisibleColumns, groupInteger, hasComputedAnnotations, isArrayField, isObjectField, isPureLiteralUnion, isTupleField, isUnionField, iteratePathAncestors, joinDecimalString, mergeErrorMaps, optKey, optLabel, parseColSpan, parseDecimalInput, parseRowSpan, parseStaticAttrs, parseStaticOptions, resetDefaultClientFactory, resetMetaCache, resetValueHelpCache, resolveAttrs, resolveFieldProp, resolveFormProp, resolveGridSpec, resolveOptions, resolveSingularLabel, resolveStatic, resolveValueHelp, setByPath, setDefaultClientFactory, setDefaultValidatorPlugins, setResolver, splitDecimalString, str, valueHelpDictPaths };