@atscript/ui 0.1.58

package/dist/index.mjs

@@ -0,0 +1,1498 @@
+import { Validator, createDataFromAnnotatedType, deserializeAnnotatedType, detectDiscriminator, flattenAnnotatedType } from "@atscript/typescript/utils";
+import { Client } from "@atscript/db-client";
+//#region src/shared/annotation-keys.ts
+const UI_TYPE = "ui.type";
+const UI_FORM_PLACEHOLDER = "ui.form.placeholder";
+const UI_FORM_HINT = "ui.form.hint";
+const UI_FORM_CLASSES = "ui.form.classes";
+const UI_FORM_STYLES = "ui.form.styles";
+const UI_FORM_AUTOCOMPLETE = "ui.form.autocomplete";
+const UI_FORM_DISABLED = "ui.form.disabled";
+const UI_FORM_OPTIONS = "ui.form.options";
+const UI_FORM_ORDER = "ui.form.order";
+const UI_FORM_TYPE = "ui.form.type";
+const UI_FORM_COMPONENT = "ui.form.component";
+const UI_FORM_HIDDEN = "ui.form.hidden";
+const UI_FORM_ATTR = "ui.form.attr";
+const UI_FORM_GRID_COL_SPAN = "ui.form.grid.colSpan";
+const UI_FORM_GRID_ROW_SPAN = "ui.form.grid.rowSpan";
+const UI_FORM_SUBMIT_TEXT = "ui.form.submit.text";
+const UI_FORM_LABEL_SINGULAR = "ui.form.label.singular";
+const UI_FORM_ACTION = "ui.form.action";
+const UI_FORM_PREFIX = "ui.form.prefix";
+const UI_FORM_PREFIX_REF = "ui.form.prefix.ref";
+const UI_FORM_PREFIX_ICON = "ui.form.prefix.icon";
+const UI_FORM_SUFFIX = "ui.form.suffix";
+const UI_FORM_SUFFIX_REF = "ui.form.suffix.ref";
+const UI_FORM_SUFFIX_ICON = "ui.form.suffix.icon";
+const UI_TABLE_WIDTH = "ui.table.width";
+const UI_TABLE_COMPONENT = "ui.table.component";
+const UI_TABLE_HIDDEN = "ui.table.hidden";
+const UI_TABLE_ATTR = "ui.table.attr";
+const UI_TABLE_CLASSES = "ui.table.classes";
+const UI_TABLE_STYLES = "ui.table.styles";
+const UI_TABLE_TYPE = "ui.table.type";
+const UI_TABLE_ORDER = "ui.table.order";
+const UI_DICT_LABEL = "ui.dict.label";
+const UI_DICT_DESCR = "ui.dict.descr";
+const UI_DICT_ATTR = "ui.dict.attr";
+const UI_DICT_FILTERABLE = "ui.dict.filterable";
+const UI_DICT_SORTABLE = "ui.dict.sortable";
+const UI_DICT_SEARCHABLE = "ui.dict.searchable";
+const DB_REL_FK = "db.rel.FK";
+const DB_HTTP_PATH = "db.http.path";
+const DB_AMOUNT_CURRENCY = "db.amount.currency";
+const DB_AMOUNT_CURRENCY_REF = "db.amount.currency.ref";
+const DB_UNIT = "db.unit";
+const DB_UNIT_REF = "db.unit.ref";
+const DB_COLUMN_PRECISION = "db.column.precision";
+const WF_ACTION_WITH_DATA = "wf.action.withData";
+const META_LABEL = "meta.label";
+const META_ID = "meta.id";
+const META_DESCRIPTION = "meta.description";
+const META_READONLY = "meta.readonly";
+const META_REQUIRED = "meta.required";
+const META_DEFAULT = "meta.default";
+const META_SENSITIVE = "meta.sensitive";
+const EXPECT_MAX_LENGTH = "expect.maxLength";
+const UI_FORM_FN_PREFIX = "ui.form.fn.";
+const UI_FORM_FN_LABEL = "ui.form.fn.label";
+const UI_FORM_FN_PLACEHOLDER = "ui.form.fn.placeholder";
+const UI_FORM_FN_DESCRIPTION = "ui.form.fn.description";
+const UI_FORM_FN_HINT = "ui.form.fn.hint";
+const UI_FORM_FN_HIDDEN = "ui.form.fn.hidden";
+const UI_FORM_FN_DISABLED = "ui.form.fn.disabled";
+const UI_FORM_FN_READONLY = "ui.form.fn.readonly";
+const UI_FORM_FN_OPTIONS = "ui.form.fn.options";
+const UI_FORM_FN_ATTR = "ui.form.fn.attr";
+const UI_FORM_FN_VALUE = "ui.form.fn.value";
+const UI_FORM_FN_CLASSES = "ui.form.fn.classes";
+const UI_FORM_FN_STYLES = "ui.form.fn.styles";
+const UI_FORM_FN_TITLE = "ui.form.fn.title";
+const UI_FORM_FN_SUBMIT_TEXT = "ui.form.fn.submit.text";
+const UI_FORM_FN_SUBMIT_DISABLED = "ui.form.fn.submit.disabled";
+const UI_TABLE_FN_PREFIX = "ui.table.fn.";
+const UI_TABLE_FN_ATTR = "ui.table.fn.attr";
+const UI_TABLE_FN_CLASSES = "ui.table.fn.classes";
+const UI_TABLE_FN_STYLES = "ui.table.fn.styles";
+const UI_FORM_VALIDATE = "ui.form.validate";
+//#endregion
+//#region src/form/types.ts
+/** Type guard: checks if a field def is an array field. */
+function isArrayField(field) {
+	return field.type === "array";
+}
+/** Type guard: checks if a field def is an object field. */
+function isObjectField(field) {
+	return field.type === "object";
+}
+/** Type guard: checks if a field def is a union field. */
+function isUnionField(field) {
+	return field.type === "union";
+}
+/** Type guard: checks if a field def is a tuple field. */
+function isTupleField(field) {
+	return field.type === "tuple";
+}
+//#endregion
+//#region src/shared/field-resolver.ts
+/** Static resolver — ignores fn keys, reads only static metadata. */
+var StaticFieldResolver = class {
+	resolveFieldProp(prop, _fnKey, staticKey, _scope, opts) {
+		return resolveStatic(prop.metadata, staticKey, opts);
+	}
+	resolveFormProp(type, _fnKey, staticKey, _scope, opts) {
+		return resolveStatic(type.metadata, staticKey, opts);
+	}
+	hasComputedAnnotations(_prop) {
+		return false;
+	}
+};
+/** Resolves a static metadata value. Exported for reuse by dynamic resolvers. */
+function resolveStatic(metadata, staticKey, opts) {
+	if (staticKey === void 0) return void 0;
+	const staticVal = metadata.get(staticKey);
+	if (staticVal !== void 0) {
+		if (opts?.staticAsBoolean) return true;
+		if (opts?.transform) return opts.transform(staticVal);
+		return staticVal;
+	}
+}
+/** Default static resolver instance. */
+const defaultResolver = new StaticFieldResolver();
+let activeResolver = defaultResolver;
+/** Replace the active resolver (called by ui-fns to install dynamic resolution). */
+function setResolver(resolver) {
+	activeResolver = resolver;
+}
+/** Get the current active resolver. */
+function getResolver() {
+	return activeResolver;
+}
+/** Resolve a field-level metadata property via the active resolver. */
+function resolveFieldProp(prop, fnKey, staticKey, scope, opts) {
+	return activeResolver.resolveFieldProp(prop, fnKey, staticKey, scope, opts);
+}
+/** Resolve a form-level metadata property via the active resolver. */
+function resolveFormProp(type, fnKey, staticKey, scope, opts) {
+	return activeResolver.resolveFormProp(type, fnKey, staticKey, scope, opts);
+}
+/** Check if a prop has dynamic annotations via the active resolver. */
+function hasComputedAnnotations(prop) {
+	return activeResolver.hasComputedAnnotations(prop);
+}
+function getFieldMeta(prop, key) {
+	return prop.metadata.get(key);
+}
+/** Ensures a value is an array — returns as-is if already one, wraps in `[x]` otherwise. */
+function asArray(x) {
+	return Array.isArray(x) ? x : [x];
+}
+/**
+* Parses static `ui.attr` metadata into a key-value record.
+* Exported so ui-fns can reuse this without duplicating the parsing logic.
+*/
+function parseStaticAttrs(staticAttrs) {
+	if (!staticAttrs) return void 0;
+	const result = {};
+	let hasAttrs = false;
+	for (const item of asArray(staticAttrs)) if (typeof item === "object" && item !== null && "name" in item && "value" in item) {
+		const { name, value } = item;
+		result[name] = value;
+		hasAttrs = true;
+	}
+	return hasAttrs ? result : void 0;
+}
+/**
+* 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.
+*/
+function resolveAttrs(prop, scope, keys = {}) {
+	const staticKey = keys.staticKey ?? "ui.form.attr";
+	const fnKey = keys.fnKey ?? "ui.form.fn.attr";
+	const staticAttrs = getFieldMeta(prop, staticKey);
+	const fnAttrs = getFieldMeta(prop, fnKey);
+	if (!staticAttrs && !fnAttrs) return void 0;
+	const result = {};
+	let hasAttrs = false;
+	const parsed = parseStaticAttrs(staticAttrs);
+	if (parsed) {
+		Object.assign(result, parsed);
+		hasAttrs = true;
+	}
+	if (fnAttrs) {
+		const resolved = resolveFieldProp(prop, fnKey, void 0, scope);
+		if (resolved) {
+			Object.assign(result, resolved);
+			hasAttrs = true;
+		}
+	}
+	return hasAttrs ? result : void 0;
+}
+//#endregion
+//#region src/value-help/extract-literals.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.
+*/
+function extractLiteralOptions(prop) {
+	if (prop.type.kind !== "union") return void 0;
+	const result = collectLiterals(prop.type.items, /* @__PURE__ */ new Set());
+	return result && result.length > 0 ? result : void 0;
+}
+/** Returns true when the annotated type is a union composed entirely of literal values. */
+function isPureLiteralUnion(prop) {
+	if (prop.type.kind !== "union") return false;
+	return checkAllLiterals(prop.type.items);
+}
+/** Walks union items returning true only if every leaf is a literal value. */
+function checkAllLiterals(items) {
+	for (const item of items) {
+		if (item.type.kind === "" && item.type.value !== void 0) continue;
+		if (item.type.kind === "union") {
+			if (!checkAllLiterals(item.type.items)) return false;
+			continue;
+		}
+		return false;
+	}
+	return items.length > 0;
+}
+/**
+* Recursively collects literal values from union items.
+* Returns null if any non-literal, non-union item is found (invalid union).
+* Returns empty array when all items are valid but already seen (deduped).
+*/
+function collectLiterals(items, seen) {
+	const result = [];
+	for (const item of items) if (item.type.kind === "" && item.type.value !== void 0) {
+		const val = String(item.type.value);
+		if (!seen.has(val)) {
+			seen.add(val);
+			result.push({
+				key: val,
+				label: val
+			});
+		}
+	} else if (item.type.kind === "union") {
+		const nested = collectLiterals(item.type.items, seen);
+		if (nested === null) return null;
+		result.push(...nested);
+	} else return null;
+	return result;
+}
+//#endregion
+//#region src/value-help/extract-ref.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`.
+*/
+function extractValueHelp(prop) {
+	if (!prop.metadata.has("db.rel.FK")) return void 0;
+	if (!prop.ref) return void 0;
+	const target = prop.ref.type();
+	if (!target) return void 0;
+	const url = target.metadata.get(DB_HTTP_PATH);
+	if (!url) return void 0;
+	return {
+		url,
+		targetField: prop.ref.field
+	};
+}
+//#endregion
+//#region src/form/create-form-def.ts
+/** Known atscript primitive extension tags that map directly to field types. */
+const UI_TAGS = new Set([
+	"action",
+	"paragraph",
+	"select",
+	"radio",
+	"checkbox"
+]);
+/**
+* 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: ''`.
+*/
+function createFormDef(type) {
+	if (type.type.kind !== "object") {
+		const rootField = createFieldDef("", type);
+		return {
+			type,
+			rootField,
+			fields: [rootField],
+			flatMap: /* @__PURE__ */ new Map()
+		};
+	}
+	const objectType = type;
+	const flatMap = flattenAnnotatedType(objectType, { excludePhantomTypes: false });
+	const fields = [];
+	const structuredPrefixes = /* @__PURE__ */ new Set();
+	for (const [path, prop] of flatMap.entries()) {
+		if (path === "") continue;
+		if (isChildOfStructured(path, structuredPrefixes)) continue;
+		const originalProp = resolveOriginalProp(objectType, path) ?? prop;
+		const kind = originalProp.type.kind;
+		if (kind === "object") {
+			const hasLabel = getFieldMeta(originalProp, META_LABEL) !== void 0;
+			const hasComponent = getFieldMeta(originalProp, UI_FORM_COMPONENT) !== void 0;
+			if (!hasLabel && !hasComponent) continue;
+		}
+		if (kind === "array") {
+			if (originalProp.type.of.type.kind === "array" && !getFieldMeta(originalProp, "ui.form.component")) continue;
+		}
+		if (kind === "array" || kind === "object" || kind === "union" || kind === "tuple") structuredPrefixes.add(path + ".");
+		fields.push(createFieldDef(path, originalProp));
+	}
+	const orderMap = new Map(fields.map((f) => [f, getFieldMeta(f.prop, "ui.form.order") ?? Infinity]));
+	fields.sort((a, b) => orderMap.get(a) - orderMap.get(b));
+	const rootField = {
+		path: "",
+		prop: type,
+		type: "object",
+		phantom: false,
+		name: "",
+		allStatic: false
+	};
+	const def = {
+		type,
+		rootField,
+		fields,
+		flatMap
+	};
+	rootField.objectDef = def;
+	return def;
+}
+/** Creates a FormFieldDef from any ATScript annotated type. */
+function createFieldDef(path, prop) {
+	const kind = prop.type.kind;
+	const name = path.slice(path.lastIndexOf(".") + 1);
+	const allStatic = !hasComputedAnnotations(prop);
+	const uiType = getFieldMeta(prop, "ui.form.type") ?? getFieldMeta(prop, "ui.type");
+	const base = {
+		path,
+		prop,
+		phantom: false,
+		name,
+		allStatic
+	};
+	const customType = uiType;
+	if (kind === "array") {
+		const arrayType = prop.type;
+		return {
+			...base,
+			type: "array",
+			customType,
+			itemType: arrayType.of,
+			itemField: createFieldDef("", arrayType.of)
+		};
+	}
+	if (kind === "object") return {
+		...base,
+		type: "object",
+		customType,
+		objectDef: createFormDef(prop)
+	};
+	if (kind === "union") {
+		if (isPureLiteralUnion(prop)) return {
+			...base,
+			type: uiType ?? "select"
+		};
+		const unionVariants = buildUnionVariants(prop);
+		if (unionVariants.length > 1) return {
+			...base,
+			type: "union",
+			customType,
+			unionVariants
+		};
+		const v = unionVariants[0];
+		if (v?.itemField) return {
+			...v.itemField,
+			path,
+			name,
+			allStatic
+		};
+		if (v?.def) return {
+			...base,
+			type: "object",
+			customType,
+			objectDef: v.def
+		};
+	}
+	if (kind === "tuple") {
+		const tupleType = prop.type;
+		return {
+			...base,
+			type: "tuple",
+			customType,
+			itemFields: tupleType.items.map((item, i) => {
+				const field = createFieldDef(String(i), item);
+				field.name = "";
+				return field;
+			})
+		};
+	}
+	if (extractValueHelp(prop)) return {
+		...base,
+		type: uiType ?? "ref"
+	};
+	const tags = kind === "" ? prop.type.tags : void 0;
+	let uiTag;
+	let isTimestamp = false;
+	if (tags) for (const t of tags) {
+		if (uiTag === void 0 && UI_TAGS.has(t)) uiTag = t;
+		if (t === "timestamp") isTimestamp = true;
+	}
+	const dt = kind === "" ? prop.type.designType : void 0;
+	let numericType;
+	if (kind === "") {
+		const hasCurrency = getFieldMeta(prop, "db.amount.currency") !== void 0 || getFieldMeta(prop, "db.amount.currency.ref") !== void 0;
+		const isDecimalDesign = dt === "decimal";
+		if (hasCurrency) numericType = "decimal";
+		else if (isDecimalDesign) numericType = "decimal";
+		else if (dt === "number") {
+			const hasUnit = getFieldMeta(prop, "db.unit") !== void 0 || getFieldMeta(prop, "db.unit.ref") !== void 0;
+			const hasPrefix = getFieldMeta(prop, "ui.form.prefix") !== void 0 || getFieldMeta(prop, "ui.form.prefix.ref") !== void 0 || getFieldMeta(prop, "ui.form.prefix.icon") !== void 0;
+			const hasSuffix = getFieldMeta(prop, "ui.form.suffix") !== void 0 || getFieldMeta(prop, "ui.form.suffix.ref") !== void 0 || getFieldMeta(prop, "ui.form.suffix.icon") !== void 0;
+			if (hasUnit || hasPrefix || hasSuffix) numericType = "number";
+		}
+	}
+	const tagType = isTimestamp ? "datetime" : void 0;
+	return {
+		...base,
+		type: uiType ?? uiTag ?? numericType ?? tagType ?? (dt === "number" ? "number" : dt === "boolean" ? "checkbox" : "text"),
+		phantom: kind === "" && dt === "phantom"
+	};
+}
+/** Resolves the original annotated type from the type hierarchy by path. */
+function resolveOriginalProp(type, path) {
+	const parts = path.split(".");
+	let current = type.type;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const prop = current.props.get(parts[i]);
+		if (!prop || prop.type.kind !== "object") return void 0;
+		current = prop.type;
+	}
+	return current.props.get(parts[parts.length - 1]);
+}
+/** Check if a path is a child of any structured prefix (prefixes are pre-suffixed with "."). */
+function isChildOfStructured(path, prefixes) {
+	for (const prefix of prefixes) if (path.startsWith(prefix)) return true;
+	return false;
+}
+/**
+* Builds union variant definitions from a union annotated type.
+* Iterates top-level items directly — one variant per item.
+*/
+function buildUnionVariants(typeDef) {
+	const items = typeDef.type.items ?? [typeDef];
+	const variants = [];
+	for (const item of items) {
+		const v = createVariant(item);
+		if (items.length > 1) v.label = `${String(variants.length + 1)}. ${v.label}`;
+		variants.push(v);
+	}
+	return variants;
+}
+/** Creates a single union variant from an annotated type item. */
+function createVariant(def) {
+	const kind = def.type.kind;
+	if (kind === "object") {
+		const label = getFieldMeta(def, "meta.label") ?? "Object";
+		const hasComponent = getFieldMeta(def, UI_FORM_COMPONENT) !== void 0;
+		return {
+			label,
+			type: def,
+			def: createFormDef(def),
+			itemField: hasComponent ? createFieldDef("", def) : void 0
+		};
+	}
+	if (kind === "") {
+		const dt = def.type.designType;
+		return {
+			label: capitalize(dt === "phantom" ? "item" : dt),
+			type: def,
+			itemField: createFieldDef("", def),
+			designType: dt
+		};
+	}
+	return {
+		label: capitalize(kind),
+		type: def,
+		itemField: createFieldDef("", def)
+	};
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//#endregion
+//#region src/value-help/dict-paths.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.
+*/
+function valueHelpDictPaths(resolved) {
+	const paths = [
+		...resolved.primaryKeys,
+		resolved.labelField,
+		...resolved.attrFields
+	];
+	if (resolved.descrField) paths.push(resolved.descrField);
+	return new Set(paths);
+}
+//#endregion
+//#region src/value-help/resolve-options.ts
+/** Extracts the key from an option entry. */
+function optKey(opt) {
+	return typeof opt === "string" ? opt : opt.key;
+}
+/** Extracts the display label from an option entry. */
+function optLabel(opt) {
+	return typeof opt === "string" ? opt : opt.label;
+}
+/**
+* Converts raw option annotation value to a normalized array.
+*/
+function parseStaticOptions(raw) {
+	return asArray(raw).map((item) => {
+		if (typeof item === "object" && item !== null && "label" in item) {
+			const { label, value } = item;
+			return value !== void 0 ? {
+				key: value,
+				label
+			} : label;
+		}
+		return String(item);
+	});
+}
+/**
+* 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
+*/
+function resolveOptions(prop, scope) {
+	const resolved = resolveFieldProp(prop, UI_FORM_FN_OPTIONS, UI_FORM_OPTIONS, scope, { transform: parseStaticOptions });
+	if (resolved !== void 0) return resolved;
+	return extractLiteralOptions(prop);
+}
+//#endregion
+//#region src/value-help/value-help-client.ts
+/**
+* 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.
+*/
+var ValueHelpClient = class {
+	_client;
+	constructor(client) {
+		this._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
+	*/
+	async search(resolved, opts) {
+		const mode = opts?.mode ?? "form";
+		const limit = opts?.limit ?? 20;
+		const selectFields = opts?.select ?? computeSelectFields(resolved, mode);
+		const text = opts?.text;
+		if (!text) return { items: await this._client.query({ controls: {
+			$select: selectFields,
+			$limit: limit
+		} }) };
+		if (resolved.searchable) return { items: await this._client.query({ controls: {
+			$select: selectFields,
+			$limit: limit,
+			$search: text
+		} }) };
+		const filter = buildOrFilter(text, selectFields, resolved.primaryKeys[0] ?? resolved.labelField);
+		return { items: await this._client.query({
+			filter,
+			controls: {
+				$select: selectFields,
+				$limit: limit
+			}
+		}) };
+	}
+};
+/**
+* Compute the $select fields for a value-help query.
+*/
+function computeSelectFields(resolved, mode) {
+	const fields = [...resolved.primaryKeys, resolved.labelField];
+	if (resolved.descrField) fields.push(resolved.descrField);
+	if (mode === "filter") fields.push(...resolved.attrFields);
+	return [...new Set(fields)];
+}
+/**
+* Build a Uniquery `$or` filter for value-help search across multiple fields.
+* Uses regex startsWith (case-insensitive) on text fields + exact match on PK.
+*/
+function buildOrFilter(text, fields, pkField) {
+	const escaped = text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const conditions = [];
+	for (const field of fields) if (field !== pkField) conditions.push({ [field]: { $regex: `/^${escaped}/i` } });
+	const asNum = Number(text);
+	if (!Number.isNaN(asNum)) conditions.push({ [pkField]: asNum });
+	else conditions.push({ [pkField]: text });
+	return { $or: conditions };
+}
+//#endregion
+//#region src/client-factory.ts
+const builtin = (url) => new Client(url);
+let _default = builtin;
+/**
+* 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.
+*/
+function setDefaultClientFactory(factory) {
+	_default = factory;
+}
+/** Current app-wide default factory. Falls back to `new Client(url)`. */
+function getDefaultClientFactory() {
+	return _default;
+}
+/** Reset the default factory to the built-in one (primarily for tests). */
+function resetDefaultClientFactory() {
+	_default = builtin;
+}
+//#endregion
+//#region src/shared/meta-cache.ts
+const cache = /* @__PURE__ */ new Map();
+/**
+* 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.
+*/
+function getMetaEntry(url, factory) {
+	const existing = cache.get(url);
+	if (existing) return existing;
+	const client = (factory ?? getDefaultClientFactory())(url);
+	const meta = client.meta().catch((err) => {
+		cache.delete(url);
+		throw err;
+	});
+	const entry = {
+		client,
+		meta,
+		type: meta.then((m) => deserializeAnnotatedType(m.type))
+	};
+	cache.set(url, entry);
+	return entry;
+}
+function resetMetaCache() {
+	cache.clear();
+}
+//#endregion
+//#region src/value-help/resolve.ts
+/**
+* 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.
+*/
+function resolveValueHelp(url) {
+	const entry = getMetaEntry(url);
+	if (entry.resolved) return entry.resolved;
+	entry.resolved = Promise.all([entry.meta, entry.type]).then(([meta, type]) => buildResolved(url, meta, type));
+	return entry.resolved;
+}
+/** Thin alias over `resetMetaCache` — retained so existing test code keeps working. */
+function resetValueHelpCache() {
+	resetMetaCache();
+}
+function buildResolved(url, meta, targetType) {
+	const objectType = targetType.type.kind === "object" ? targetType.type : void 0;
+	const primaryKeys = [];
+	let labelField;
+	let descrField;
+	const attrFields = [];
+	let firstStringField;
+	if (objectType) for (const [name, fieldProp] of objectType.props) {
+		const isPK = fieldProp.metadata.has(META_ID);
+		if (isPK) primaryKeys.push(name);
+		if (fieldProp.metadata.has("ui.dict.label")) labelField = name;
+		if (fieldProp.metadata.has("ui.dict.descr")) descrField = name;
+		if (fieldProp.metadata.has("ui.dict.attr")) attrFields.push(name);
+		if (!firstStringField && !isPK && fieldProp.type.kind === "" && fieldProp.type.designType === "string") firstStringField = name;
+	}
+	if (!labelField) labelField = firstStringField;
+	if (!labelField) labelField = primaryKeys[0] ?? "id";
+	const filterableFields = [];
+	const sortableFields = [];
+	if (meta.fields) for (const [name, fm] of Object.entries(meta.fields)) {
+		if (fm?.filterable) filterableFields.push(name);
+		if (fm?.sortable) sortableFields.push(name);
+	}
+	return {
+		url,
+		primaryKeys,
+		labelField,
+		descrField,
+		attrFields,
+		filterableFields,
+		sortableFields,
+		searchable: !!meta.searchable,
+		targetType
+	};
+}
+//#endregion
+//#region src/form/path-utils.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`).
+*/
+function getByPath(obj, path) {
+	const root = obj.value;
+	if (!path) return root;
+	const keys = path.split(".");
+	let current = root;
+	for (const key of keys) {
+		if (current === null || current === void 0 || typeof current !== "object") return void 0;
+		current = current[key];
+	}
+	return current;
+}
+/**
+* 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.
+*/
+function setByPath(obj, path, value) {
+	if (!path) {
+		obj.value = value;
+		return;
+	}
+	const keys = path.split(".");
+	const last = keys.pop();
+	if (last === void 0) return;
+	let current = obj.value;
+	for (const key of keys) {
+		if (current[key] === null || current[key] === void 0 || typeof current[key] !== "object") current[key] = {};
+		current = current[key];
+	}
+	current[last] = value;
+}
+function parseStaticDefault(raw, prop) {
+	if (typeof raw !== "string") return raw;
+	if (prop.type.kind === "" && prop.type.designType === "string") return raw;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+/** Cached default resolver — reused when no resolver is provided. */
+const defaultValueResolver = createFormValueResolver();
+function createFormValueResolver(data = {}, context = {}) {
+	return (prop, _path) => {
+		return resolveFieldProp(prop, UI_FORM_FN_VALUE, META_DEFAULT, {
+			v: void 0,
+			data,
+			context,
+			entry: void 0
+		}, { transform: (raw) => parseStaticDefault(raw, prop) });
+	};
+}
+/**
+* Type-appropriate "defined-but-empty" fallback for primitive design types
+* whose structural default in atscript's `finalDefault` table is
+* `undefined`. Without this, `createFormData` on an optional `decimal`
+* field (or any other primitive missed by atscript's table) returns
+* `undefined` — but `createFormData` is called from "explicit add"
+* contexts (optional-toggle, array-add, tuple-pad, union-pick) where the
+* caller's intent is "give me a value the renderer can edit", not "no
+* value yet". Returning `undefined` leaves the empty-state placeholder
+* stuck in AsFieldShell.
+*
+* `decimal → "0"` mirrors the `number → 0` default — the atscript runtime
+* validator (≥ 0.1.54) rejects `""` for decimal fields, so committing the
+* canonical zero is the only init that survives a submit-without-edit.
+* `useAsDecimal` pads the display to the field's effective scale, so the
+* user sees `0.00` / `0.000` per the `@db.column.precision` annotation.
+*/
+function primitiveInitFallback(prop) {
+	if (prop.type.kind !== "") return void 0;
+	switch (prop.type.designType) {
+		case "decimal": return "0";
+		default: return;
+	}
+}
+function createFormData(type, resolver) {
+	let value = createDataFromAnnotatedType(type, { mode: resolver ?? defaultValueResolver });
+	if (value === void 0) value = primitiveInitFallback(type);
+	return { value };
+}
+const variantValidatorCache = /* @__PURE__ */ new WeakMap();
+function getVariantValidator(variant) {
+	let v = variantValidatorCache.get(variant.type);
+	if (!v) {
+		v = variant.type.validator();
+		variantValidatorCache.set(variant.type, v);
+	}
+	return v;
+}
+const variantsDiscriminatorCache = /* @__PURE__ */ new WeakMap();
+function getVariantsDiscriminator(variants) {
+	let cached = variantsDiscriminatorCache.get(variants);
+	if (cached === void 0) {
+		cached = detectDiscriminator(variants.map((v) => v.type));
+		variantsDiscriminatorCache.set(variants, cached);
+	}
+	return cached;
+}
+function detectUnionVariant(value, variants) {
+	if (variants.length <= 1) return 0;
+	const disc = getVariantsDiscriminator(variants);
+	if (disc && value !== null && typeof value === "object") {
+		const tag = value[disc.propertyName];
+		const idx = disc.indexMapping[String(tag)];
+		if (idx !== void 0) return idx;
+	}
+	for (let i = 0; i < variants.length; i++) try {
+		if (getVariantValidator(variants[i]).validate(value, true)) return i;
+	} catch {}
+	return 0;
+}
+//#endregion
+//#region src/form/validate.ts
+let defaultValidatorPlugins = [];
+/** Replace the default validator plugins applied to every form/field validator. */
+function setDefaultValidatorPlugins(plugins) {
+	defaultValidatorPlugins = plugins;
+}
+/** Get the currently registered default validator plugins. */
+function getDefaultValidatorPlugins() {
+	return defaultValidatorPlugins;
+}
+/**
+* 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`.
+*/
+function getFormValidator(def, opts) {
+	const validator = new Validator(def.type, {
+		unknownProps: "ignore",
+		...opts,
+		plugins: [...defaultValidatorPlugins, ...opts?.plugins ?? []]
+	});
+	return (callOpts) => {
+		if (validator.validate(callOpts.data, true, {
+			data: callOpts.data,
+			context: callOpts.context ?? {}
+		})) return {};
+		const errors = {};
+		for (const err of validator.errors) errors[err.path] = err.message;
+		return errors;
+	};
+}
+/**
+* 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.
+*/
+function createFieldValidator(prop, opts) {
+	let cached;
+	return (value, externalCtx) => {
+		cached ??= new Validator(prop, { plugins: defaultValidatorPlugins });
+		if (!cached.validate(value, true, externalCtx)) {
+			if (opts?.rootOnly) {
+				const rootError = cached.errors?.find((e) => e.path === "");
+				if (rootError) return rootError.message;
+				return true;
+			}
+			return cached.errors?.[0]?.message || "Invalid value";
+		}
+		return true;
+	};
+}
+//#endregion
+//#region src/form/error-utils.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.
+*/
+const FORM_ERROR_KEY = "__form";
+/**
+* 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.
+*/
+function mergeErrorMaps(...maps) {
+	const merged = {};
+	for (const m of maps) {
+		if (!m) continue;
+		for (const k of Object.keys(m)) {
+			const v = m[k];
+			if (v) merged[k] = v;
+		}
+	}
+	return merged;
+}
+/**
+* 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.
+*/
+function* iteratePathAncestors(path) {
+	if (!path || path === FORM_ERROR_KEY) return;
+	let pos = path.length;
+	while (pos > 0) {
+		yield path.slice(0, pos);
+		const dot = path.lastIndexOf(".", pos - 1);
+		if (dot < 0) return;
+		pos = dot;
+	}
+}
+/**
+* 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.
+*/
+function buildDescendantErrorCounts(errors) {
+	const map = /* @__PURE__ */ new Map();
+	for (const errPath of Object.keys(errors)) {
+		if (!errors[errPath]) continue;
+		for (const prefix of iteratePathAncestors(errPath)) map.set(prefix, (map.get(prefix) ?? 0) + 1);
+	}
+	return map;
+}
+//#endregion
+//#region src/form/grid.ts
+/** Grid layout parsing for `@ui.form.grid.colSpan` / `@ui.form.grid.rowSpan`. */
+const DEFAULT_COL_SPAN = 12;
+const DEFAULT_ROW_SPAN = 1;
+const COL_SPAN_ALIASES = {
+	full: 12,
+	half: 6,
+	third: 4
+};
+/** Accepts "1"-"12" and the aliases "full" (12), "half" (6), "third" (4). */
+function parseColSpan(raw) {
+	if (!raw) return void 0;
+	const aliased = COL_SPAN_ALIASES[raw];
+	if (aliased !== void 0) return aliased;
+	const n = Number.parseInt(raw, 10);
+	if (Number.isFinite(n) && n >= 1 && n <= 12 && String(n) === raw) return n;
+}
+/** Accepts numeric strings "1"+; rejects "0", negatives, decimals, aliases. */
+function parseRowSpan(raw) {
+	if (!raw) return void 0;
+	const n = Number.parseInt(raw, 10);
+	if (Number.isFinite(n) && n >= 1 && String(n) === raw) return n;
+}
+/**
+* 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.
+*/
+function resolveGridSpec(colSpan, rowSpan) {
+	return {
+		col: {
+			desktop: parseColSpan(colSpan?.desktop) ?? 12,
+			narrow: parseColSpan(colSpan?.narrow) ?? 12
+		},
+		row: {
+			desktop: parseRowSpan(rowSpan?.desktop) ?? 1,
+			narrow: parseRowSpan(rowSpan?.narrow) ?? 1
+		}
+	};
+}
+/**
+* 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.
+*/
+function buildGridClasses(spec) {
+	const out = [];
+	if (spec.col.desktop !== 12) out.push(`col-span-${spec.col.desktop}`);
+	if (spec.row.desktop !== 1) out.push(`row-span-${spec.row.desktop}`);
+	if (spec.col.narrow !== spec.col.desktop) out.push(`as-narrow:col-span-${spec.col.narrow}`);
+	if (spec.row.narrow !== spec.row.desktop) out.push(`as-narrow:row-span-${spec.row.narrow}`);
+	return out.join(" ");
+}
+//#endregion
+//#region src/form/labels.ts
+/** Singular label for an array field (used by AsArray for "Add <singular>"). */
+function resolveSingularLabel(meta) {
+	if (!meta) return "item";
+	return getFieldMeta(meta, "ui.form.label.singular") || "item";
+}
+//#endregion
+//#region src/form/measurement.ts
+/**
+* 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.
+*/
+function extractMeasurement(prop) {
+	const precisionMeta = getFieldMeta(prop, DB_COLUMN_PRECISION);
+	return {
+		currencyCode: getFieldMeta(prop, DB_AMOUNT_CURRENCY),
+		currencyRefField: getFieldMeta(prop, DB_AMOUNT_CURRENCY_REF),
+		unitCode: getFieldMeta(prop, DB_UNIT),
+		unitRefField: getFieldMeta(prop, DB_UNIT_REF),
+		precisionScale: precisionMeta?.scale
+	};
+}
+//#endregion
+//#region src/form/decimal-format.ts
+const WHITESPACE_GROUP_RE = /[   ]/g;
+const numberFormatCache = /* @__PURE__ */ new Map();
+function getNumberFormat(locale, opts) {
+	const key = `${locale ?? ""}|${opts.style ?? ""}|${opts.currency ?? ""}|${opts.currencyDisplay ?? ""}|${opts.useGrouping ?? ""}|${opts.minimumFractionDigits ?? ""}|${opts.maximumFractionDigits ?? ""}`;
+	let f = numberFormatCache.get(key);
+	if (!f) {
+		f = new Intl.NumberFormat(locale, opts);
+		numberFormatCache.set(key, f);
+	}
+	return f;
+}
+const decimalSeparatorCache = /* @__PURE__ */ new Map();
+const thousandsSeparatorCache = /* @__PURE__ */ new Map();
+const currencyDisplayCache = /* @__PURE__ */ new Map();
+const currencyDecimalsCache = /* @__PURE__ */ new Map();
+/** "." in en-US, "," in fr-FR. Returns "." when locale is undefined. */
+function getDecimalSeparator(locale) {
+	const key = locale ?? "";
+	const cached = decimalSeparatorCache.get(key);
+	if (cached !== void 0) return cached;
+	let out = ".";
+	try {
+		out = getNumberFormat(locale, { useGrouping: false }).formatToParts(1.1).find((p) => p.type === "decimal")?.value ?? ".";
+	} catch {}
+	decimalSeparatorCache.set(key, out);
+	return out;
+}
+/**
+* "," in en-US, NNBSP (U+202F) in fr-FR. Returns "" when no grouping is
+* applied (or when Intl rejects the locale).
+*/
+function getThousandsSeparator(locale) {
+	const key = locale ?? "";
+	const cached = thousandsSeparatorCache.get(key);
+	if (cached !== void 0) return cached;
+	let out = "";
+	try {
+		out = getNumberFormat(locale, { useGrouping: true }).formatToParts(1e6).find((p) => p.type === "group")?.value ?? "";
+	} catch {}
+	thousandsSeparatorCache.set(key, out);
+	return out;
+}
+function getCurrencyDisplayParts(code, locale) {
+	const key = `${locale ?? ""}|${code}`;
+	const cached = currencyDisplayCache.get(key);
+	if (cached) return cached;
+	let out = {
+		symbol: code,
+		position: "prefix"
+	};
+	try {
+		const parts = getNumberFormat(locale, {
+			style: "currency",
+			currency: code,
+			currencyDisplay: "narrowSymbol"
+		}).formatToParts(0);
+		const idxCur = parts.findIndex((p) => p.type === "currency");
+		const idxInt = parts.findIndex((p) => p.type === "integer");
+		out = {
+			symbol: parts[idxCur]?.value ?? code,
+			position: idxInt === -1 || idxCur < idxInt ? "prefix" : "suffix"
+		};
+	} catch {}
+	currencyDisplayCache.set(key, out);
+	return out;
+}
+/**
+* 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`.
+*/
+function getCurrencyDecimals(code, locale) {
+	if (!code) return void 0;
+	const key = `${locale ?? ""}|${code}`;
+	if (currencyDecimalsCache.has(key)) return currencyDecimalsCache.get(key);
+	let out;
+	try {
+		const max = getNumberFormat(locale, {
+			style: "currency",
+			currency: code
+		}).resolvedOptions().maximumFractionDigits;
+		out = typeof max === "number" ? max : void 0;
+	} catch {
+		out = void 0;
+	}
+	currencyDecimalsCache.set(key, out);
+	return out;
+}
+/**
+* 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.
+*/
+function parseDecimalInput(raw, locale) {
+	if (typeof raw !== "string") return null;
+	const trimmed = raw.trim();
+	if (trimmed === "") return null;
+	const decSep = getDecimalSeparator(locale);
+	const thouSep = getThousandsSeparator(locale);
+	let sign = "";
+	let body = trimmed;
+	if (body.startsWith("-")) {
+		sign = "-";
+		body = body.slice(1);
+	} else if (body.startsWith("+")) body = body.slice(1);
+	if (body.length === 0) return null;
+	if (body.includes("-") || body.includes("+")) return null;
+	if (thouSep && body.includes(thouSep)) {
+		const decIdx = body.indexOf(decSep);
+		const headRaw = decIdx === -1 ? body : body.slice(0, decIdx);
+		const tail = decIdx === -1 ? "" : body.slice(decIdx);
+		if (tail.includes(thouSep)) return null;
+		if (headRaw.includes(thouSep)) {
+			const groups = headRaw.split(thouSep);
+			const first = groups[0];
+			if (first.length < 1 || first.length > 3 || !/^\d+$/.test(first)) return null;
+			for (let i = 1; i < groups.length; i += 1) if (!/^\d{3}$/.test(groups[i])) return null;
+		}
+		body = `${headRaw.split(thouSep).join("")}${tail}`;
+	}
+	body = body.replace(WHITESPACE_GROUP_RE, "");
+	if (decSep !== ".") {
+		if ((body.match(/,/g)?.length ?? 0) > 1) return null;
+		if (body.includes(".") && body.includes(",")) return null;
+		if (body.includes(",")) body = body.replace(",", ".");
+	} else if (body.includes(",")) {
+		if (body.includes(".")) return null;
+		if ((body.match(/,/g)?.length ?? 0) > 1) return null;
+		body = body.replace(",", ".");
+	}
+	if (!/^\d*\.?\d*$/.test(body)) return null;
+	if (body === "" || body === ".") return null;
+	if (body.endsWith(".")) body = body.slice(0, -1);
+	if (body.startsWith(".")) body = `0${body}`;
+	const dot = body.indexOf(".");
+	if (dot === -1) body = body.replace(/^0+(\d)/, "$1");
+	else {
+		const head = body.slice(0, dot);
+		const tail = body.slice(dot);
+		body = `${head.replace(/^0+(\d)/, "$1")}${tail}`;
+	}
+	if (sign === "-" && /^0+(\.0+)?$/.test(body)) sign = "";
+	return `${sign}${body}`;
+}
+/**
+* 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)
+*/
+function enforceScale(s, scale, opts) {
+	if (typeof s !== "string" || s === "") return s;
+	if (scale === void 0 || scale < 0) return s;
+	const parts = splitDecimalString(s);
+	if (scale === 0) {
+		if (opts?.roundHalfUp && parts.decimal.length > 0 && parts.decimal[0] >= "5") {
+			const bumped = addOne(parts.integer);
+			return joinDecimalString({
+				sign: parts.sign,
+				integer: bumped,
+				decimal: ""
+			});
+		}
+		return joinDecimalString({
+			sign: parts.sign,
+			integer: parts.integer,
+			decimal: ""
+		});
+	}
+	if (parts.decimal.length === scale) return joinDecimalString(parts);
+	if (parts.decimal.length < scale) return joinDecimalString({
+		sign: parts.sign,
+		integer: parts.integer,
+		decimal: parts.decimal.padEnd(scale, "0")
+	});
+	let head = parts.decimal.slice(0, scale);
+	const dropped = parts.decimal.slice(scale);
+	let integer = parts.integer;
+	if (opts?.roundHalfUp && dropped.length > 0 && dropped[0] >= "5") {
+		const bumpedFrac = addOne(head);
+		if (bumpedFrac.length > head.length) {
+			integer = addOne(integer);
+			head = "0".repeat(scale);
+		} else head = bumpedFrac;
+	}
+	return joinDecimalString({
+		sign: parts.sign,
+		integer,
+		decimal: head
+	});
+}
+function addOne(digits) {
+	if (digits === "") return "1";
+	const out = digits.split("");
+	let i = out.length - 1;
+	let carry = 1;
+	while (i >= 0 && carry > 0) {
+		const d = out[i].charCodeAt(0) - 48 + carry | 0;
+		if (d >= 10) {
+			out[i] = "0";
+			carry = 1;
+		} else {
+			out[i] = String.fromCharCode(d + 48);
+			carry = 0;
+		}
+		i -= 1;
+	}
+	if (carry > 0) out.unshift("1");
+	return out.join("");
+}
+function splitDecimalString(s) {
+	if (typeof s !== "string" || s === "") return {
+		sign: "",
+		integer: "0",
+		decimal: ""
+	};
+	let sign = "";
+	let body = s;
+	if (body.startsWith("-")) {
+		sign = "-";
+		body = body.slice(1);
+	} else if (body.startsWith("+")) body = body.slice(1);
+	if (body === "") return {
+		sign: "",
+		integer: "0",
+		decimal: ""
+	};
+	const dot = body.indexOf(".");
+	let integer;
+	let decimal;
+	if (dot === -1) {
+		integer = body;
+		decimal = "";
+	} else {
+		integer = body.slice(0, dot);
+		decimal = body.slice(dot + 1);
+	}
+	if (integer === "") integer = "0";
+	integer = integer.replace(/^0+(\d)/, "$1");
+	if (sign === "-" && integer === "0" && !decimal.replace(/0/g, "")) sign = "";
+	return {
+		sign,
+		integer,
+		decimal
+	};
+}
+function joinDecimalString(parts) {
+	const integer = parts.integer === "" ? "0" : parts.integer;
+	const decimal = parts.decimal;
+	const body = decimal === "" ? integer : `${integer}.${decimal}`;
+	return `${parts.sign}${body}`;
+}
+function formatDecimalForDisplay(opts) {
+	const { value, scale, locale, currency, unit, useGrouping = true } = opts;
+	if (value === null || value === void 0 || value === "") return "";
+	let canonical;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) return "";
+		canonical = String(value);
+	} else canonical = value;
+	if (!/^[+-]?\d*(\.\d*)?$/.test(canonical) || canonical === "." || canonical === "-") return canonical;
+	if (scale !== void 0 && scale >= 0) canonical = enforceScale(canonical, scale);
+	const parts = splitDecimalString(canonical);
+	const asNumber = Number(canonical);
+	const intlSafe = Number.isFinite(asNumber);
+	if (currency) {
+		try {
+			const fmt = getNumberFormat(locale, {
+				style: "currency",
+				currency,
+				currencyDisplay: "narrowSymbol",
+				minimumFractionDigits: scale,
+				maximumFractionDigits: scale,
+				useGrouping
+			});
+			if (intlSafe) return fmt.format(asNumber);
+		} catch {}
+		return `${currency} ${formatPlain(parts, scale, locale, useGrouping)}`;
+	}
+	const base = formatPlain(parts, scale, locale, useGrouping);
+	return unit ? `${base} ${unit}` : base;
+}
+function formatPlain(parts, scale, locale, useGrouping) {
+	const intStr = useGrouping ? groupInteger(parts.integer, locale) : parts.integer;
+	const decStr = scale !== void 0 && scale >= 0 ? parts.decimal.padEnd(scale, "0").slice(0, scale) : parts.decimal;
+	const decSep = getDecimalSeparator(locale);
+	const body = decStr.length > 0 ? `${intStr}${decSep}${decStr}` : intStr;
+	return `${parts.sign}${body}`;
+}
+/**
+* Insert the locale's thousands separator into a plain integer string.
+* Pure string-based — no float math, handles arbitrary length.
+*/
+function groupInteger(integer, locale) {
+	const sep = getThousandsSeparator(locale);
+	if (!sep) return integer;
+	if (integer.length <= 3) return integer;
+	const out = [];
+	let i = integer.length;
+	while (i > 3) {
+		out.unshift(integer.slice(i - 3, i));
+		i -= 3;
+	}
+	out.unshift(integer.slice(0, i));
+	return out.join(sep);
+}
+//#endregion
+//#region src/table/create-table-def.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
+*/
+function createTableDef(meta, preDeserializedType) {
+	const type = preDeserializedType ?? deserializeAnnotatedType(meta.type);
+	const flatMap = type.type.kind === "object" ? flattenAnnotatedType(type, { excludePhantomTypes: true }) : /* @__PURE__ */ new Map();
+	const columns = [];
+	for (const [path, prop] of flatMap.entries()) {
+		if (path === "") continue;
+		if (!(path in meta.fields)) {
+			const kind = prop.type.kind;
+			if (path.includes(".") || kind === "object" || kind === "array") continue;
+		}
+		const fieldMeta = meta.fields[path];
+		const options = extractLiteralOptions(prop);
+		const valueHelpInfo = extractValueHelp(prop);
+		const maxLengthMeta = getFieldMeta(prop, EXPECT_MAX_LENGTH);
+		const tableType = getFieldMeta(prop, UI_TABLE_TYPE);
+		const sharedType = getFieldMeta(prop, UI_TYPE);
+		const tableComponent = getFieldMeta(prop, UI_TABLE_COMPONENT);
+		columns.push({
+			path,
+			label: getFieldMeta(prop, "meta.label") ?? humanizePath(path),
+			type: tableType ?? sharedType ?? (valueHelpInfo ? "ref" : inferDisplayType(prop, options)),
+			component: tableComponent,
+			sortable: fieldMeta?.sortable ?? false,
+			filterable: fieldMeta?.filterable ?? false,
+			nullable: prop.optional === true,
+			visible: getFieldMeta(prop, UI_TABLE_HIDDEN) === void 0,
+			width: getFieldMeta(prop, UI_TABLE_WIDTH),
+			maxLen: maxLengthMeta?.length,
+			order: getFieldMeta(prop, "ui.table.order") ?? Infinity,
+			options,
+			valueHelpInfo,
+			...extractMeasurement(prop)
+		});
+	}
+	columns.sort((a, b) => a.order - b.order);
+	const actions = groupActions(meta.actions ?? []);
+	const crud = meta.crud ?? {};
+	return {
+		type,
+		columns,
+		flatMap,
+		primaryKeys: meta.primaryKeys,
+		preferredId: meta.preferredId ?? meta.primaryKeys,
+		crud,
+		canRemove: "remove" in crud,
+		actions,
+		searchable: meta.searchable,
+		vectorSearchable: meta.vectorSearchable,
+		searchIndexes: meta.searchIndexes,
+		relations: meta.relations
+	};
+}
+/** Sort by (order ?? 0). `toSorted` is stable per spec, so ties preserve declaration order. */
+function byOrder(xs) {
+	return xs.toSorted((x, y) => (x.order ?? 0) - (y.order ?? 0));
+}
+/**
+* Partition actions by `level`, sort each group by `(order ?? 0)` then
+* declaration order, and pick the first `default: true` entry per level.
+* The synthesised `__remove` UI action lives outside this set and is never
+* a candidate for `default.row`.
+*/
+function groupActions(actions) {
+	const table = [];
+	const row = [];
+	const rows = [];
+	for (const a of actions) if (a.level === "table") table.push(a);
+	else if (a.level === "row") row.push(a);
+	else if (a.level === "rows") rows.push(a);
+	const tableSorted = byOrder(table);
+	const rowSorted = byOrder(row);
+	const rowsSorted = byOrder(rows);
+	return {
+		table: tableSorted,
+		row: rowSorted,
+		rows: rowsSorted,
+		default: {
+			table: tableSorted.find((a) => a.default === true),
+			row: rowSorted.find((a) => a.default === true),
+			rows: rowsSorted.find((a) => a.default === true)
+		}
+	};
+}
+/** Infers a display type string from the annotated type's kind and designType. */
+function inferDisplayType(prop, literalOpts) {
+	const kind = prop.type.kind;
+	if (kind === "array") return "array";
+	if (kind === "object") return "object";
+	if (kind === "union") return literalOpts !== void 0 ? "enum" : "union";
+	if (kind === "") {
+		const final = prop.type;
+		const dt = final.designType;
+		if (dt === "number") return final.tags?.has("timestamp") ? "datetime" : "number";
+		if (dt === "decimal") return "number";
+		if (dt === "boolean") return "boolean";
+		return "text";
+	}
+	return "text";
+}
+/** Converts a dot-path to a human-readable label (e.g. 'firstName' → 'First Name'). */
+function humanizePath(path) {
+	return path.slice(path.lastIndexOf(".") + 1).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (s) => s.toUpperCase());
+}
+//#endregion
+//#region src/shared/str.ts
+/** Safely convert an unknown value to a string without triggering no-base-to-string lint errors. */
+function str(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return `${value}`;
+	return JSON.stringify(value) ?? "";
+}
+//#endregion
+//#region src/table/column-resolver.ts
+/** Get visible columns only, already sorted by order. */
+function getVisibleColumns(def) {
+	return def.columns.filter((c) => c.visible);
+}
+/** Get sortable columns. */
+function getSortableColumns(def) {
+	return def.columns.filter((c) => c.sortable);
+}
+/** Get filterable columns. */
+function getFilterableColumns(def) {
+	return def.columns.filter((c) => c.filterable);
+}
+/** Find a column by path. */
+function getColumn(def, path) {
+	return def.columns.find((c) => c.path === path);
+}
+//#endregion
+export { 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, EXPECT_MAX_LENGTH, META_DEFAULT, META_DESCRIPTION, META_ID, META_LABEL, META_READONLY, META_REQUIRED, META_SENSITIVE, StaticFieldResolver, 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, 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 };