---
URL: "ui.atscript.dev/"
LLMS_URL: "ui.atscript.dev/index.md"
layout: "home"
hero2:
  text: "Your types render themselves."
  tagline: "Forms, smart tables and multi-step HTTP flows — declared once in `.as`, rendered everywhere. No render boilerplate, no manual wiring, no schema drift."
actions:
  - theme: "brand"
        text: "Quick Start"
        link: "/guide/quick-start"
  - theme: "alt"
        text: "View on GitHub"
        link: "https://github.com/moostjs/atscript-ui"
---



---
URL: "ui.atscript.dev/api/moost-ui-presets"
LLMS_URL: "ui.atscript.dev/api/moost-ui-presets.md"
---

# @atscript/moost-ui-presets

Moost controller + atscript schema for table-preset persistence. Subclass `AsPresetsController` to wire the table to your auth layer; the rest (CRUD, dirty detection, public-label uniqueness, per-user quotas, capabilities endpoint) ships out of the box. Pair with [`@atscript/vue-table`](/api/vue-table)'s `usePresets()` / `<AsPresetPicker>` to ship full preset UX.

## Contents

- [Controller](#controller)
- [Schema — AsPresetEntry](#schema-aspresetentry)
- [Re-exports](#re-exports)

## Controller

### `AsPresetsController<T?>`

Abstract base extending `AsDbController` from `@atscript/moost-db`. Inherits the standard CRUD endpoints (GET, POST, PATCH, DELETE) and adds:

- `GET /capabilities?app=...&tableKey=...` — returns the user's preset capabilities (publish rights, quota).
- Read gating — `transformFilter` injects an owner-aware filter so users only see their own private rows and everyone's public rows.
- Write hooks — `onWrite` enforces label uniqueness, quota, and stamps `userLabel` / `publicLabel` / `aspects`.
- Delete gating — `onRemove` only allows owners to delete.

```typescript
@Inherit()
abstract class AsPresetsController<
  T extends TAtscriptAnnotatedType = typeof AsPresetEntry,
> extends AsDbController<T> {
  protected maxPresetsPerUser: number; // 10
  protected abstract getCurrentUser(): Promise<string>;

  protected getMaxPresetsPerUser(
    app: string,
    tableKey: string,
    user: string,
  ): Promise<number>;
  protected canPublishPresets(
    app: string,
    tableKey: string,
    user: string,
  ): Promise<boolean>;
  protected getUserLabel(user: string): Promise<string | undefined>;

  @Get("capabilities")
  capabilities(query: AsCapabilitiesQuery): Promise<PresetCapabilities>;
}
```

### Implementation example

```typescript
import { Controller } from "moost";
import { AsPresetsController } from "@atscript/moost-ui-presets";

@Controller("/presets")
class PresetsController extends AsPresetsController {
  constructor(private readonly auth: AuthService) {
    super();
  }

  protected async getCurrentUser(): Promise<string> {
    const user = await this.auth.currentUser();
    if (!user) throw new HttpError(401, "Unauthorized");
    return user.id;
  }

  /** Free tier: 10 presets. Paid: 100. Admin: unlimited. */
  protected async getMaxPresetsPerUser(app: string, _table: string, user: string) {
    const tier = await this.auth.tierOf(user);
    return tier === "admin" ? Number.MAX_SAFE_INTEGER : tier === "paid" ? 100 : 10;
  }

  protected async canPublishPresets(_app: string, _table: string, user: string) {
    return (await this.auth.tierOf(user)) !== "free";
  }

  protected async getUserLabel(user: string) {
    return (await this.auth.profileOf(user))?.displayName;
  }
}
```

### Extension points

| Method                                      | Default                               | Override when                                        |
| ------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
| `getCurrentUser()`                          | abstract                              | Always — wire to your auth layer.                    |
| `getMaxPresetsPerUser(app, tableKey, user)` | returns `this.maxPresetsPerUser` (10) | Tiered quotas (admin / paid / free).                 |
| `canPublishPresets(app, tableKey, user)`    | returns `true`                        | Restrict public presets by tier or per-table policy. |
| `getUserLabel(user)`                        | returns `undefined`                   | Surface display names on shared presets.             |

### REST endpoints

All endpoints inherited from `AsDbController` work with `AsPresetEntry` rows. The controller adds:

- `GET /capabilities?app=<app>&tableKey=<tableKey>` → `PresetCapabilities`.

The `@atscript/ui-table` [`PresetsClient`](/api/ui-table#presets-http-clients) targets this exact controller.

## Schema — AsPresetEntry

The atscript-db row shape. Stored in table `as_presets`.

```atscript
@db.table 'as_presets'
export interface AsPresetEntry {
  @meta.id
  @db.default.uuid
  id: string

  /** Row kind — drives the polymorphic `data` column. */
  type: 'preset' | 'userConf' | 'appConf'

  /** App scope. Required on every row. */
  app: string

  /** Per-table scope. Required for `preset` / `userConf`; absent for `appConf`. */
  tableKey?: string

  /** Owner user id. Stamped by the controller from session. */
  user: string

  /** Optional display name for shared presets. */
  userLabel?: string

  /** Visible to other users when true. Only meaningful for `type='preset'`. */
  public?: boolean

  /** Mirror of `data.label` — top-level for indexable lookups. `type='preset'` only. */
  label?: string

  /** Race-safe public-name uniqueness column. `type='preset' AND public=true` only. */
  publicLabel?: string

  /** Aspects this preset claims — derived by the controller on every write. */
  aspects?: PresetAspect[]

  @db.json
  data: PresetData | UserConfData | AppConfData

  @db.default.now createdAt: number
  @db.default.now updatedAt: number
}
```

### Polymorphic `data` shape

- **`type='preset'`** → [`PresetData`](/api/ui-table#presets-application-types): `{ label, content?: PresetSnapshotWire }`. The snapshot blob carries `columns`, `filters`, `filterOps`, `sorters`, `itemsPerPage`.
- **`type='userConf'`** → [`UserConfData`](/api/ui-table#presets-application-types): `{ defaultPresetId?, favPresetIds? }`. Per-table user preferences.
- **`type='appConf'`** → [`AppConfData`](/api/ui-table#presets-application-types): `{ appearance?, language?, timezone?, density?, dateFormat?, firstDayOfWeek?, customJson? }`. App-wide per-user preferences (one row per `(user, app)`).

### Validation rules enforced by the controller

- `aspects[]` is rebuilt from `data.content` keys on every write — clients can't fake aspect claims.
- `label` is mirrored from `data.label` on every `type='preset'` write.
- `publicLabel` is stamped equal to `label` on `type='preset' AND public=true` writes, NULL otherwise. The composite unique index `preset_public_label_idx (app, tableKey, publicLabel)` relies on NULL ≠ NULL semantics so private / userConf / appConf rows never collide.
- `user` is stamped from `getCurrentUser()` on every write — clients can't author rows under another user.
- Per-user quota is checked on insert; exceeding it returns HTTP `409` with `code: "preset_limit_reached"` and `{ limit, count }` in the body.

## Re-exports

From [`@atscript/ui-table`](/api/ui-table) — re-exported so consumers can grab schema-relevant types from one import:

```typescript
export {
  // Types
  type AppConfData,
  type AsPresetEntryData,
  type AsPresetsErrorCode,
  type FilterCondition,
  type FilterConditionType,
  type PresetAspect,
  type PresetCapabilities,
  type PresetData,
  type PresetLimitReachedBody,
  type PresetSnapshotWire,
  type UserConfData,

  // Constants
  APP_CONF_PREFIX,
  PRESET_ASPECTS,
  RESERVED_ID_PREFIXES,
  SYSTEM_PRESET_PREFIX,
  USER_CONF_PREFIX,

  // Helpers
  appConfId,
  userConfId,
} from "@atscript/ui-table";
```

`appConfId(user, app)` and `userConfId(user, app, tableKey)` are the deterministic id builders the controller uses for the singleton `appConf` and per-table `userConf` rows.

## Cross-links

- [Tables — Presets](/tables/presets), [Server-Side Presets](/tables/server-presets)
- [@atscript/ui-table](/api/ui-table) — wire types, draft helpers, `PresetsClient`
- [@atscript/vue-table](/api/vue-table) — `usePresets()`, `<AsPresetPicker>`, `<AsPresetDialog>`
- [db.atscript.dev — Tables](https://db.atscript.dev/api/tables) — base CRUD endpoints inherited from `AsDbController`
- atscript.dev — `.as` syntax, `@db.*` annotations


---
URL: "ui.atscript.dev/api/moost-wf"
LLMS_URL: "ui.atscript.dev/api/moost-wf.md"
---

# @atscript/moost-wf

Server-side workflow runtime that pairs with [`@atscript/vue-wf`](/api/vue-wf). Decorators (`@WfInput`, `@WfAction`), a schema-aware composable (`useAtscriptWf`), helpers for context passing and action discovery, plus an opt-in store implementation backed by atscript-db. Atscript-typed forms are the contract — the client renders whatever schema the server returns.

## Contents

- [Plugin](#plugin)
- [Decorators](#decorators)
- [Composables](#composables)
- [Helpers](#helpers)
- [Outlet helpers](#outlet-helpers)
- [Finish-screen envelope](#finish-screen-envelope)
- [Store subpath](#store-subpath)

## Plugin

### `@atscript/moost-wf/plugin`

Registers the workflow-specific annotation keys at build time.

```typescript
import wfPlugin from "@atscript/moost-wf/plugin";

export default {
  plugins: [wfPlugin()],
};
```

Annotations registered:

- `@wf.context.pass 'key'` — whitelist a workflow context key for the `inputRequired` response. Only listed keys reach the client.
- `@wf.action.withData 'id'` — form action that ships partial form data with deep-partial validation (e.g. "save draft").
- `@wf.store.fromContext 'path'` — shadow-column copy from `state.context` into a top-level DB column (`AsWfStore` only). Path is dot-notation; field must be optional or have `@meta.default` / `@db.default`; primitive type only (`string` | `number` | `boolean`).

## Decorators

### `@WfInput(opts?)`

Parameter decorator that resolves to the validated, typed input for the current step. Built on top of `useAtscriptWf()` with the action-aware policy matrix baked in.

```typescript
function WfInput(opts?: { pass?: boolean }): ParameterDecorator;
```

```typescript
import { WfInput } from "@atscript/moost-wf";
import { Step } from "@moostjs/event-wf";
import type { LoginForm } from "./LoginForm.as";

class AuthFlow {
  @Step("login")
  async login(@WfInput() input: LoginForm) {
    try {
      return await this.auth.login(input.username, input.password);
    } catch {
      // requireInput() builds a StepRetriableError — throw it to re-pause.
      throw useAtscriptWf(LoginForm).requireInput({
        errors: { password: "Invalid credentials" },
      });
    }
  }
}
```

Policy matrix:

| Situation                                          | Behaviour                                                                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| No action fired                                    | Strict full validation against the schema. Missing input throws `StepRetriableError`.                                                                 |
| Action declared in `@wf.action.withData`           | Deep-partial validation — present fields validated, missing fields OK.                                                                                |
| Action declared in `@ui.form.action`               | Input must be absent. Without `pass: true`, the decorator throws (no-data actions exclude this step).                                                 |
| Action declared in `@ui.form.action`, `pass: true` | The step opts in to handling the no-data action: parameter resolves to `undefined`, body still runs.                                                  |
| Unknown action                                     | `StepRetriableError` propagates with `__form: 'Action "<name>" is not supported'`. Same guard fires from `@WfAction(Form)` before the step body runs. |

Use `?:` syntax (`input?: Form`), not a union (`input: Form | undefined`) — TS emits `Object` for union-typed parameters in decorator metadata, which breaks atscript reflection. `@WfInput({ pass: true })` composes `@Optional()` internally so the parameter being `undefined` is fine for global validator pipes.

### `@WfAction(Form)`

Parameter decorator that resolves to the current workflow action name (or `undefined` for plain submits). The form type argument is **required** — the decorator validates the incoming action against the form's `@ui.form.action` / `@wf.action.withData` whitelist and throws `StepRetriableError` for unknown actions before the step body runs.

```typescript
function WfAction<T extends TAtscriptTypeDef>(type: TAtscriptAnnotatedType<T>): ParameterDecorator;
```

```typescript
@Step("mfa-verify")
async mfaVerify(
  @WfAction(PincodeForm) action: string | undefined,
  @WfInput() input: PincodeForm,
) {
  if (action === "resend") {
    await this.sendOtp(this.ctx.email);
    return;
  }
  await this.verifyCode(input.code);
}
```

The form-argument whitelist is a security guard: step bodies never see an action that wasn't declared on the form. Use the same form type the step receives via `@WfInput`.

## Composables

### `useAtscriptWf(type)`

Schema-driven workflow I/O primitives. Returns three pure, independent helpers — composable consumers can interleave their own logic between checking the action and validating the input.

```typescript
function useAtscriptWf<T extends TAtscriptTypeDef>(
  type: TAtscriptAnnotatedType<T>,
): {
  resolveInput(opts?: { partial?: "deep" }): InferDataType<T>;
  resolveAction(): string | undefined;
  requireInput(opts?: {
    errors?: Record<string, string>;
    formMessage?: string;
  }): StepRetriableError;
};
```

| Method                | Purpose                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolveInput(opts?)` | Validates `state.input` against the schema and returns it typed. Throws `StepRetriableError` if input is missing or invalid. **Does not consult the action.** |
| `resolveAction()`     | Returns the action name (or `undefined`). Throws `StepRetriableError` if the action is not declared on the schema. **Does not consult the input.**            |
| `requireInput(opts?)` | Builder for `StepRetriableError`. `errors` is field-keyed; `formMessage` becomes the top-level `__form` error. Use it to bail out from custom branches.       |

Validator instances are cached per `(type, opts)` pair.

```typescript
import { useAtscriptWf } from "@atscript/moost-wf";
import { LoginForm } from "./LoginForm.as";

@Step("login")
async login() {
  const wf = useAtscriptWf(LoginForm);
  const action = wf.resolveAction();
  if (action === "forgot") {
    await this.sendPasswordReset();
    return;
  }
  const input = wf.resolveInput();
  // ... auth ...
  if (failed) {
    throw wf.requireInput({ errors: { password: "Invalid credentials" } });
  }
}
```

## Helpers

### `serializeFormSchema(type)`

Cached per-type serializer for `inputRequired.payload`. Drops `@wf.context.pass` from the output (server-only) and ships FK fields with shallow refs (`refDepth: 0.5`) so clients can resolve value-help without dragging full target trees onto the wire.

```typescript
function serializeFormSchema(type: TAtscriptAnnotatedType): unknown;
```

### `extractPassContext(type, wfContext)`

Extract whitelisted context keys (those marked `@wf.context.pass`) from workflow state.

```typescript
function extractPassContext(
  type: TAtscriptAnnotatedType,
  wfContext: Record<string, unknown>,
): Record<string, unknown>;
```

### `getFormActions(type)`

Inspects a form type's metadata and returns the declared `actions` and `actionsWithData` ids — used internally by `useAtscriptWf` to classify the incoming action.

```typescript
interface TFormActions {
  actions: string[];
  actionsWithData: string[];
}

function getFormActions(type: TAtscriptAnnotatedType): TFormActions;
```

Reads `@ui.form.action` and `@wf.action.withData`. Results are cached per type identity.

## Outlet helpers

### `createAsHttpOutlet()`

Pre-configured HTTP outlet for `<AsWfForm>`. Wraps generic form payloads in `{ inputRequired: { payload, transport, context } }` while letting signal payloads (`finished` / `sent` / `outlet` / `error`) flow through unwrapped.

### `handleAsOutletRequest(opts, deps)`

Drop-in replacement for `handleWfOutletRequest` (from `@moostjs/event-wf`). Adds the `finished: true` marker that `<AsWfForm>` reads when a step calls `useWfFinished().set({ value })`.

```typescript
import { createAsHttpOutlet, handleAsOutletRequest } from "@atscript/moost-wf";

@Post("wf")
async handle() {
  // ... build deps ...
  return handleAsOutletRequest(
    {
      allow: ["auth/login"],
      state: () => new EncapsulatedStateStrategy({ secret: WF_SECRET }),
      outlets: [createAsHttpOutlet()],
      token: { read: ["body"], write: "body", name: "wfs" },
    },
    deps,
  );
}
```

## Finish-screen envelope

Helpers for the unified `WfFinished` envelope rendered by `<AsWfFinish>` on the client. Reach for `finishWf` / `abortWf` instead of raw `useWfFinished()` unless you need to set HTTP-level cookies alongside the envelope.

### `finishWf(opts?)`

Builds and writes a `WfFinished` envelope to `useWfFinished()`.

```typescript
function finishWf(opts?: FinishWfOpts): void;

interface FinishWfOpts {
  data?: unknown;
  message?: WfMessage;
  next?: WfNext;
}
```

### `abortWf(reason, opts?)`

Same shape as `finishWf`, additionally sets `aborted: true` and the abort `reason`.

```typescript
function abortWf(reason: string, opts?: FinishWfOpts): void;
```

### `isWfFinished(value)`

Type guard for `WfFinished` envelopes — useful in custom transports or outlet wrappers.

```typescript
function isWfFinished(value: unknown): value is WfFinished;
```

### Envelope types

`WfFinished` carries `{ aborted?, reason?, data?, message?, next? }`. `WfNext` is the `{ trigger: 'immediate' | 'auto' | 'manual', ... }` discriminated union the client renders. `WfMessage`, `WfButton`, and `WfActionRequest` round out the schema. See [Finish Screens](/workflows/finish-screens) for the full surface.

## Store subpath

`@atscript/moost-wf/store` ships an opt-in `WfStateStore` implementation backed by an atscript-db table.

### `AsWfStateRecord`

The base atscript interface defining the columns the store reads/writes. Consumers extend it with their own `@meta.id`-bearing primary-key column.

```atscript
// .as files import the model from `/store.as` (raw atscript source).
// .ts files import the runtime class from `/store` (compiled module).
import { AsWfStateRecord } from '@atscript/moost-wf/store.as'

@db.table 'wf_state'
interface WfStateRow extends AsWfStateRecord {
  @meta.id
  @db.default.uuid
  id: string

  // Shadow columns — auto-populated from state.context on every set()
  @wf.store.fromContext 'approval.approver'
  approver?: string
}
```

Columns provided by `AsWfStateRecord`: `handle`, `schemaId`, `state` (JSON), `expiresAt?`, `createdAt`, `updatedAt`, `createdBy?`, `lastUpdatedBy?`.

### `AsWfStore`

Persistent `WfStateStore` (from `@prostojs/wf/outlets`) backed by an `AtscriptDbTable`. Lifts `schemaId` out of the JSON blob into an indexed top-level column; populates `@wf.store.fromContext`-annotated shadow columns on every write.

```typescript
class AsWfStore implements WfStateStore {
  constructor(opts: AsWfStoreOptions);

  set(handle: string, state: WfState, expiresAt?: number): Promise<void>;
  get(handle: string): Promise<{ state: WfState; expiresAt?: number } | null>;
  delete(handle: string): Promise<void>;
  /** Race-safe single-use consume — `findRow` → `deleteMany` → `deletedCount === 1` gate. */
  getAndDelete(handle: string): Promise<{ state: WfState; expiresAt?: number } | null>;
  /** Drop expired rows. `retention` extends the grace window; `Infinity` is a no-op. */
  cleanup(opts?: { retention?: number }): Promise<number>;
  /** Re-apply `@wf.store.fromContext` shadow columns to existing rows. */
  heal(opts?: { filter?: Record<string, unknown>; batchSize?: number }): Promise<number>;
}

interface AsWfStoreOptions {
  table: AtscriptDbTable<any>;
  clock?: { now(): number };
  actor?: () => string | undefined;
}
```

### Shadow-column mechanism

When a field on the consumer's row schema carries `@wf.store.fromContext 'path'`:

1. On every `set()`, the store reads `state.context` along the dot-path.
2. If the resolved value is `string` / `number` / `boolean`, it is written to the matching DB column.
3. On miss (or type mismatch), **optional** fields get `null` (clears stale); non-optional default-bearing fields are omitted (DB default fires on insert, prior value sticks on update).
4. Type mismatches emit a single console warning per field per store instance.

`heal()` re-applies shadows after you add a new annotation, so existing rows backfill without waiting for each workflow to next pause.

### Subclassing

`AsWfStore` is subclass-friendly. Override:

- `getActor()` — custom auth source.
- `findRow(handle)` — sharded / multi-tenant lookup. Preserve the `getAndDelete` contract.
- `buildSetPayload(handle, state, opts)` — add custom columns alongside the base payload.
- `applyShadows(payload, state)` — change how shadow values are resolved or coerced.
- `scanShadowFields()` — read shadow specs from a different annotation key.
- `resolvePath(obj, path)` / `coerceShadowValue(raw, spec)` — change traversal or type-coercion rules.

## Cross-links

- [Workflows — Overview](/workflows/)
- [Workflows — Server Authoring](/workflows/server-authoring)
- [Workflows — Form Input](/workflows/form-input)
- [Workflows — Actions](/workflows/actions)
- [Workflows — Context Passing](/workflows/context)
- [Workflows — State Persistence](/workflows/state-persistence)
- [Workflows — Outlets & Resume](/workflows/outlets-resume)
- [@atscript/vue-wf](/api/vue-wf) — client runtime
- atscript.dev — `.as` syntax and serialization
- atscript-db.dev — `AtscriptDbTable`, `@db.*` annotations


---
URL: "ui.atscript.dev/api/ui"
LLMS_URL: "ui.atscript.dev/api/ui.md"
---

# @atscript/ui

Framework-agnostic core for type-driven UIs. Reads compiled Atscript metadata, builds form and table definitions, exposes a pluggable field resolver, validators, value-help, and a battery of pure utilities consumed by every Vue package. No Vue, no React — plain TypeScript.

## Contents

- [Plugin](#plugin)
- [Form types](#form-types)
- [Form factories](#form-factories)
- [Table types](#table-types)
- [Table factory](#table-factory)
- [Field resolver](#field-resolver)
- [Annotation key constants](#annotation-key-constants)
- [Validators](#validators)
- [Path utilities](#path-utilities)
- [Value-help](#value-help)
- [Grid layout](#grid-layout)
- [Decimal helpers](#decimal-helpers)
- [Column helpers](#column-helpers)
- [Error map utilities](#error-map-utilities)
- [Type guards](#type-guards)
- [Misc utilities](#misc-utilities)
- [Client factory](#client-factory)
- [Meta cache](#meta-cache)

## Plugin

`@atscript/ui/plugin` exposes the build-time plugin that registers every static `@ui.*` annotation key. Wire it in `atscript.config.ts`:

```typescript
import uiPlugin from "@atscript/ui/plugin";

export default {
  plugins: [uiPlugin()],
};
```

For dynamic `@ui.fn.*` and `@ui.form.validate`, also register [`@atscript/ui-fns/plugin`](/api/ui-fns).

## Form types

### `FormDef`

Complete form definition produced by `createFormDef(type)`.

```typescript
interface FormDef {
  type: TAtscriptAnnotatedType;
  rootField: FormFieldDef;
  fields: FormFieldDef[];
  flatMap: Map<string, TAtscriptAnnotatedType>;
}
```

### `FormFieldDef`

Thin pointer to one atscript prop. Metadata lives on `prop.metadata` and is resolved on demand.

```typescript
interface FormFieldDef {
  /** Dot-separated path relative to the parent data container. `""` = root. */
  path: string;
  prop: TAtscriptAnnotatedType;
  /** Render-kind: structural names (`array`, `object`, `union`, `tuple`) or primitive override from `@ui.form.type`. */
  type: string;
  /**
   * Optional `@ui.form.type` / `@ui.type` override that lets a structured kind
   * (`array`, `object`, `union`, `tuple`) dispatch to a different built-in
   * renderer in the `:types` map. Reserved for built-in ids — custom
   * components are wired via `@ui.form.component` + `:components`.
   */
  customType?: string;
  phantom: boolean;
  name: string;
  /** True when no `ui.fn.*` keys exist on the prop — perf flag. */
  allStatic: boolean;
}
```

### `FormArrayFieldDef`, `FormObjectFieldDef`, `FormUnionFieldDef`, `FormTupleFieldDef`

Extended field defs for structural kinds.

```typescript
interface FormArrayFieldDef extends FormFieldDef {
  itemType: TAtscriptAnnotatedType;
  itemField: FormFieldDef;
}

interface FormObjectFieldDef extends FormFieldDef {
  objectDef: FormDef;
}

interface FormUnionFieldDef extends FormFieldDef {
  unionVariants: FormUnionVariant[];
}

interface FormTupleFieldDef extends FormFieldDef {
  itemFields: FormFieldDef[];
}
```

### `FormUnionVariant`

One branch of a union.

```typescript
interface FormUnionVariant {
  label: string;
  type: TAtscriptAnnotatedType;
  /** Pre-built FormDef for object variants. */
  def?: FormDef;
  /** Pre-built field def for primitive variants. */
  itemField?: FormFieldDef;
  /** "string" | "number" | "boolean" for primitive variants. */
  designType?: string;
}
```

### `TFormAction`

```typescript
interface TFormAction {
  id: string;
  label: string;
}
```

### `TFormEntryOptions`

A select/radio option — plain string or `{ key, label }` pair.

```typescript
type TFormEntryOptions = { key: string; label: string } | string;
```

## Form factories

### `createFormDef(type, opts?)`

Builds a `FormDef` from an annotated type. Walks props, pre-resolves structural sub-defs, and caches the flat map.

```typescript
function createFormDef(type: TAtscriptAnnotatedType, opts?: { versionColumn?: string }): FormDef;
```

When `opts.versionColumn` is supplied, the matching prop is excluded from the returned `fields[]` (so `AsForm`'s renderer doesn't paint it) but remains in `flatMap` and in the form's underlying data wrapper. This is the contract OCC needs: hide the version input from users while keeping the value in the wire payload so the server can lift it into `$cas`. Pass `meta.versionColumn` directly.

```ts
formDef.value = createFormDef(deserializeAnnotatedType(meta.type), {
  versionColumn: meta.versionColumn,
});
```

See the [Edit forms with optimistic concurrency](/tables/edit-form-occ) pattern guide for the end-to-end flow.

### `buildUnionVariants(type)`

Returns the variant list for a union prop — used internally by `createFormDef` for union fields and union array items.

```typescript
function buildUnionVariants(type: TAtscriptAnnotatedType): FormUnionVariant[];
```

### `createFormData(type, resolver?)`

Creates the wrapped data container `{ value: domainData }` populated from atscript defaults and `@meta.default`. The optional `resolver` (`TFormValueResolver`) overrides the per-field defaulting strategy.

```typescript
function createFormData<T extends TAtscriptAnnotatedType>(
  type: T,
  resolver?: TFormValueResolver,
): { value: TAtscriptDataType<T> };
```

### `createFormValueResolver(data?, context?)`

Returns a value resolver that reads `@meta.default` or `@ui.form.fn.value`, given a scope.

```typescript
type TFormValueResolver = (prop: TAtscriptAnnotatedType, path: string) => unknown;

function createFormValueResolver(
  data?: Record<string, unknown>,
  context?: Record<string, unknown>,
): TFormValueResolver;
```

## Table types

### `TableDef`

Complete table definition built by `createTableDef(meta, type)`.

```typescript
interface TableDef {
  type: TAtscriptAnnotatedType;
  columns: ColumnDef[];
  flatMap: Map<string, TAtscriptAnnotatedType>;
  primaryKeys: string[];
  /** Preferred row identifier for URL/wire addressing. */
  preferredId: string[];
  /** Mirrors `MetaResponse.versionColumn` — name of the OCC version column when the table opts into `@db.column.version`. */
  versionColumn?: string;
  crud: TCrudPermissions;
  canRemove: boolean;
  actions: TableActionsModel;
  searchable: boolean;
  vectorSearchable: boolean;
  searchIndexes: SearchIndexInfo[];
  relations: RelationInfo[];
}
```

`createTableDef` propagates `versionColumn` from the meta envelope and skips the matching entry from `def.columns`, so filter/sort/column-picker dialogs ignore the version column automatically — see [Edit forms with optimistic concurrency](/tables/edit-form-occ).

### `ColumnDef`

A single column definition built from field metadata + annotations.

```typescript
interface ColumnDef {
  path: string;
  label: string;
  type: string;
  component?: string;
  /** Extra sibling leaf paths to fetch when this column is visible — see [Custom Cells](/tables/custom-cells). */
  selectWith?: string[];
  sortable: boolean;
  filterable: boolean;
  nullable: boolean;
  visible: boolean;
  width?: string;
  maxLen?: number;
  order: number;
  options?: { key: string; label: string }[];
  valueHelpInfo?: ValueHelpInfo;
  currencyCode?: string;
  currencyRefField?: string;
  unitCode?: string;
  unitRefField?: string;
  precisionScale?: number;
  /** Synthesised columns (e.g. row-actions) — locked chrome, excluded from `columnNames`. */
  fixed?: boolean;
}
```

### `MetaResponse`

The payload returned by the `moost-db` `/meta` endpoint.

```typescript
interface MetaResponse {
  searchable: boolean;
  vectorSearchable: boolean;
  searchIndexes: SearchIndexInfo[];
  primaryKeys: string[];
  preferredId: string[];
  versionColumn?: string;
  crud: TCrudPermissions;
  actions: TDbActionInfo[];
  relations: RelationInfo[];
  fields: Record<string, FieldMeta>;
  type: TSerializedAnnotatedType;
}

interface FieldMeta {
  sortable: boolean;
  filterable: boolean;
}

interface SearchIndexInfo {
  name: string;
  description?: string;
  type?: "text" | "vector";
}

interface RelationInfo {
  name: string;
  direction: "to" | "from" | "via";
  isArray: boolean;
}
```

**`versionColumn?: string`** — name of the server-managed row version column on OCC-protected tables (declared with `@db.column.version` in your `.as` schema). Absent on tables that don't opt into OCC. Consumer code should pass this through to `createFormDef` so the version field doesn't render as an editable input, while still riding in the form data for the server's `$cas` round-trip. See the [Edit forms with optimistic concurrency](/tables/edit-form-occ) pattern guide for the full flow.

### `TableActionsModel`

Server-declared actions grouped by `level`.

```typescript
interface TableActionsModel {
  table: TDbActionInfo[];
  row: TDbActionInfo[];
  rows: TDbActionInfo[];
  default: {
    table?: TDbActionInfo;
    row?: TDbActionInfo;
    rows?: TDbActionInfo;
  };
}
```

### `TableQueryState`, `SortControl`, `PaginationControl`

```typescript
interface SortControl {
  field: string;
  direction: "asc" | "desc";
}
interface PaginationControl {
  page: number;
  itemsPerPage: number;
}

interface TableQueryState {
  sort?: SortControl[];
  pagination?: PaginationControl;
  search?: string;
  filters?: Record<string, unknown>;
}
```

## Table factory

### `createTableDef(meta, type)`

Builds a `TableDef` from a `MetaResponse` plus the deserialized atscript type.

```typescript
function createTableDef(meta: MetaResponse, type: TAtscriptAnnotatedType): TableDef;
```

See [Annotations Reference](/tables/annotations) for how `@ui.table.*` and `@db.*` annotations populate `ColumnDef`.

## Field resolver

The resolver is pluggable so static-only consumers ship with zero `new Function` overhead and dynamic consumers (`@atscript/ui-fns`) opt in by replacing the global instance.

### `FieldResolver`

```typescript
interface 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;
}

interface TResolveOptions<T> {
  staticAsBoolean?: boolean;
  transform?: (raw: unknown) => T;
}
```

### `StaticFieldResolver`

Class implementing `FieldResolver` with static-only semantics — fn keys are ignored.

### `setResolver(resolver)` / `getResolver()` / `defaultResolver`

```typescript
function setResolver(resolver: FieldResolver): void;
function getResolver(): FieldResolver;
const defaultResolver: StaticFieldResolver;
```

### Standalone helpers

```typescript
function resolveFieldProp<T>(prop, fnKey, staticKey, scope, opts?): T | undefined;
function resolveFormProp<T>(type, fnKey, staticKey, scope, opts?): T | undefined;
function resolveStatic<T>(metadata, staticKey, opts?): T | undefined;
function hasComputedAnnotations(prop: TAtscriptAnnotatedType): boolean;
function getFieldMeta<K extends keyof AtscriptMetadata>(
  prop: TAtscriptAnnotatedType,
  key: K,
): AtscriptMetadata[K] | undefined;
```

`resolveStatic` is exposed so dynamic resolvers (in `ui-fns`) can fall back to it without duplicating logic.

### `parseStaticAttrs(value)` / `resolveAttrs(prop, scope, keys?)`

Resolve `@ui.form.attr` and the dynamic `@ui.form.fn.attr` counterpart into a single record. `keys` overrides the static/fn key pair for `@ui.table.attr` and friends.

```typescript
function parseStaticAttrs(value: unknown): Record<string, unknown> | undefined;
function resolveAttrs(
  prop: TAtscriptAnnotatedType,
  scope: Record<string, unknown>,
  keys?: { staticKey?: string; fnKey?: string },
): Record<string, unknown> | undefined;
```

## Annotation key constants

Every supported annotation has a stringly-typed constant exported from `@atscript/ui` so consumers can build resolvers, mappers, or codegen against named keys instead of magic strings.

### Cross-surface

| Name      | Value       |
| --------- | ----------- |
| `UI_TYPE` | `"ui.type"` |

### Form static keys

`UI_FORM_PLACEHOLDER`, `UI_FORM_HINT`, `UI_FORM_CLASSES`, `UI_FORM_STYLES`, `UI_FORM_AUTOCOMPLETE`, `UI_FORM_DISABLED`, `UI_FORM_OPTIONS`, `UI_FORM_ORDER`, `UI_FORM_TYPE`, `UI_FORM_COMPONENT`, `UI_FORM_HIDDEN`, `UI_FORM_ATTR`, `UI_FORM_GRID_COL_SPAN`, `UI_FORM_GRID_ROW_SPAN`, `UI_FORM_SUBMIT_TEXT`, `UI_FORM_LABEL_SINGULAR`, `UI_FORM_ACTION`, `UI_FORM_PREFIX`, `UI_FORM_PREFIX_REF`, `UI_FORM_PREFIX_ICON`, `UI_FORM_SUFFIX`, `UI_FORM_SUFFIX_REF`, `UI_FORM_SUFFIX_ICON`, `UI_FORM_VALIDATE`.

### Form dynamic keys

`UI_FORM_FN_PREFIX`, `UI_FORM_FN_LABEL`, `UI_FORM_FN_PLACEHOLDER`, `UI_FORM_FN_DESCRIPTION`, `UI_FORM_FN_HINT`, `UI_FORM_FN_HIDDEN`, `UI_FORM_FN_DISABLED`, `UI_FORM_FN_READONLY`, `UI_FORM_FN_OPTIONS`, `UI_FORM_FN_ATTR`, `UI_FORM_FN_VALUE`, `UI_FORM_FN_CLASSES`, `UI_FORM_FN_STYLES`, `UI_FORM_FN_TITLE`, `UI_FORM_FN_SUBMIT_TEXT`, `UI_FORM_FN_SUBMIT_DISABLED`.

### Table static keys

`UI_TABLE_WIDTH`, `UI_TABLE_COMPONENT`, `UI_TABLE_SELECT_WITH`, `UI_TABLE_HIDDEN`, `UI_TABLE_ATTR`, `UI_TABLE_CLASSES`, `UI_TABLE_STYLES`, `UI_TABLE_TYPE`, `UI_TABLE_ORDER`.

### Table dynamic keys

`UI_TABLE_FN_PREFIX`, `UI_TABLE_FN_ATTR`, `UI_TABLE_FN_CLASSES`, `UI_TABLE_FN_STYLES`.

### Dictionary

`UI_DICT_LABEL`, `UI_DICT_DESCR`, `UI_DICT_ATTR`, `UI_DICT_FILTERABLE`, `UI_DICT_SORTABLE`, `UI_DICT_SEARCHABLE`.

### DB-aware

`DB_REL_FK`, `DB_HTTP_PATH`, `DB_AMOUNT_CURRENCY`, `DB_AMOUNT_CURRENCY_REF`, `DB_UNIT`, `DB_UNIT_REF`, `DB_COLUMN_PRECISION`.

### Workflow

`WF_ACTION_WITH_DATA`.

### Meta / expect

`META_LABEL`, `META_ID`, `META_DESCRIPTION`, `META_READONLY`, `META_REQUIRED`, `META_DEFAULT`, `META_SENSITIVE`, `EXPECT_MAX_LENGTH`.

## Validators

### `getFormValidator(def, opts?)`

Returns a reusable validator function bound to a `FormDef`. Built once, called per submit.

```typescript
function getFormValidator(
  def: FormDef,
  opts?: Partial<TValidatorOptions>,
): (callOpts: {
  data: Record<string, unknown>;
  context?: Record<string, unknown>;
}) => Record<string, string>;
```

Returns an errors record keyed by dot-separated field path (empty when valid).

### `createFieldValidator(prop, opts?)`

Field-level validator with internal `Validator` caching. Returns `true` on success or the first error message string.

```typescript
function createFieldValidator(
  prop: TAtscriptAnnotatedType,
  opts?: { rootOnly?: boolean },
): (value: unknown, externalCtx?: { data: unknown; context: unknown }) => true | string;
```

### Default validator plugins

`setDefaultValidatorPlugins(plugins)` installs validator plugins globally; both `getFormValidator` and `createFieldValidator` apply them. `getDefaultValidatorPlugins()` returns the current list. `@atscript/ui-fns` uses this to wire its `uiFnsValidatorPlugin()`.

```typescript
function setDefaultValidatorPlugins(plugins: TValidatorPlugin[]): void;
function getDefaultValidatorPlugins(): TValidatorPlugin[];
```

See the [Validation guide](/forms/validation) for end-to-end usage.

## Path utilities

Form data is wrapped: `{ value: domainData }`. These helpers de-reference the wrapper automatically.

### `getByPath(data, path)` / `setByPath(data, path, value)`

```typescript
function getByPath(obj: Record<string, unknown>, path: string): unknown;
function setByPath(obj: Record<string, unknown>, path: string, value: unknown): void;
```

`path === ""` returns or replaces the entire `obj.value`. Intermediate objects are auto-created on set.

### `detectUnionVariant(value, variants)`

Returns the index of the variant matching `value`. Uses a discriminator when atscript detects one, otherwise probes each variant's validator. Falls back to `0`.

```typescript
function detectUnionVariant(value: unknown, variants: FormUnionVariant[]): number;
```

## Value-help

### `ValueHelpInfo`

Sync probe for a value-help-eligible prop (FK or ref).

```typescript
interface ValueHelpInfo {
  /** HTTP path of the value-help target. */
  url: string;
  /** Field on the target that this FK references. */
  targetField: string;
}
```

### `extractValueHelp(prop)` / `extractLiteralOptions(prop)` / `isPureLiteralUnion(prop)`

```typescript
function extractValueHelp(prop: TAtscriptAnnotatedType): ValueHelpInfo | undefined;
function extractLiteralOptions(
  prop: TAtscriptAnnotatedType,
): { key: string; label: string }[] | undefined;
function isPureLiteralUnion(prop: TAtscriptAnnotatedType): boolean;
```

### `ValueHelpClient`

Thin wrapper over a pre-built `Client` (from `@atscript/db-client`) that runs FK-flavoured searches against the value-help target. Most consumers stick to `resolveValueHelp()` plus their own `Client`; this class formalises the search semantics (full-text `$search` when the target is searchable, `$or`-regex fallback otherwise) so picker UIs don't reimplement them.

```typescript
class ValueHelpClient {
  constructor(client: Client);
  search(resolved: ResolvedValueHelp, opts?: ValueHelpSearchOptions): Promise<ValueHelpResult>;
}

interface ValueHelpSearchOptions {
  /** Search term. Empty / 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>[];
}
```

### `resolveValueHelp(url)` / `resetValueHelpCache()`

Globally caches resolved value-help endpoints by URL so multiple fields pointing at the same target share one `/meta` fetch.

```typescript
function resolveValueHelp(url: string): Promise<ResolvedValueHelp>;
function resetValueHelpCache(): void;

interface ResolvedValueHelp {
  url: string;
  primaryKeys: string[];
  labelField: string;
  descrField: string | undefined;
  attrFields: string[];
  filterableFields: string[];
  sortableFields: string[];
  searchable: boolean;
  targetType: TAtscriptAnnotatedType;
}
```

### `valueHelpDictPaths(resolved)`

Returns the dict-view path set of a resolved value-help target (PKs + label + descr + attr fields). Filter dialogs use it to clamp visible columns to the dictionary subset.

```typescript
function valueHelpDictPaths(resolved: ResolvedValueHelp): Set<string>;
```

See [Forms — References (FK)](/forms/references).

### Option helpers

```typescript
function optKey(opt: TFormEntryOptions): string;
function optLabel(opt: TFormEntryOptions): string;
function parseStaticOptions(value: unknown): TFormEntryOptions[] | undefined;
function resolveOptions(
  prop: TAtscriptAnnotatedType,
  scope: Record<string, unknown>,
): TFormEntryOptions[] | undefined;
```

`resolveOptions` checks `@ui.form.options`, then `@ui.form.fn.options` via the active resolver, then literal-union extraction.

## Grid layout

Framework-agnostic helpers for `@ui.form.grid.colSpan` / `@ui.form.grid.rowSpan`. Each annotation has the shape `{ desktop, narrow? }` — `getFieldMeta(prop, UI_FORM_GRID_COL_SPAN)` returns a `GridSpanArgs`.

```typescript
const DEFAULT_COL_SPAN: number; // 12
const DEFAULT_ROW_SPAN: number; // 1

interface GridSpec {
  col: { desktop: number; narrow: number };
  row: { desktop: number; narrow: number };
}

interface GridSpanArgs {
  desktop: string;
  narrow?: string;
}

/** Accepts `"1"`–`"12"` and the aliases `"full"` (12), `"half"` (6), `"third"` (4). */
function parseColSpan(raw: string | undefined): number | undefined;

/** Accepts numeric strings `"1"`+; rejects `"0"`, negatives, decimals, aliases. */
function parseRowSpan(raw: string | undefined): number | undefined;

/** Compose a resolved spec from already-extracted `colSpan` / `rowSpan` annotation values. */
function resolveGridSpec(
  colSpan: GridSpanArgs | undefined,
  rowSpan: GridSpanArgs | undefined,
): GridSpec;

/** Emit `col-span-X` / `row-span-X` + `as-narrow:` variants for the spec. */
function buildGridClasses(spec: GridSpec): string;
```

See [Grid Layout](/forms/grid-layout).

## Decimal helpers

Framework-agnostic decimal-string formatting and parsing — shared by `@atscript/vue-form` AsDecimal and `@atscript/vue-table` cells. Storage is string-only so DB-precision decimals never bounce through floats.

```typescript
interface CurrencyDisplay {
  decimals: number;
  symbol: string;
}
interface DecimalParts {
  integer: string;
  fraction: string;
  sign: "+" | "-";
}
interface FormatDecimalOptions {
  currency?: string;
  locale?: string;
  /** Number of fractional digits to display. */
  scale?: number;
}

function enforceScale(value: string, scale: number): string;
function formatDecimalForDisplay(value: string, opts?: FormatDecimalOptions): string;
function parseDecimalInput(input: string, opts?: FormatDecimalOptions): string | undefined;
function getCurrencyDecimals(currency: string, locale?: string): number;
function getCurrencyDisplayParts(currency: string, locale?: string): CurrencyDisplay;
function getDecimalSeparator(locale?: string): string;
function getThousandsSeparator(locale?: string): string;
function groupInteger(integer: string, locale?: string): string;
function joinDecimalString(parts: DecimalParts): string;
function splitDecimalString(value: string): DecimalParts;
```

## Column helpers

```typescript
function getVisibleColumns(def: TableDef, hidden?: Set<string>): ColumnDef[];
function getSortableColumns(def: TableDef): ColumnDef[];
function getFilterableColumns(def: TableDef): ColumnDef[];
function getColumn(def: TableDef, path: string): ColumnDef | undefined;
```

## Error map utilities

```typescript
/** Merge any number of partial error maps; falsy values are dropped, later maps win when both have a string. */
function mergeErrorMaps(
  ...maps: Array<Record<string, string | undefined> | undefined>
): Record<string, string>;

/** Yields every ancestor prefix longest-first, including the path itself. `"a.b.c"` → `"a.b.c", "a.b", "a"`. */
function* iteratePathAncestors(path: string): Generator<string>;

/** Build `Map<absolutePath, descendantErrorCount>` so each struct in the tree renders an error-count badge in O(1). */
function buildDescendantErrorCounts(
  errors: Record<string, string | undefined>,
): Map<string, number>;
```

`buildDescendantErrorCounts` powers the count badges on `AsObject` headers.

## Type guards

```typescript
function isArrayField(field: FormFieldDef): field is FormArrayFieldDef;
function isObjectField(field: FormFieldDef): field is FormObjectFieldDef;
function isUnionField(field: FormFieldDef): field is FormUnionFieldDef;
function isTupleField(field: FormFieldDef): field is FormTupleFieldDef;
```

## Misc utilities

```typescript
function asArray<T>(x: T | T[]): T[];

/** `@ui.form.label.singular` for array fields; falls back to `"item"`. */
function resolveSingularLabel(prop: TAtscriptAnnotatedType | undefined): string;

/** Always returns a `MeasurementInfo` — individual fields are `undefined` when their annotation is absent. */
function extractMeasurement(prop: TAtscriptAnnotatedType): MeasurementInfo;

function str(value: unknown): string;
```

`extractMeasurement` reads `@db.amount.currency*` / `@db.unit*` / `@db.column.precision` and returns a structured info record consumed by AsField for currency/unit adornments.

## Client factory

`ClientFactory` is the contract Vue tables and value-help use to build HTTP clients. Override globally to inject auth headers / retries / interceptors.

```typescript
type ClientFactory = (url: string) => Client; // `Client` from `@atscript/db-client`

function setDefaultClientFactory(factory: ClientFactory): void;
function getDefaultClientFactory(): ClientFactory; // never `undefined` — falls back to `(url) => new Client(url)`
function resetDefaultClientFactory(): void;
```

## Meta cache

A single `/meta` fetch per URL is cached across `useTable` instances and `resolveValueHelp` calls. `getMetaEntry` is synchronous — the promises on the entry resolve once the underlying fetch settles.

```typescript
function getMetaEntry(url: string, factory?: ClientFactory): MetaCacheEntry;
function resetMetaCache(): void;

interface MetaCacheEntry {
  client: Client; // from `@atscript/db-client`
  meta: Promise<MetaResponse>;
  type: Promise<TAtscriptAnnotatedType>; // pre-deserialized
  resolved?: Promise<ResolvedValueHelp>; // populated lazily by `resolveValueHelp`
  tableDef?: Promise<TableDef>; // populated lazily by Vue `useTable`
}
```

## Cross-links

- [Forms — Annotations Reference](/forms/annotations)
- [Forms — Validation](/forms/validation)
- [Forms — References (FK)](/forms/references)
- [Tables — Annotations Reference](/tables/annotations)
- [@atscript/ui-fns](/api/ui-fns) — dynamic resolver
- atscript.dev — `.as` syntax and `Validator`


---
URL: "ui.atscript.dev/api/ui-fns"
LLMS_URL: "ui.atscript.dev/api/ui-fns.md"
---

# @atscript/ui-fns

Opt-in dynamic resolver that wires `@ui.form.fn.*`, `@ui.table.fn.*`, and `@ui.form.validate` annotation strings into the global resolver in [`@atscript/ui`](/api/ui). Without this package every `@ui.fn.*` annotation is silently ignored.

## Contents

- [Plugin](#plugin)
- [Installer](#installer)
- [Dynamic resolver](#dynamic-resolver)
- [Compilers](#compilers)
- [Validator plugin](#validator-plugin)
- [Helpers](#helpers)
- [Types](#types)
- [Security](#security)
- [Performance](#performance)

## Plugin

`@atscript/ui-fns/plugin` registers the build-time `@ui.fn.*` annotation keys (form + table) and `@ui.form.validate`. Add it next to `uiPlugin()` in `atscript.config.ts`:

```typescript
import uiPlugin from "@atscript/ui/plugin";
import uiFnsPlugin from "@atscript/ui-fns/plugin";

export default {
  plugins: [uiPlugin(), uiFnsPlugin()],
};
```

## Installer

### `installDynamicResolver()`

One-shot installer. Calls `setResolver(new DynamicFieldResolver())` and `setDefaultValidatorPlugins([uiFnsValidatorPlugin()])`. Invoke once at app startup, before any form/table is built.

```typescript
import { installDynamicResolver } from "@atscript/ui-fns";

installDynamicResolver();
```

After this, every `resolveFieldProp`/`resolveFormProp` call walks the `ui.fn.*` keys first and compiles them on demand. Static annotations still work exactly as in `@atscript/ui`.

## Dynamic resolver

### `DynamicFieldResolver`

Class implementing [`FieldResolver`](/api/ui#field-resolver). Compiles and evaluates `@ui.form.fn.*` / `@ui.table.fn.*` annotation strings on demand, falling back to static resolution via `resolveStatic`.

```typescript
class DynamicFieldResolver implements FieldResolver {
  resolveFieldProp<T>(prop, fnKey, staticKey, scope, opts?): T | undefined;
  resolveFormProp<T>(type, fnKey, staticKey, scope, opts?): T | undefined;
  hasComputedAnnotations(prop: TAtscriptAnnotatedType): boolean;
}
```

`hasComputedAnnotations` returns true when at least one metadata key on the prop starts with `ui.form.fn.` or `ui.table.fn.` — the Vue form/table layers use this as a perf flag to skip per-keystroke re-resolution for fully static fields.

### Attr handling

Keys ending in `attr` (`UI_FORM_FN_ATTR`, `UI_TABLE_FN_ATTR`) store `[{ name, fn }]` arrays instead of a single fn string; the resolver evaluates each entry and merges into a single record.

## Compilers

All three functions return a callable bound to a [`TFnScope`](#types). Compiled functions are cached in an internal `FNPool` keyed by the source string.

### `compileFieldFn(fnStr)`

```typescript
function compileFieldFn<R = unknown>(fnStr: string): (scope: TFnScope) => R;
```

The string is wrapped as:

```javascript
return (<fnStr>)(v, data, context, entry)
```

So a field-level dynamic annotation reads like:

```atscript
@ui.form.fn.hidden '(v, data) => !data.optedIn'
```

### `compileTopFn(fnStr)`

```typescript
function compileTopFn<R = unknown>(fnStr: string): (scope: TFnScope) => R;
```

Form-level wrapping — no leaf value or entry:

```javascript
return (<fnStr>)(data, context)
```

Used for root-interface `@ui.form.fn.title`, `@ui.form.fn.description`,
`@ui.form.fn.submit.text`, `@ui.form.fn.submit.disabled`.

### `compileValidatorFn(fnStr)`

Delegates to `compileFieldFn` with a narrowed return type. Returns `true` for valid, or a string error message for invalid.

```typescript
function compileValidatorFn(fnStr: string): (scope: TFnScope) => boolean | string;
```

## Validator plugin

### `uiFnsValidatorPlugin()`

Returns a [`TValidatorPlugin`](/api/ui#validators) that walks `@ui.form.validate` annotations on a field, compiles each, and reports the first non-`true` result as the field's validation error.

```typescript
function uiFnsValidatorPlugin(): TValidatorPlugin;
```

The plugin is auto-registered by `installDynamicResolver()`. Re-export and add it manually if you need a fine-grained Validator instance.

```atscript
@ui.form.validate '(v, data) => v === data.passwordConfirm || "Passwords do not match"'
password: string
```

See [Validation](/forms/validation) for end-to-end usage.

## Helpers

### `buildFieldEntry(prop, baseScope, path, opts?)`

Implements the dual-scope pattern used by the resolver and the validator plugin:

1. Resolve constraints (`disabled`, `hidden`, `readonly`) from `baseScope`.
2. Assemble a `TFieldEvaluated` entry object.
3. Build the full scope `{ ...baseScope, entry }`.
4. Resolve `options` against the full scope (so option expressions can read the entry's `type` / `disabled`).

```typescript
function buildFieldEntry(
  prop: TAtscriptAnnotatedType,
  baseScope: TFnScope,
  path: string,
  opts?: TBuildFieldEntryOpts,
): TFnScope;

type TBuildFieldEntryOpts = Partial<
  Pick<
    TFieldEvaluated,
    "name" | "type" | "component" | "optional" | "disabled" | "hidden" | "readonly"
  >
>;
```

The returned scope is the full evaluation scope (with `entry` populated). Use it when invoking other compiled fns that depend on resolved field state.

## Types

### `TFnScope`

The eval scope passed to every compiled function. Properties become positional arguments inside the wrapping shim:

```typescript
interface TFnScope<V = unknown, D = Record<string, unknown>, C = Record<string, unknown>> {
  /** Current field value (leaf). Undefined for form-level fns. */
  v?: V;
  /** Whole form's domain data. */
  data: D;
  /** Caller-supplied formContext. */
  context: C;
  /** Resolved field meta (label, type, disabled, hidden, options, …). */
  entry?: TFieldEvaluated;
  /** Action name when the fn is evaluated during action dispatch. */
  action?: string;
}
```

### `TComputed<T>`

Convenience union for "static value or scope-bound function".

```typescript
type TComputed<T> = T | ((scope: TFnScope) => T);
```

### `TFieldEvaluated`

Resolved per-field snapshot passed to validators and computed annotations as `entry`.

```typescript
interface TFieldEvaluated {
  field: string;
  type: string;
  component?: string;
  name: string;
  disabled?: boolean;
  optional?: boolean;
  hidden?: boolean;
  readonly?: boolean;
  options?: TFormEntryOptions[];
}
```

### `TValidatorContext`

Per-call context passed via `validator.validate(value, safe, context)` and unpacked by `uiFnsValidatorPlugin`.

```typescript
interface TValidatorContext {
  data: Record<string, unknown>;
  context: Record<string, unknown>;
}
```

### `TBuildFieldEntryOpts`

Defined above next to [`buildFieldEntry`](#helpers).

## Security

`compileFieldFn`, `compileTopFn`, and `compileValidatorFn` all use `new Function` under the hood (via `@prostojs/deserialize-fn`'s `FNPool`). The compiled function runs in the host JS realm — it sees `globalThis`, can throw, can loop forever.

This is **only safe for compile-time-validated schemas you author or trust**. Never accept user-authored fn strings from the network and feed them through this resolver. The atscript compiler validates expression syntax at build time so a typo fails CI rather than at runtime.

Browser deployments with strict CSP require `unsafe-eval`.

## Performance

- Every fn string is compiled once and cached in `FNPool` for the lifetime of the process. Identical strings on different fields share the same compiled function.
- `hasComputedAnnotations` short-circuits Vue's per-keystroke re-resolution: fields where every annotation is static skip the resolver loop entirely. The `FormFieldDef.allStatic` flag mirrors this on the form side.
- `buildFieldEntry` resolves constraints once, then reuses the entry across `options` and validator evaluation in the same submit pass.

## Cross-links

- [Forms — Dynamic Fields](/forms/dynamic-fields)
- [Forms — Validation](/forms/validation)
- [@atscript/ui — FieldResolver](/api/ui#field-resolver)
- [@atscript/ui — Validators](/api/ui#validators)


---
URL: "ui.atscript.dev/api/ui-styles"
LLMS_URL: "ui.atscript.dev/api/ui-styles.md"
---

# @atscript/ui-styles

The vunor-powered UnoCSS preset, the safelist extractor that drives our as-component class collection, the `as-*` shortcut tree, the baked-icon collection, and the `unplugin-vue-components` resolver. Spread `asPresetVunor()` into UnoCSS, register `AsResolver()` in Vite, and every `as-*` class used by `@atscript/vue-form` / `@atscript/vue-table` / `@atscript/vue-wf` resolves correctly.

## Contents

- [Preset](#preset)
- [Extractor](#extractor)
- [Base UnoCSS config](#base-unocss-config)
- [Shortcuts](#shortcuts)
- [Component class maps](#component-class-maps)
- [Icons](#icons)
- [vunor re-exports](#vunor-re-exports)
- [Vite subpath — AsResolver](#vite-subpath-asresolver)
- [Pre-built CSS subpaths](#pre-built-css-subpaths)

## Preset

### `asPresetVunor(options?)`

Returns an array of UnoCSS presets + rules + safelist entries spreadable into `unocss.config.ts`. Bundles vunor (palette / scope / layer / surface / c8 / i8), the `as-*` shortcut tree, the baked icon collection (`i-as-*`), and the safelist extractor.

```typescript
// AsBaseUnoConfigOptions IS vunor's presetVunor option type — every field
// (`baseRadius`, `palette`, `fingertip`, `typography`, `animation`, …) is
// accepted flat at the top level. Omitted fields fall back to the baked
// `defaultAsVunorOptions`. `palette.colors` and `fingertip` shallow-merge
// per-key so you can override one entry without redeclaring the whole map.
type AsVunorPresetOptions = NonNullable<Parameters<typeof presetVunor>[0]>;
interface AsBaseUnoConfigOptions extends AsVunorPresetOptions {}

interface AsPresetVunorOptions extends AsBaseUnoConfigOptions {
  /** Drop a kebab-case component's classes from the safelist when the consumer has replaced it.
   *  Typed against the generated `AsComponentName` union — autocompletes, typos fail the build. */
  excludeComponents?: AsComponentName[];
  /** Replace built-in `i-as-<name>` icons with custom SVG strings. Unknown keys ignored. */
  iconOverrides?: Record<string, string>;
}

function asPresetVunor(options?: AsPresetVunorOptions): Preset[];

/** Baked-in vunor theme atscript-ui has shipped since day one. Exported so
 *  consumers can read or extend it (e.g. spread + tweak one field). */
const defaultAsVunorOptions: AsVunorPresetOptions;
```

```typescript
import { defineConfig } from "unocss";
import { asPresetVunor } from "@atscript/ui-styles";

export default defineConfig({
  presets: [
    ...asPresetVunor({
      baseRadius: "0.5rem",
      palette: { colors: { primary: "#a855f7" } }, // keeps grey/neutral/error defaults
      fingertip: { m: "36px" }, // keeps xs/s/l/xl defaults
      excludeComponents: ["as-input"],
    }),
  ],
});
```

See [Styling — Installation](/styling/installation) and [Theme & Palette](/styling/theme).

## Extractor

### `createAsExtractor(opts)`

Builds the UnoCSS source-code extractor that pre-seeds the safelist with every class our components reference. Used internally by `asPresetVunor`; expose your own for advanced setups (e.g. running the safelist build inside a different bundler).

```typescript
interface AsExtractorOptions {
  /** Kebab-case component names to drop from the safelist. */
  excludeComponents?: AsComponentName[];
}

function createAsExtractor(opts?: AsExtractorOptions): {
  name: string;
  extract(ctx: { code: string; id?: string }): Set<string>;
};
```

## Base UnoCSS config

### `createAsBaseUnoConfig(opts?)`

Returns the minimal UnoCSS base config (vunor + presets + safelist) the demo apps use. Most consumers spread `asPresetVunor()` directly; reach for `createAsBaseUnoConfig` only when you want the entire opinionated config object pre-assembled.

```typescript
function createAsBaseUnoConfig(opts?: AsBaseUnoConfigOptions): UserConfig;
```

## Shortcuts

The shortcut tree is split per package so consumers can opt in. Each export is a `TVunorShortcut[]` ready to spread into a vunor config.

```typescript
import {
  commonShortcuts,
  formShortcuts,
  tableShortcuts,
  wfShortcuts,
  aoothShortcuts,
  allShortcuts,
} from "@atscript/ui-styles";

const commonShortcuts: TVunorShortcut[];
const formShortcuts: TVunorShortcut[];
const tableShortcuts: TVunorShortcut[];
const wfShortcuts: TVunorShortcut[];
const aoothShortcuts: TVunorShortcut[];

const allShortcuts: TVunorShortcut[]; // mergeVunorShortcuts of the five above
```

`asPresetVunor()` already injects `allShortcuts`. Spread individual shortcut sets only when assembling a custom preset for a subset of the libraries.

See [The as-\* Shortcut System](/styling/shortcuts).

## Component class maps

Generated at build time by walking every `as-*.vue` template. Drives the safelist extractor and the optional component-exclusion knob.

```typescript
/** Union of every published kebab-case component name — generated from the component set; powers `excludeComponents` autocomplete (typos fail the build). */
type AsComponentName =
  | "as-action"
  | "as-array"
  | /* …every published component… */ "as-window-table";

/** Map: kebab-case component name → list of class names it references (own classes only). */
const componentClasses: Record<string, readonly string[]>;

/** Map: kebab-case component name → tracked components it renders or lazy-mounts.
 *  The extractor expands these recursively; each entry is independently veto-able
 *  via `excludeComponents`. See the Bundle Optimization guide. */
const componentCompanions: Record<string, readonly string[]>;

/** Map: kebab-case component name → owning package ("form" | "table" | "wf"). */
const componentPackages: Record<string, "form" | "table" | "wf">;

/** Union of every class referenced by the given kebab-case component names, companions included.
 *  Names in `exclude` contribute nothing and are not traversed through. */
function getComponentClasses(names: readonly string[], exclude?: ReadonlySet<string>): string[];

/** Same as `getComponentClasses`, but takes helper-function names and expands them via `helperAliases`. */
function getHelperClasses(...helpers: string[]): string[];

/**
 * Map: default-bundle helper function name → list of kebab-case components it wires up.
 * Keys are `createDefaultCellTypes`, `createDefaultControls`, `createDefaultTypes`.
 * A call to `createDefaultControls()` in your source pulls in the classes for every default
 * component it returns.
 */
const helperAliases: Record<string, readonly string[]>;
```

## Icons

### `bakedIcons`

```typescript
const bakedIcons: Record<string, string>;
```

Map of semantic icon name → Iconify id or inline SVG string. Baked at publish time so the preset works offline and inside CSP-restricted environments. Override individual entries via `asPresetVunor({ iconOverrides })`.

Built-in semantic names include: `search`, `close`, `plus`, `chevron-{up,down,left,right}`, `chevron-double-*`, `arrow-{up,down}`, `grip`, `filter`, `filter-ops`, `sort-asc`, `value-help`, `sun`, `moon`, `check`, `check-square`, `sorters`, `refresh`, `columns`, `eye`, `eye-off`, `eye-slash`, `star`, `star-filled`, `pin`, `pin-filled`, `settings`, `ellipsis`, `menu`, `trash`, `loading`, `warning`, `field-empty`, `field-fill`.

Reference an icon in your own shortcut with `i-as-<name>`:

```typescript
defineShortcuts({
  "my-button": "i-as-plus c8-filled scope-primary",
});
```

See [Styling — Icons](/styling/icons).

## vunor re-exports

For convenience, the package re-exports the vunor shortcut authoring helpers and the `TVunorShortcut` type so consumers don't need a second import.

```typescript
import { defineShortcuts, mergeVunorShortcuts, toUnoShortcut } from "@atscript/ui-styles";
import type { TVunorShortcut } from "@atscript/ui-styles";

function defineShortcuts(map: Record<string, string>): TVunorShortcut[];
function mergeVunorShortcuts(sets: TVunorShortcut[][]): TVunorShortcut[];
function toUnoShortcut(shortcut: TVunorShortcut): readonly [string | RegExp, string];
```

## Vite subpath — AsResolver

### `@atscript/ui-styles/vite`

```typescript
import { AsResolver } from "@atscript/ui-styles/vite";
import Components from "unplugin-vue-components/vite";

export default {
  plugins: [
    Components({
      resolvers: [AsResolver()],
    }),
  ],
};
```

`AsResolver()` returns a `ComponentResolverObject` that auto-imports the **Tier 1 primary components** — `AsField`, `AsFilters`, `AsForm`, `AsIterator`, `AsPresetPicker`, `AsTable`, `AsTableActions`, `AsTableRoot`, `AsWfForm`, `AsWindowTable` — on first use in a template. (Authoritative source: `primaryComponents` in `packages/ui-styles/src/generated/component-classes.ts`.)

Tier-2 defaults (`AsInput`, `AsFilterDialog`, …) are not auto-resolved — users import them explicitly when composing custom defaults. Composables (`useTable`, …) are never handled by `unplugin-vue-components`.

```typescript
function AsResolver(): ComponentResolverObject;
```

## Pre-built CSS subpaths

For apps that don't run UnoCSS at all, the package ships pre-baked CSS bundles. Importing one of these subpaths for side-effect injects every class our components need.

```typescript
import "@atscript/ui-styles/css"; // alias for /css/all
import "@atscript/ui-styles/css/all"; // form + table + wf + aooth + common
import "@atscript/ui-styles/css/form"; // form only
import "@atscript/ui-styles/css/table"; // table only
import "@atscript/ui-styles/css/wf"; // wf only
import "@atscript/ui-styles/css/aooth"; // @atscript/vue-aooth components only
```

Caveat: pre-built CSS skips theme tuning. Use `asPresetVunor()` if you want to change the palette, base radius, fingertip ladder, or icon set.

See [Pre-built CSS](/styling/prebuilt-css).

## Cross-links

- [Styling — Overview](/styling/)
- [Styling — Installation](/styling/installation)
- [Styling — Theme & Palette](/styling/theme)
- [Styling — Icons](/styling/icons)
- [Styling — The as-\* Shortcut System](/styling/shortcuts)
- [Styling — Pre-built CSS](/styling/prebuilt-css)
- [Guide — Bundle Optimization](/guide/bundle-optimization)
- vunor — internal shortcuts engine atscript-ui composes against (`vunor`, `vunor/theme`, `vunor/utils`)


---
URL: "ui.atscript.dev/api/ui-table"
LLMS_URL: "ui.atscript.dev/api/ui-table.md"
---

# @atscript/ui-table

Framework-agnostic table model. Filter conditions, filter→Uniquery conversion, sorter/filter merging, URL state bridging, preset wire types, window-mode pagination math, column widths, selection helpers, and the abstract `TableStateMethods` / `TableStateData` contracts that `@atscript/vue-table` fulfills. Zero Vue dependency — React or Svelte adapters reuse everything here.

## Contents

- [Filter model](#filter-model)
- [Filter input format](#filter-input-format)
- [Filters and Uniquery](#filters-and-uniquery)
- [Date shortcuts](#date-shortcuts)
- [Presets — wire types](#presets-wire-types)
- [Presets — application types](#presets-application-types)
- [Presets — id helpers](#presets-id-helpers)
- [Presets — system presets](#presets-system-presets)
- [Presets — dirty detection](#presets-dirty-detection)
- [Presets — local draft](#presets-local-draft)
- [Presets — HTTP clients](#presets-http-clients)
- [Query builder](#query-builder)
- [URL query bridge](#url-query-bridge)
- [Selection](#selection)
- [State contracts](#state-contracts)
- [Window mode helpers](#window-mode-helpers)
- [Column widths](#column-widths)
- [Utilities](#utilities)

## Filter model

### `FilterConditionType`

Canonical operator names used in filter conditions. `bw` ("between") is the range operator — there is no separate `between` alias.

```typescript
type FilterConditionType =
  | "eq"
  | "ne"
  | "gt"
  | "gte"
  | "lt"
  | "lte"
  | "contains"
  | "starts"
  | "ends"
  | "bw"
  | "null"
  | "notNull"
  | "regex";
```

### `FilterCondition`

A single per-field condition. Operands live in a positional array — most operators read `value[0]`; `bw` reads `value[0]` (low) + `value[1]` (high); `null` / `notNull` ignore `value`.

```typescript
interface FilterCondition {
  type: FilterConditionType;
  value: (string | number | boolean)[];
}
```

### `FieldFilters`

Per-field map of applied conditions. The framework treats absence and empty array as equivalent.

```typescript
type FieldFilters = Record<string, FilterCondition[]>;
```

### Condition helpers

```typescript
function isFilled(cond: FilterCondition): boolean;
function hasSecondValue(type: FilterConditionType): boolean; // `true` only for `"bw"`
function isSimpleEq(cond: FilterCondition): boolean;
function conditionLabel(type: FilterConditionType): string;
function filledFilterCount(filters: FieldFilters): number;
function filterTokenLabel(
  path: string,
  conditions: FilterCondition[],
  columnLabel?: string,
): string;

const NULL_OPS: ReadonlySet<FilterConditionType>; // { "null", "notNull" }
```

`isFilled` returns true when the condition has at least one operand bound (or uses a `NULL_OPS` operator). `filledFilterCount` is used by toolbar badges. `filterTokenLabel` summarises a field's filled conditions into a chip-friendly token.

### Conditions per type

```typescript
type ColumnFilterType = "text" | "number" | "boolean" | "date" | "enum" | "ref";

/** Drops `"null"` / `"notNull"` when `nullable === false`. */
function conditionsForType(
  type: ColumnFilterType,
  nullable?: boolean,
): readonly FilterConditionType[];

/** Map a `ColumnDef.type` string to its filter-type bucket. */
function columnFilterType(columnType: string): ColumnFilterType;
```

`conditionsForType` returns the operator set the filter picker should offer for a given column type.

## Filter input format

Tools for parsing and formatting filter values typed by the user.

```typescript
/** Parses operator shorthand (`>100`, `*foo*`, `lo...hi`, `<empty>`, `!<empty>`, `/regex/`). */
function parseFilterInput(
  raw: string,
  columnType: ColumnFilterType,
  nullable?: boolean,
): FilterCondition | undefined;

/** Format a condition back into the same operator-shorthand string. Round-trips with `parseFilterInput`. */
function formatFilterCondition(cond: FilterCondition): string;

/** Default operator for a fresh filter picker: `"contains"` for `text`/`enum`/`ref`, else `"eq"`. */
function defaultCondition(columnType: ColumnFilterType): FilterConditionType;

function escapeRegex(value: string): string;
function unescapeRegex(value: string): string;
```

See [Filtering](/tables/filtering).

## Filters and Uniquery

`filtersToUniqueryFilter` produces a `@uniqu/core`-compatible filter object the server consumes; `uniqueryFilterToFieldFilters` rebuilds `FieldFilters` from a stored Uniquery object (used when applying a preset or URL state).

```typescript
function filtersToUniqueryFilter(
  filters: FieldFilters,
  columns: ColumnDef[],
): Record<string, unknown> | undefined;

function uniqueryFilterToFieldFilters(
  filter: Record<string, unknown> | undefined,
  columns: ColumnDef[],
): FieldFilters;
```

## Date shortcuts

Pre-built date-range presets used by the date filter picker. Each shortcut produces an ISO date pair (`YYYY-MM-DD`) intended for a `bw` (between) condition.

```typescript
interface DateShortcut {
  label: string;
  dates: [start: string, end: string];
}

/** Returns the canonical shortcut list relative to `now` (defaults to current date). */
function dateShortcuts(now?: Date): DateShortcut[];
// → Last 7 Days, Last 30 Days, Month to Date, Last 90 Days, Last 6 Months,
//   Last 12 Months, Year to Date
```

## Presets — wire types

### `PresetSnapshot`

In-memory snapshot of table state for preset persistence. Dict-shaped — aspects mirror the runtime state, not the wire format. The wire form (entries-arrays for atscript validation) is `PresetSnapshotWire`. Each top-level key is opt-in: a key's presence claims that aspect; absent keys are left untouched on apply.

```typescript
interface PresetSnapshot {
  columns?: {
    columnNames: string[];
    /** Override-only diff against column defaults — never serialise the default itself. */
    columnWidths?: Record<string, string>;
  };
  /** Displayed filter field paths (the visible-input list). */
  filters?: string[];
  /** Applied filter conditions keyed by field path. */
  filterOps?: FieldFilters;
  sorters?: SortControl[];
  itemsPerPage?: number;
}
```

### `PresetSnapshotWire`, `PresetColumnWidthEntry`, `PresetFilterOpEntry`, `PresetSorterEntry`

Persisted wire form (what hits the DB / URL). Matches the `.as` model in [`@atscript/moost-ui-presets`](/api/moost-ui-presets).

### `PresetAspect`, `AspectMask`, `PRESET_ASPECTS`, `derivePresetAspects`

```typescript
type PresetAspect = "columns" | "filters" | "filterOps" | "sorters" | "itemsPerPage";
type AspectMask = ReadonlySet<PresetAspect> | readonly PresetAspect[];

const PRESET_ASPECTS: readonly PresetAspect[];

function derivePresetAspects(snapshot: PresetSnapshot | PresetSnapshotWire): PresetAspect[];
```

`derivePresetAspects(snapshot)` returns the list of aspects actually present on a snapshot — used by the controller when stamping `aspects[]` on a preset row.

### `toWireSnapshot(snapshot)` / `fromWireSnapshot(wire)`

```typescript
function toWireSnapshot(snapshot: PresetSnapshot): PresetSnapshotWire;
function fromWireSnapshot(wire: PresetSnapshotWire): PresetSnapshot;
```

Bidirectional bridge between the application shape (sets, ordered arrays, etc.) and the JSON wire shape.

## Presets — application types

```typescript
interface AsPresetEntryRow {
  id: string;
  type: "preset" | "userConf" | "appConf";
  app: string;
  tableKey?: string;
  user: string;
  userLabel?: string;
  public?: boolean;
  label?: string;
  publicLabel?: string;
  aspects?: PresetAspect[];
  data: AsPresetEntryData;
  createdAt: number;
  updatedAt: number;
}

type AsPresetEntryData = PresetData | UserConfData | AppConfData;

interface PresetData {
  label: string;
  content?: PresetSnapshotWire;
}
interface UserConfData {
  defaultPresetId?: string;
  favPresetIds?: string[];
}
interface AppConfData {
  appearance?: "system" | "light" | "dark";
  language?: string;
  timezone?: string;
  density?: "compact" | "cozy" | "comfortable";
  dateFormat?: "iso" | "us" | "eu";
  firstDayOfWeek?: 0 | 1 | 6;
  customJson?: string;
}

interface PresetCapabilities {
  /** Whether the current user may set `public: true` on presets in this scope. */
  canPublish: boolean;
  /** Per-`(app, tableKey, user)` preset cap. */
  presetLimit: number;
  /** Server-known opaque identity for the current user. */
  userId: string;
}

interface PresetLimitReachedBody {
  code: "preset_limit_reached";
  limit: number;
  count: number;
}

type AsPresetsErrorCode =
  | "preset_limit_reached"
  | "reserved_id"
  | "public_name_conflict"
  | "missing_scope"
  | "missing_id"
  | "invalid_type"
  | "type_immutable"
  | "identity_immutable"
  | "preset_not_found"
  | "publish_forbidden"
  | "action_unsupported";
```

## Presets — id helpers

```typescript
const SYSTEM_PRESET_PREFIX: "sys:";
const USER_CONF_PREFIX: "uc:";
const APP_CONF_PREFIX: "ac:";
const RESERVED_ID_PREFIXES: readonly string[];
const STANDARD_PRESET_ID: "sys:standard";

function userConfId(user: string, app: string, tableKey: string): string;
function appConfId(user: string, app: string): string;
function isSystemPresetId(id: string): boolean;
function normaliseSystemPresetId(id: string): string;
```

User-authored preset ids must NOT start with any prefix in `RESERVED_ID_PREFIXES` — the controller rejects writes that try.

## Presets — system presets

System presets are read-only, framework-defined snapshots like "Standard view". Apps may also register custom synthetic presets via `useTable({ preset.systemPresets })`.

```typescript
interface SystemPreset {
  id: string; // "sys:standard" or "sys:<custom>"
  label: string;
  snapshot: PresetSnapshot;
  aspects: PresetAspect[];
}

interface SystemPresetInput {
  id: string;
  label: string;
  snapshot: Partial<PresetSnapshot>;
}

function resolveSystemPresets(
  inputs?: SystemPresetInput[],
  defaults?: { columnNames?: string[] },
): SystemPreset[];
```

`resolveSystemPresets` always emits a `sys:standard` entry as item 0 and follows it with the consumer-supplied list.

## Presets — dirty detection

```typescript
function stableStringify(value: unknown): string;
function isDirtyAgainst(
  current: PresetSnapshot,
  claimed: AspectMask,
  baseline: PresetSnapshot,
): boolean;
```

`stableStringify` produces deterministic JSON (sorted keys) so a snapshot's hash is stable across reorders. `isDirtyAgainst` returns true when at least one claimed aspect differs from baseline.

## Presets — local draft

Opt-in localStorage overlay that captures the user's in-flight tweaks. Persists `columns`/`filters`/`sorters` and optionally `itemsPerPage`; `filterOps`, `searchTerm`, and pagination are never persisted.

```typescript
interface PresetDraft {
  presetId: string;
  columns?: PresetSnapshot["columns"];
  filters?: PresetSnapshot["filters"];
  sorters?: PresetSnapshot["sorters"];
  itemsPerPage?: number;
}

type DraftPersistedAspect = "columns" | "filters" | "sorters" | "itemsPerPage";
const DRAFT_PERSISTED_ASPECTS: readonly DraftPersistedAspect[];

function serializeDraft(draft: PresetDraft): string;
function deserializeDraft(raw: string): PresetDraft | undefined;
function isEmptyDraft(draft: PresetDraft): boolean;
function draftMatchesPreset(draft: PresetDraft, snapshot: PresetSnapshot): boolean;
```

## Presets — HTTP clients

### `PresetsClient`

Framework-agnostic wrapper over `@atscript/db-client`'s `Client` for the [`AsPresetsController`](/api/moost-ui-presets) endpoint. Owns preset CRUD, userConf upserts, and capability probing. Stateless — every method is a fresh request.

```typescript
interface PresetsClientConfig {
  /** Controller mount URL, e.g. `"/db/_presets"`. */
  url: string;
  app: string;
  tableKey: string;
  /** Pre-built `Client` (auth-configured by the host). Wins over `clientFactory`. */
  client?: Client;
  /** Builds a `Client` for the given URL. Defaults to `getDefaultClientFactory()`. */
  clientFactory?: (url: string) => Client;
  /** Fetch impl for the `GET /capabilities` side-channel. Defaults to `globalThis.fetch`. */
  fetch?: typeof globalThis.fetch;
}

interface PresetsListResult {
  presets: AsPresetEntryRow[];
  /** type='userConf' row for this `(user, app, tableKey)`, or null. */
  userConf: AsPresetEntryRow | null;
  /** `null` when the capabilities load failed; `undefined` when the call skipped capabilities. */
  capabilities: PresetCapabilities | null | undefined;
  /** True when the controller responded 401/403 — UI silently hides. */
  denied: boolean;
}

interface PresetsSaveAsOptions {
  public?: boolean;
}

interface PresetsSaveResult {
  id: string;
}

class PresetsClient {
  constructor(config: PresetsClientConfig);

  /** Lists owned + public preset rows AND the user's userConf row. `{ capabilities: false }` skips the capabilities fetch. */
  list(opts?: { capabilities?: boolean }): Promise<PresetsListResult>;

  /** `GET ${url}/capabilities?app=...&tableKey=...` — out-of-band of the CRUD plumbing. */
  loadCapabilities(): Promise<PresetCapabilities>;

  /** Overwrite the active preset's content (label preserved). */
  savePreset(id: string, label: string, snapshot: PresetSnapshot): Promise<void>;

  /** Create a new preset row. Server stamps `user`, generates `id`, derives `aspects`. */
  savePresetAs(
    label: string,
    snapshot: PresetSnapshot,
    opts?: PresetsSaveAsOptions,
  ): Promise<PresetsSaveResult>;

  renamePreset(id: string, label: string): Promise<void>;
  setPublic(id: string, value: boolean): Promise<void>;
  deletePreset(id: string): Promise<void>;

  /** Upsert the userConf row keyed on `${USER_CONF_PREFIX}${user}:${app}:${tableKey}`. */
  upsertUserConf(
    existing: AsPresetEntryRow | null,
    patch: Partial<UserConfData>,
    user?: string,
  ): Promise<void>;
}
```

### `PresetsHttpError` / `isAuthError`

```typescript
class PresetsHttpError extends Error {
  readonly status: number;
  constructor(status: number, message: string);
}

function isAuthError(err: unknown): boolean; // true for HTTP 401/403 on `ClientError` or `PresetsHttpError`
```

### `AppPrefsClient`

Loads the `appConf` row for `(user, app)` — app-wide preferences like density, locale, appearance. Independent of any table; devs may use this standalone.

```typescript
interface AppPrefsClientConfig {
  /** Same controller URL the presets table is mounted on. */
  url: string;
  app: string;
  client?: Client;
  clientFactory?: (url: string) => Client;
}

interface AppPrefsLoadResult {
  /** Full row (server-stamped id, user, timestamps), or `null`. */
  row: AsPresetEntryRow | null;
  /** Convenience accessor for `row.data`, or `null`. */
  prefs: AppConfData | null;
  /** True when the controller responded 401/403. */
  denied: boolean;
}

class AppPrefsClient {
  constructor(config: AppPrefsClientConfig);
  load(): Promise<AppPrefsLoadResult>;
  /** Upsert the appConf row. `existing` comes from a prior `load()` so the verb is correct. Returns the row id on success. */
  save(
    existing: AsPresetEntryRow | null,
    patch: Partial<AppConfData>,
    user?: string,
  ): Promise<string | null>;
}
```

See [Server-Side Presets](/tables/server-presets).

## Query builder

### `buildTableQuery(opts)`

Pure function that translates table UI state into a `Uniquery` request. Merges user filters with force filters, prepends force sorters, projects `$select`, applies search and the `$actions` flag.

```typescript
interface BuildTableQueryOptions {
  /** Paths of visible columns — emitted as `controls.$select`. */
  visibleColumnPaths: string[];
  /** User-configured sorters. */
  sorters: SortControl[];
  /** Always-applied sorters (prepended before user sorters). */
  forceSorters?: SortControl[];
  /** User-configured field filters. */
  filters: FieldFilters;
  /** Always-applied Uniquery filter (AND'd with user filters). */
  forceFilters?: FilterExpr;
  /** Full-text search term. */
  search?: string;
  /** Search index name for `$search:<index>`. */
  searchIndex?: string;
  /** Set `controls.$actions = true` to receive per-row `$actions: string[]`. */
  includeActions?: boolean;
}

function buildTableQuery(opts: BuildTableQueryOptions): Uniquery; // `Uniquery` from `@uniqu/core`
```

### `mergeSorters` / `mergeFilters`

Used by `buildTableQuery` to combine force + user controls; safe to call directly when composing presets / URL state.

```typescript
function mergeSorters(force: SortControl[], user: SortControl[]): SortControl[];

/** AND-merge two `FilterExpr` trees, producing a wire shape that survives the Uniquery parser collapse. */
function mergeFilters(force?: FilterExpr, user?: FilterExpr): FilterExpr | undefined;
```

## URL query bridge

Two-way bridge between table state and URL query strings. Per-aspect gates (`filters` / `sorters` / `search` / `pagination`) are honoured symmetrically by encoder and decoder — pass the same `sync` config to both so the round-trip matches.

```typescript
interface UrlQueryStateLike {
  filters: FieldFilters;
  sorters: SortControl[];
  /** 1-based page number; `1` is the default and is omitted from the URL. */
  page?: number;
  /** Per-page size; omitted from the URL when equal to `defaultItemsPerPage`. */
  itemsPerPage?: number;
  /** Full-text search term; omitted when empty. */
  searchTerm?: string;
}

interface UrlQueryStateSnapshot {
  filters: FieldFilters;
  sorters: SortControl[];
  /** Raw `$skip` offset when present (no page math — recipients divide by their own `itemsPerPage`). */
  skip?: number;
  searchTerm: string;
}

interface UrlQuerySync {
  /** `true` / `undefined` (default): all filters. `false` / `[]`: no filters in URL. `string[]`: allowlist of field paths. */
  filters?: boolean | string[];
  /** Same `boolean | string[]` semantics; allowlist matches `SortControl.field`. */
  sorters?: boolean | string[];
  /** Round-trip `searchTerm` as `$search`. Default `true`. */
  search?: boolean;
  /** Round-trip pagination (`$skip`). Default `true`. */
  pagination?: boolean;
}

interface UrlQueryDefaults {
  /** Consumer's `:limit` prop. Used to compute `$skip` and to suppress `$limit` writes. */
  defaultItemsPerPage: number;
  /** Per-aspect sync gates. Omitted = full sync. */
  sync?: UrlQuerySync;
}

interface UrlQueryParseOptions {
  /** Field paths the table knows about. Conditions on fields outside this set are silently dropped. */
  knownFields?: Iterable<string>;
  /** Per-aspect sync gates — must match the encoder's config. */
  sync?: UrlQuerySync;
}

/** Tri-state resolution of a per-aspect gate: `"all"` (pass-through), `"none"` (off), or an allowlist Set. */
type AspectGate = "all" | "none" | Set<string>;

function resolveAspectGate(value: boolean | string[] | undefined): AspectGate;

/** Returns the URL query string (no leading `?`). Returns `""` for the default view. */
function stateToUrlQueryString(state: UrlQueryStateLike, defaults: UrlQueryDefaults): string;

/** Robust by design — schema drift never breaks the recipient's view. */
function urlQueryStringToState(
  urlString: string,
  opts?: UrlQueryParseOptions,
): UrlQueryStateSnapshot;
```

See [URL State](/tables/url-state).

## Selection

```typescript
type SelectionMode = "none" | "single" | "multi";

function togglePk(set: unknown[], pk: unknown): unknown[];
function trimSelection(set: unknown[], pks: Iterable<unknown>): unknown[];
function rowsToPks(
  rows: Record<string, unknown>[],
  rowValueFn: (row: Record<string, unknown>) => unknown,
): unknown[];
```

`togglePk` returns a new array — never mutates. `trimSelection` drops any selected pk not present in `pks` (used when the row set narrows).

## State contracts

`ConfigTab`, `TableStateData`, and `TableStateMethods` are the framework-agnostic contracts that the Vue `ReactiveTableState` implements. Reuse them when writing a React/Svelte port so the rest of `@atscript/ui-table` keeps working.

```typescript
type ConfigTab = "columns" | "filters" | "sorters";

interface TableStateData {
  tableDef: TableDef | null;
  columnNames: string[];
  allColumns: ColumnDef[];
  columnWidths: ColumnWidthsMap;
  filterFields: string[];
  filters: FieldFilters;
  sorters: SortControl[];
  searchTerm: string;
  pagination: PaginationControl;
  selectedRows: unknown[];
  results: Record<string, unknown>[];
  totalCount: number;
  // ...
}

interface TableStateMethods {
  query(): Promise<void>;
  loadRange(from: number, to: number): Promise<void>;
  setColumnNames(names: string[]): void;
  setColumnWidths(widths: ColumnWidthsMap): void;
  setFilters(filters: FieldFilters, fields?: string[]): void;
  setSorters(sorters: SortControl[]): void;
  setSearchTerm(value: string): void;
  setPagination(p: PaginationControl): void;
  setSelectedRows(rows: unknown[]): void;
  applyUrlQuery(urlString: string): void;
  // ...
}
```

The full mutator list mirrors `ReactiveTableState` in [`@atscript/vue-table`](/api/vue-table) — see that page for the complete enumeration with reactive types.

## Window mode helpers

Used by `<AsWindowTable>` to compute page-aligned fetch ranges and merge incoming results into the universal cache.

```typescript
const DEFAULT_ROW_HEIGHT_PX: number;

interface PageAlignedBlock {
  /** 1-based page number, ready to pass to a server pagination param. */
  page: number;
  /** Index of the first row in the block. */
  firstIndex: number;
}

function pageAlignedBlocksFor(skip: number, limit: number, blockSize: number): PageAlignedBlock[];
function blockStartFor(absIdx: number, blockSize: number): number;
function clampTopIndex(topIndex: number, totalCount: number, viewport: number): number;

interface MergeResult {
  /* ... */
}
function walkForwardAbsorb(results: MergeResult): void;
function walkBackwardAbsorb(results: MergeResult): void;

/** `"jump"` — viewport sits in uncached territory; centre a fetch around it. `"steady"` — fetch one block at the edge that's running out. */
type FetchPlanMode = "jump" | "steady";

interface FetchPlan {
  skip: number;
  limit: number;
  mode: FetchPlanMode;
}

interface PlanFetchArgs {
  top: number;
  viewport: number;
  totalCount: number;
  cache: Map<number, unknown>;
  blockSize: number;
  /** Threshold below which a steady prefetch fires. Typically `blockSize / 4`. */
  buffer: number;
}

function planFetch(args: PlanFetchArgs): FetchPlan | null;
```

`planFetch` is the centerpiece: given the viewport and the universal-cache state, it returns the single fetch the renderer should issue next (or `null` when the cache already satisfies the visible range).

## Column widths

```typescript
interface ColumnWidthEntry {
  w: string; // current rendered width
  d: string; // computed default
}
type ColumnWidthsMap = Record<string, ColumnWidthEntry>;

const MAX_DEFAULT_COLUMN_WIDTH_PX: number;

function computeDefaultColumnWidth(column: ColumnDef): string;
function reconcileColumnWidthDefaults(
  current: ColumnWidthsMap,
  columns: ColumnDef[],
): ColumnWidthsMap;
```

`computeDefaultColumnWidth` prefers `@ui.table.width`, falls back to type + `@expect.maxLen`, clamps to `MAX_DEFAULT_COLUMN_WIDTH_PX`. `reconcileColumnWidthDefaults` is called whenever the column set changes so widths stay populated for every visible column.

## Utilities

```typescript
function debounce<T extends (...args: any[]) => unknown>(fn: T, ms: number): T & { cancel(): void };
function arraysEqual<T>(a: readonly T[], b: readonly T[]): boolean;
function sameColumnSet(a: readonly string[], b: readonly string[]): boolean;
function setsEqual<T>(a: ReadonlySet<T>, b: ReadonlySet<T>): boolean;
function sortersEqual(a: readonly SortControl[], b: readonly SortControl[]): boolean;

type ColumnReorderPosition = "before" | "after";

/** Pure — returns a new array. Returns input unchanged when paths are missing or the move is a no-op. */
function reorderColumnNames(
  names: string[],
  fromPath: string,
  toPath: string,
  position: ColumnReorderPosition,
): string[];
```

## Cross-links

- [Tables — Filtering](/tables/filtering)
- [Tables — Sorting](/tables/sorting)
- [Tables — Pagination & Virtualization](/tables/pagination)
- [Tables — Presets](/tables/presets)
- [Tables — URL State](/tables/url-state)
- [@atscript/vue-table](/api/vue-table) — Vue-side `ReactiveTableState`
- [@atscript/moost-ui-presets](/api/moost-ui-presets) — server endpoint


---
URL: "ui.atscript.dev/api/vue-aooth"
LLMS_URL: "ui.atscript.dev/api/vue-aooth.md"
---

# @atscript/vue-aooth

Custom Vue 3 form-field components for [Aooth](https://aooth.moost.org)-flavoured flows — multi-consent collection, password-policy display, QR-code enrolment, one-shot link/token sharing, and SSO / social-login provider picking. All five implement the `TAsComponentProps` contract from [`@atscript/vue-form`](/api/vue-form) and drop into `<AsForm :components>` via the `@ui.form.component` annotation. Typically paired with [`@atscript/vue-wf`](/api/vue-wf) when the consents, policies, TOTP URIs, or magic links arrive as part of a workflow `formContext`.

## Contents

- [Subpath](#subpath)
- [Component — AsConsentArray](#component-asconsentarray)
- [Component — AsPasswordRules](#component-aspasswordrules)
- [Component — AsQrCode](#component-asqrcode)
- [Component — AsCopy](#component-ascopy)
- [Component — AsSsoProviders](#component-asssoproviders)
- [Custom-component patterns used](#custom-component-patterns-used)

## Subpath

```typescript
// barrel
import {
  AsConsentArray,
  AsCopy,
  AsPasswordRules,
  AsQrCode,
  AsSsoProviders,
} from "@atscript/vue-aooth";

// per-component (for granular bundling)
import AsConsentArray from "@atscript/vue-aooth/as-consent-array";
import AsCopy from "@atscript/vue-aooth/as-copy";
import AsPasswordRules from "@atscript/vue-aooth/as-password-rules";
import AsQrCode from "@atscript/vue-aooth/as-qr-code";
import AsSsoProviders from "@atscript/vue-aooth/as-sso-providers";

// descriptor types (prop payload item shapes)
import type { AsConsentArrayItem, AsPasswordRulesPolicy, AsSsoProvider } from "@atscript/vue-aooth";
```

None of the five are auto-resolved — all are Tier-2 swap targets. Register them by name in `<AsForm :components>` and tag the field with `@ui.form.component`. The narrative guide with end-to-end examples lives at [Forms · Aooth components](/forms/aooth-components).

The descriptor types behind the custom props are exported too — use them to type the lists you place on `formContext`:

- `AsConsentArrayItem` — one `pendingConsents` entry for [`AsConsentArray`](#component-asconsentarray).
- `AsPasswordRulesPolicy` — one `policies` entry for [`AsPasswordRules`](#component-aspasswordrules).
- `AsSsoProvider` — one `providers` entry for [`AsSsoProviders`](#component-asssoproviders).

## Component — AsConsentArray

Multi-consent checkbox group. The bound value is a `string[]` containing the ids of every checked consent. When the source list is empty, the entire field is suppressed — useful for "show the legal block only when the backend says it has new consents to collect".

### Props

Extends `TAsComponentProps<string[]>` with one custom prop fed via `@ui.form.fn.attr`:

```typescript
interface AsConsentArrayItem {
  /** Value committed to the bound `string[]` when checked. */
  id: string;
  /** Checkbox label. Supports `[text](url)` markdown links for http(s)/mailto URLs. */
  text: string;
  /**
   * Non-empty string ⇒ mandatory consent; the string is the surfaced
   * error message. Empty / undefined ⇒ optional.
   */
  required?: string;
}

interface AsConsentArrayProps extends TAsComponentProps<string[]> {
  pendingConsents?: AsConsentArrayItem[];
}
```

### Behaviour

- One row per `pendingConsents` entry. The whole shell is hidden when `pendingConsents` is empty or omitted.
- A required consent renders an asterisk marker on its label. Missing required consents surface their `required` message inline beneath the row (the shell-level error footer is suppressed to avoid duplication).
- Consent text is parsed for markdown links `[label](url)`. Only `http://`, `https://`, and `mailto:` URLs render as anchors; any other scheme falls back to the verbatim source string so dangerous schemes (e.g. `javascript:`) can't sneak through.
- Validation runs through `useAsField` — registered alongside the field-state entry `<AsField>` already provides, so all rules run at submit time and external errors propagate.
- The committed array preserves insertion order — checks append, unchecks remove. The display order follows `pendingConsents`.

### How to wire

```atscript
// auth-step.as
export interface SignupStep {
    @meta.label 'Email'
    @meta.required 'Email required'
    email: string.email

    @ui.form.component 'AsConsentArray'
    @ui.form.fn.attr 'pendingConsents', '(_v, _d, ctx) => ctx.pendingConsents'
    consents: string[]
}
```

The consents list comes from the form's `formContext` — typically supplied by the backend through `<AsWfForm>`'s server round-trip, so the same field schema works whether your backend ships one consent or ten.

```vue
<script setup lang="ts">
import { AsForm, createAsFormDef, createDefaultTypes } from "@atscript/vue-form";
import { AsConsentArray } from "@atscript/vue-aooth";
import { SignupStep } from "./auth-step.as";

const { def, formData } = createAsFormDef(SignupStep);
const types = createDefaultTypes();
const components = { AsConsentArray };

// In a real app, formContext is whatever the server sends back.
const formContext = {
  pendingConsents: [
    {
      id: "tos",
      text: "I accept the [Terms of Service](https://example.com/tos)",
      required: "Please accept the Terms",
    },
    { id: "marketing", text: "Send me product updates" },
  ],
};
</script>

<template>
  <AsForm
    :def="def"
    :form-data="formData"
    :form-context="formContext"
    :types="types"
    :components="components"
  />
</template>
```

## Component — AsPasswordRules

Display-only readout of password-policy fulfilment. Pair it with a sibling password field; the component re-evaluates on every password keystroke and toggles each row's met / unmet state.

### Props

`TAsComponentProps` (no value binding — the field is display-only, conventionally typed as `ui.paragraph` so the form treats it as non-data chrome) plus:

```typescript
interface AsPasswordRulesPolicy {
  /** Function-string evaluated through @atscript/ui-fns' compileFieldFn. */
  rule: string;
  /** Plain label shown to the user. */
  description?: string;
  /** Backend-supplied wording reserved for future submit-failure surfacing. */
  errorMessage?: string;
}

interface AsPasswordRulesProps extends TAsComponentProps {
  policies?: AsPasswordRulesPolicy[];
  /** Current password value — typically sourced from a sibling field. */
  password?: string;
}
```

### Behaviour

- Each policy row reads `data-passed="true" | "false"` — style the met / unmet glyph and text through descendant selectors on `.as-password-rules-row`.
- The `rule` string is compiled with `compileFieldFn` from `@atscript/ui-fns`, sharing the same FNPool cache the framework uses for `@ui.form.fn.*` annotations. Compiled rules are invoked positionally — the rule's first argument receives the current password.
- Empty password ⇒ all rows render as unpassed, regardless of what a no-op rule would technically return. This avoids misleading "all good!" cues at the empty-input state.
- A broken / throwing rule is treated as unpassed and logged once per distinct rule source (no console flooding on every keystroke).

### How to wire

```atscript
// password-step.as
export interface PasswordStep {
    @meta.label 'New password'
    @meta.required 'Password required'
    @ui.form.type 'password'
    newPassword: string

    @ui.form.type 'paragraph'
    @ui.form.component 'AsPasswordRules'
    @ui.form.fn.attr 'policies', '(_v, _d, ctx) => ctx.passwordPolicies'
    @ui.form.fn.attr 'password', '(_, data) => data.newPassword'
    passwordHints: string
}
```

`policies` is sourced from `formContext.passwordPolicies` (server-supplied, typically arriving via `<AsWfForm>`); `password` watches the live sibling value via `(_, data) => data.newPassword`. The compiled `rule` strings receive that password as their first argument.

```vue
<script setup lang="ts">
import { AsForm, createAsFormDef, createDefaultTypes } from "@atscript/vue-form";
import { AsPasswordRules } from "@atscript/vue-aooth";
import { PasswordStep } from "./password-step.as";

const { def, formData } = createAsFormDef(PasswordStep);
const types = createDefaultTypes();
const components = { AsPasswordRules };

const formContext = {
  passwordPolicies: [
    { rule: "(p) => p.length >= 8", description: "At least 8 characters" },
    { rule: "(p) => /[A-Z]/.test(p)", description: "At least one uppercase letter" },
    { rule: "(p) => /[0-9]/.test(p)", description: "At least one digit" },
  ],
};
</script>

<template>
  <AsForm
    :def="def"
    :form-data="formData"
    :form-context="formContext"
    :types="types"
    :components="components"
  />
</template>
```

## Component — AsQrCode

Phantom field that renders an SVG QR code from any string. Primarily used for TOTP enrolment: for `otpauth://` URIs it also surfaces the `?secret=` query param beneath the SVG as a manual-entry fallback for users who can't scan.

### Props

`TAsComponentProps<string | undefined>` plus:

```typescript
interface AsQrCodeProps extends TAsComponentProps<string | undefined> {
  /** SVG width in px. Default 192. */
  size?: number;
  /** QR error-correction level. Default "M". */
  errorCorrection?: "L" | "M" | "Q" | "H";
  /**
   * Show the parsed `?secret=` fallback for `otpauth://` values.
   * Default true — set false when surfacing the secret defeats the
   * threat model (e.g. screen-sharing demos).
   */
  manualSecret?: boolean;
}
```

### Behaviour

- The value is read as `props.value ?? props.model?.value`. Phantom registrations (`ui.paragraph` + `@ui.form.fn.value`) push through `props.value`; data-bound fields use `model.value`.
- `qrcode` is an **optional peer dependency** — install it in the consumer app only for flows that use `AsQrCode`. The module is dynamic-imported, so apps without the dep pay no bundle cost.
- For `otpauth://` URIs the parsed secret renders as plain text beneath the SVG unless `:manualSecret="false"`.

```bash
npm install qrcode
```

### How to wire

```atscript
// enrol-step.as
export interface EnrolStep {
    @meta.label 'Scan with your authenticator app'
    @ui.form.fn.value '(v, data, ctx) => ctx.totpUri'
    @ui.form.component 'AsQrCode'
    totpUri: ui.paragraph
}
```

`totpUri` is supplied from `formContext` (server-side via `@wf.context.pass 'totpUri'` on a workflow form). See [Phantom vs data-bound](/forms/aooth-components#phantom-vs-data-bound) for the full pattern.

## Component — AsCopy

Phantom field that surfaces a one-shot string with a read-only input and a Copy button. Click writes through `navigator.clipboard.writeText` and swaps the button label to "Copied" for ~1.5 s; focusing the input selects the full value for fallback Ctrl+C / Cmd+C copy.

### Props

`TAsComponentProps<string | undefined>` plus:

```typescript
interface AsCopyProps extends TAsComponentProps<string | undefined> {
  /** Idle button label. Default "Copy". */
  copyLabel?: string;
  /** Post-copy button label. Default "Copied". */
  copiedLabel?: string;
}
```

### Behaviour

- Value is read as `props.value ?? props.model?.value` — same phantom + data-bound dual mode as `AsQrCode`.
- Failed clipboard writes (no permission, no API) flip the button back and surface "Copy failed — select and copy manually" through the field's error slot.

### How to wire

```atscript
// share-step.as
export interface ShareStep {
    @meta.label 'Magic link'
    @ui.form.fn.value '(v, data, ctx) => ctx.magicLink'
    @ui.form.component 'AsCopy'
    magicLink: ui.paragraph
}
```

Use it for magic links, share tokens, generated identifiers — any one-off value the user needs to paste somewhere else.

## Component — AsSsoProviders

SSO / social-login provider picker. Renders providers as a main stack of full-width buttons; any provider flagged `secondary: true` drops below an "or" divider as a compact chip. Each provider button is a one-click action — clicking selects the provider (writes its id to the bound model) _and_ fires the field's `@ui.form.action` in a single click, so there is no separate submit button. The bound value is the selected provider id. When the source list is empty the entire field is suppressed.

### Props

`TAsComponentProps<string | undefined>` with one custom prop fed via `@ui.form.attr` / `@ui.form.fn.attr`:

```typescript
interface AsSsoProvider {
  /** Committed to the bound model (`model.value = id`) on click and carried by the fired form action. */
  id: string;
  /**
   * Rendered VERBATIM. The backend owns the full display string (e.g.
   * "Continue with Google" for a main-stack button, "Discord" for a
   * secondary chip). The component never composes a "Continue with {name}" prefix.
   */
  text: string;
  /**
   * Optional CSS class painting the brand glyph (e.g. `i-logos-google-icon`).
   * Applied as-is; the consumer owns the icon collection / safelist coverage,
   * same contract as `prefixIcon`.
   */
  icon?: string;
  /**
   * `true` ⇒ renders as a compact chip below the "or" divider; omitted / false
   * ⇒ renders as a full-width button in the main stack (the default).
   */
  secondary?: boolean;
}

interface AsSsoProvidersProps extends TAsComponentProps<string | undefined> {
  providers?: AsSsoProvider[];
}
```

### Behaviour

- One-click contract: a click sets `model.value = provider.id` then emits the form `action` declared by `@ui.form.action` on the field. `<AsForm>` surfaces it as `@action(name, data)` with the selected provider already in `data`. Without a wired `@ui.form.action` the click still commits the id but emits nothing.
- Providers default to the prominent main stack (full-width buttons); only `secondary: true` opts into the compact chip group below the "or" divider. The "or" divider renders only when _both_ groups are non-empty — a lone group never dangles a divider.
- `text` is rendered verbatim. The component never prefixes "Continue with …"; the backend supplies the complete string per provider.
- `icon` is applied as-is. Icon classes referenced from `.as` files aren't seen by the static class extractor, so safelist whatever collection you ship.
- Empty or missing `providers` hides the whole field — the same render-only-when-the-backend-supplied-providers pattern as `AsConsentArray`. This also guards the transient first render before `@ui.form.fn.attr` resolves.
- No separate submit / "Continue" control: the component renders chromeless and suppresses the shell's footer action link, since the provider buttons themselves _are_ the action.

### How to wire

```atscript
// login-step.as
export interface LoginStep {
    @ui.form.component 'AsSsoProviders'
    @ui.form.action 'sso', 'Continue'
    @ui.form.fn.attr 'providers', '(_v, _d, ctx) => ctx.ssoProviders'
    ssoProvider?: string
}
```

The provider list comes from the form's `formContext` — typically supplied by the backend through `<AsWfForm>`'s server round-trip, so the same field schema works whether you offer one provider or ten. In a workflow form, add `@wf.action.withData 'sso'` on the same field so the chosen `ssoProvider` is submitted with the action (the same mechanism `forgotPassword` uses to carry a typed value). An optional `ssoProvider?` won't block a password login that submits without one.

```vue
<script setup lang="ts">
import { AsForm, createAsFormDef, createDefaultTypes } from "@atscript/vue-form";
import { AsSsoProviders } from "@atscript/vue-aooth";
import { LoginStep } from "./login-step.as";

const { def, formData } = createAsFormDef(LoginStep);
const types = createDefaultTypes();
const components = { AsSsoProviders };

// In a real app, formContext is whatever the server sends back.
// Icon classes are whatever icon collection your app ships + safelists.
const formContext = {
  ssoProviders: [
    { id: "google", text: "Continue with Google", icon: "i-logos:google-logo" },
    { id: "discord", text: "Discord", icon: "i-logos:discord-logo", secondary: true },
  ],
};

function onAction(name: string, data: { ssoProvider?: string }) {
  // name === "sso"; data.ssoProvider is the clicked provider id, e.g. "google".
  console.log("SSO provider selected:", data.ssoProvider);
}
</script>

<template>
  <AsForm
    :def="def"
    :form-data="formData"
    :form-context="formContext"
    :types="types"
    :components="components"
    @action="onAction"
  />
</template>
```

## Custom-component patterns used

These components are production examples of the patterns documented in [Custom Field Components](/forms/custom-components):

- **`AsConsentArray`** demonstrates the "`useAsField` inside a custom component" pattern — registering an extra field-state rule alongside the one `<AsField>` already provides, so per-item required validation runs at submit alongside the schema-level pipeline.
- **`AsPasswordRules`** demonstrates the "re-use `compileFieldFn` for fn-string arrays" pattern — evaluating consumer-supplied policy rule strings through the framework's shared FNPool instead of allocating a private one.
- **`AsQrCode`** and **`AsCopy`** demonstrate the **phantom display field** pattern — `ui.paragraph` + `@ui.form.fn.value` reading from `formContext`, so a server-supplied value renders without ever entering the bound data.
- **`AsSsoProviders`** demonstrates emitting a **form action from a custom component** — one-click select + fire `@ui.form.action` in a single click — together with the `@wf.action.withData` data-carrying-action pattern for workflow forms.

## Cross-links

- [@atscript/vue-form](/api/vue-form) — the underlying form renderer
- [@atscript/vue-wf](/api/vue-wf) — pairs naturally for Aooth-driven workflow flows
- [@atscript/ui-fns](/api/ui-fns) — supplies `compileFieldFn`
- [Aooth](https://aooth.moost.org) — auth + RBAC for the Moost / atscript ecosystem


---
URL: "ui.atscript.dev/api/vue-form"
LLMS_URL: "ui.atscript.dev/api/vue-form.md"
---

# @atscript/vue-form

Vue 3 form library backed by `@atscript/ui`. Three tiers of components, ~30 composables, two factories, and one auto-resolver entry. Every Tier-1 component you tag (`<AsForm>`, `<AsField>`, `<AsIterator>`) wraps a public composable, so apps can drop the renderer and rebuild their own form root without losing functionality.

## Contents

- [Tier 1 — Primary components](#tier-1-primary-components)
- [Tier 2 — Default field components](#tier-2-default-field-components)
- [Factories](#factories)
- [Composables — form / state](#composables-form-state)
- [Composables — field & structure](#composables-field-structure)
- [Composables — value help / dropdown](#composables-value-help-dropdown)
- [Composables — choreography](#composables-choreography)
- [Composables — date / number / decimal](#composables-date-number-decimal)
- [Composables — context / utility](#composables-context-utility)
- [Component prop & emit types](#component-prop-emit-types)
- [Other types](#other-types)

## Tier 1 — Primary components

Imported automatically by `AsResolver()` (see [@atscript/ui-styles](/api/ui-styles)).

### `AsForm`

Top-level form renderer.

**Props** (subset — see `useAsForm` for full reactive contract):

```typescript
interface AsFormProps {
  def: FormDef;
  formData?: { value: unknown };
  formContext?: unknown;
  types: TAsTypeComponents;
  components?: Record<string, Component>;
  errors?: Record<string, string | undefined>;
  firstValidation?: "on-change" | "touched-on-blur" | "on-blur" | "on-submit";
  hideRootTitle?: boolean;
  hideSubmit?: boolean;
  loading?: boolean;
  clientFactory?: ClientFactory;
}
```

**Emits**:

- `submit(data)` — validation passed, data ready to ship.
- `error(errors)` — validation failed; payload is `{ path, message }[]`.
- `action(name, data)` — phantom `<AsAction>` button dispatched.
- `unsupportedAction(name, data)` — action name not declared on the form's type.
- `change(type, path, value, data)` — granular per-field change; `type` is `TAsChangeType`.

**Slots**: `form.header`, `form.before`, `form.after`, `form.error`, `form.submit`, `form.footer`, `form.loading`. Every slot receives the unified `slotProps` bag (see [`useAsForm` return](#useasform-options)); `form.error` also gets `message` / `dismiss`, `form.submit` also gets `text`. See [Forms — Slots & the slotProps bag](/forms/customization#slots-the-slotprops-bag).

### `AsField`

Renders a single field given a `FormFieldDef`. Use when laying out form fields manually instead of letting `AsForm` iterate.

```typescript
interface AsFieldProps {
  field: FormFieldDef;
  /** External validation error to surface on this field. */
  error?: string;
  /** Wires the array-item remove affordance when rendered inside an array. */
  onRemove?: () => void;
  canRemove?: boolean;
  removeLabel?: string;
  /** Index of this field within a parent array — drives the `#N` suffix on labels. */
  arrayIndex?: number;
}
```

### `AsIterator`

Iterates the fields of a `FormDef` and renders each through `AsField`. Used by `AsObject` for nested objects and exposed for advanced compositions.

```typescript
interface AsIteratorProps {
  def: FormDef;
  /** Optional dotted segment to prepend to every child field's path. */
  pathPrefix?: string;
  onRemove?: () => void;
  canRemove?: boolean;
  removeLabel?: string;
}
```

### `AsCollapsible`

Section chrome with a collapsible `<summary>` header plus
`actions` / `badges` / `title-extras` / `body` / `empty` slots.
`AsObject` / `AsArray` / `AsTuple` render nested structures through it.
Public so a custom `@ui.form.component` can own its own section header and
inject header-row actions. See [Collapsible Sections](/forms/collapsible-sections)
for the narrative.

```typescript
interface AsCollapsibleProps {
  /** Header heading text. */
  title?: string;
  /** Sub-text under the title. */
  description?: string;
  /** REQUIRED. ≤0 → root (no chrome), odd → section, even → island. */
  level: number;
  /** When true and not enabled, the `empty` slot renders instead of the section. Default `false`. */
  optional?: boolean;
  /** Gates the `empty` slot — shown when `optional && !optionalEnabled`. Default `false`. */
  optionalEnabled?: boolean;
  /** Unique key registered with the sections store (expand/collapse + auto-open). */
  path: string;
  /** Renders an alert row at the top of the body. */
  error?: string;
  /** Open on first mount. Defaults to `false`. */
  defaultOpen?: boolean;
  /** Hides via `v-show` — stays mounted and registered. */
  hidden?: boolean;
  /** Appends a `#N` suffix to the title. */
  arrayIndex?: number;
}
```

**Slots**: `title-extras`, `badges`, `actions` (all render inside `<summary>`),
`body`, `empty`.

**Expose**: `runAndFocus(fn)` / `runAndFocusNew(fn)` — open-then-focus helpers
(focus first / first-new focusable inside after toggle). Used by array/optional
add-flows; rarely needed directly.

## Tier 2 — Default field components

Default swap targets for the `types` map. Importable both via the package root and the kebab subpath used by `AsResolver`.

```typescript
import { AsInput, AsSelect } from "@atscript/vue-form";
// or, for tree-shake-friendly single imports
import AsInput from "@atscript/vue-form/as-input";
```

Every component implements `TAsComponentProps`. The columns below list the `@ui.type` value that maps to each component in `createDefaultTypes()`.

| Component       | Default `type` keys            | Notes                                                                                                    |
| --------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `AsFieldShell`  | (all)                          | Chrome wrapper — title, description, error, hint, prefix/suffix. Used internally by every other default. |
| `AsInput`       | `text`, `textarea`, `password` | Plain string input.                                                                                      |
| `AsNumber`      | `number`                       | Integer input with prefix/suffix, currency-aware.                                                        |
| `AsDecimal`     | `decimal`                      | Decimal-string input with `precisionScale` enforcement.                                                  |
| `AsSelect`      | `select`                       | `<select>` element fed by `options` / value-help.                                                        |
| `AsRadio`       | `radio`                        | Radio group.                                                                                             |
| `AsCheckbox`    | `checkbox`                     | Boolean checkbox or tri-state.                                                                           |
| `AsMultiSelect` | `multiselect`                  | Multi-select combobox with chip-style selections, bound to `T[]`.                                        |
| `AsDate`        | `date`                         | Date-only input.                                                                                         |
| `AsDatetime`    | `datetime`                     | Date-time input.                                                                                         |
| `AsTime`        | `time`                         | Time-of-day input.                                                                                       |
| `AsParagraph`   | `paragraph`                    | Phantom read-only field; renders `value` as text.                                                        |
| `AsAction`      | `action`                       | Phantom button — emits `action`.                                                                         |
| `AsObject`      | `object`                       | Iterates over a nested object's fields.                                                                  |
| `AsArray`       | `array`                        | Renders array items with add/remove affordances.                                                         |
| `AsUnion`       | `union`                        | Variant picker + nested fields for the active branch.                                                    |
| `AsTuple`       | `tuple`                        | Positional fields, fixed length.                                                                         |
| `AsRef`         | `ref`                          | FK input with value-help dropdown.                                                                       |

All defaults accept the full `TAsComponentProps` contract — see [Component prop & emit types](#component-prop-emit-types).

## Factories

### `createDefaultTypes()`

Returns a pre-populated `TAsTypeComponents` map with every default in the table above.

```typescript
function createDefaultTypes(): TAsTypeComponents;
```

```typescript
import { createDefaultTypes } from "@atscript/vue-form";

const types = createDefaultTypes();
types.text = MyCustomTextInput; // swap one entry
```

### `createAsFormDef(type, context?)`

Builds a `FormDef` from an `.as` annotated type and a fresh reactive `formData` container with `@meta.default` values applied. When `context` is provided and `@atscript/ui-fns` is installed, `@ui.form.fn.value` annotations evaluate against it during default-value resolution.

```typescript
function createAsFormDef<T extends TAtscriptAnnotatedType>(
  type: T,
  context?: Record<string, unknown>,
): { def: FormDef; formData: { value: unknown } };
```

For tables that opt into optimistic concurrency, call the lower-level `createFormDef(type, { versionColumn })` from `@atscript/ui` directly so the version field is excluded from `def.fields[]` (it stays in `flatMap` and form data so the wire payload still carries it). See the [Edit forms with optimistic concurrency](/tables/edit-form-occ) pattern guide.

### `formatIndexedLabelParts(label, arrayIndex)`

Splits a label into base + optional `#N` suffix for two-part rendering by `AsCollapsible` / `AsFieldShell`. Returns `undefined` when both the base and suffix are absent.

```typescript
function formatIndexedLabelParts(
  label: string | undefined,
  arrayIndex: number | undefined,
): { base: string; suffix?: string } | undefined;
```

## Composables — form / state

### `useAsForm(options)`

Powers `<AsForm>`. Owns the data container, internal validator, external-error dismissal, action routing, change merging, descendant counts, auto-open, and all provide/inject wiring. Use this when building a custom form root.

```typescript
function useAsForm<TFormData = unknown, TFormContext = unknown>(
  options: UseAsFormOptions<TFormData, TFormContext>,
): UseAsFormReturn<TFormData, TFormContext>;
```

`UseAsFormOptions` accepts **getters** for every reactive prop so `defineProps()` accessors thread in without an extra `ref`:

```typescript
interface UseAsFormOptions<TFormData, TFormContext> {
  def: () => FormDef;
  formData?: () => TFormData | undefined;
  formContext?: () => TFormContext | undefined;
  firstValidation?: () => TFormState["firstValidation"] | undefined;
  components?: () => Record<string, Component<TAsComponentProps>> | undefined;
  types: () => TAsTypeComponents;
  errors?: () => Record<string, string | undefined> | undefined;
  clientFactory?: () => ClientFactory | undefined;
  hideRootTitle?: () => boolean | undefined;
  /** Busy flag — locks the form and disables submit while a round-trip is in flight (used by `AsWfForm`). */
  loading?: () => boolean | undefined;
  emits?: {
    submit?: (data: TFormData) => void;
    error?: (errors: { path: string; message: string }[]) => void;
    action?: (name: string, data: TFormData) => void;
    unsupportedAction?: (name: string, data: TFormData) => void;
    change?: (type: TAsChangeType, path: string, value: unknown, formData: TFormData) => void;
  };
}
```

Returns:

```typescript
interface UseAsFormReturn<TFormData, TFormContext> {
  data: ComputedRef<TFormData>;
  errors: ComputedRef<Record<string, string | undefined> | undefined>;
  formError: ComputedRef<string | undefined>;
  internalErrors: Ref<Record<string, string>>;
  reset: () => Promise<void>;
  clearErrors: () => void;
  setErrors: (errors: Record<string, string>) => void;
  onSubmit: () => void;
  submitText: ComputedRef<string>;
  submitDisabled: ComputedRef<boolean>;
  /** Resolved form-level title (`@ui.form.fn.title` / `@meta.label`); may be `undefined`. */
  title: ComputedRef<string | undefined>;
  /** Resolved form-level description (`@ui.form.fn.description` / `@meta.description`). */
  description: ComputedRef<string | undefined>;
  /** Unified slot-props bag spread onto every `<AsForm>` slot via `v-bind`. */
  slotProps: ComputedRef<{
    title: string | undefined;
    description: string | undefined;
    data: TFormData;
    errors: Record<string, string | undefined> | undefined;
    formError: string | undefined;
    disabled: boolean;
    loading: boolean;
    submitText: string;
    submit: () => void;
    reset: () => Promise<void>;
    clearErrors: () => void;
    setErrors: (errors: Record<string, string>) => void;
    dismissError: (path: string) => void;
    dismissFormError: () => void;
    formContext: TFormContext | undefined;
  }>;
  invokeAction: (name: string) => void;
  dismissError: (path: string) => void;
  dismissFormError: () => void;
  formContext: ComputedRef<TFormContext | undefined>;
  handleChange: (type: TAsChangeType, path: string, value: unknown) => void;
}
```

### `useAsState(options)`

Lower-level state plumbing: validators, error maps, first-validation strategy, freshness tracking. `useAsForm` builds on top of this.

```typescript
function useAsState<TFormData, TFormContext>(options: {
  formData: ComputedRef<TFormData>;
  formContext: ComputedRef<TFormContext | undefined>;
  firstValidation: ComputedRef<TFormState["firstValidation"] | undefined>;
  submitValidator: TFormSubmitValidator;
}): UseAsStateReturn;
```

`TFormSubmitValidator` returns `true` for success or an `{ path, message }[]` error list.

### `useAsExternalErrors(options)`

Reactive merge + per-path dismissal for server-supplied errors. `useAsForm` mounts this internally; pull it directly when consuming `<AsForm>` from a wrapper that owns its own error state.

```typescript
function useAsExternalErrors(options: UseAsExternalErrorsOptions): UseAsExternalErrorsReturn;

interface UseAsExternalErrorsOptions {
  source: () => Record<string, string | undefined> | undefined;
}

interface UseAsExternalErrorsReturn {
  effective: ComputedRef<Record<string, string | undefined> | undefined>;
  formError: ComputedRef<string | undefined>;
  dismissAt: (path: string) => void;
  dismissForm: () => void;
}
```

## Composables — field & structure

### `useAsField(opts)`

Field-level state machine — model wrapper, validator pipeline, error resolution, blur tracking, and registration with the parent form. Call from a custom field that owns its own commit path instead of routing through `AsField`.

```typescript
interface UseAsFieldOptions<TValue, TFormData, TContext> {
  getValue: () => TValue;
  setValue: (v: TValue) => void;
  rules?: TFormRule<TValue, TFormData, TContext>[];
  path: () => string;
  /** Value to set on form reset. Defaults to `''`. Use `[]` for arrays, `{}` for objects. */
  resetValue?: TValue;
}

interface UseAsFieldReturn<TValue> {
  model: WritableComputedRef<TValue>;
  error: ComputedRef<string | undefined>;
  onBlur: () => void;
}

function useAsField<TValue, TFormData, TContext>(
  opts: UseAsFieldOptions<TValue, TFormData, TContext>,
): UseAsFieldReturn<TValue>;
```

### `useAsArray(field, disabled?)`

Powers `AsArray`. Manages stable item keys, add/remove respecting `@expect.minLength` / `@expect.maxLength`, and union-item variant resolution.

```typescript
function useAsArray(field: FormArrayFieldDef, disabled?: ComputedRef<boolean>): UseAsArrayReturn;

interface UseAsArrayReturn {
  arrayValue: ComputedRef<unknown[]>;
  itemKeys: string[];
  isUnion: boolean;
  unionVariants: FormUnionVariant[];
  isOptional: boolean;
  isEmpty: ComputedRef<boolean>;
  getItemField: (index: number, name?: string) => FormFieldDef;
  addItem: (variantIndex?: number) => void;
  removeItem: (index: number) => void;
  clear: () => void;
  canAdd: ComputedRef<boolean>;
  canRemove: ComputedRef<boolean>;
}
```

### `useAsTuple(field)`

Powers `AsTuple`. Fixed-length positional fields; auto-fills missing positions on mount unless the tuple is optional.

```typescript
function useAsTuple(field: FormTupleFieldDef): UseAsTupleReturn;

interface UseAsTupleReturn {
  itemFields: FormFieldDef[];
  positionLabeled: boolean[];
  isOptional: boolean;
  isEmpty: ComputedRef<boolean>;
  clear: () => void;
  fillMissing: () => void;
}
```

### `useAsUnion(props)`

Powers `AsUnion`. Owns the locally-selected variant index and stashes per-variant data so toggling back restores prior input. Pass the component's resolved `TAsComponentProps` (`AsUnion` reads `props.field` + `props.model`).

```typescript
function useAsUnion(props: TAsComponentProps): UseAsUnionReturn;

interface UseAsUnionReturn {
  unionField: ComputedRef<FormUnionFieldDef | undefined>;
  hasMultipleVariants: ComputedRef<boolean>;
  localUnionIndex: Ref<number>;
  innerField: ComputedRef<FormFieldDef | undefined>;
  changeVariant: (newIndex: number) => void;
  optionalEnabled: ComputedRef<boolean>;
}
```

### `useAsUnionVariant()`

Reads the current union context (`TAsUnionContext`) injected by the closest `AsUnion`. Returns `undefined` outside a union.

```typescript
function useAsUnionVariant(): TAsUnionContext | undefined;
```

## Composables — value help / dropdown

### `useAsValueHelp(options)`

Lazily resolves a `ValueHelpInfo` descriptor on mount, then exposes a debounced search API for FK pickers. Reads the active `ClientFactory` from the nearest `<AsForm :client-factory>` (or the global default) automatically.

```typescript
interface UseAsValueHelpOptions {
  /** Resolved value-help descriptor (read from `props.valueHelp`). */
  info: ValueHelpInfo;
  /** The model whose `.value` the picker writes to on select. */
  model: { value: unknown };
  /** Called after a selection commits so AsField can run blur-time validation. */
  onBlur: () => void;
}

interface UseAsValueHelpReturn {
  resolved: ShallowRef<ResolvedValueHelp | null>;
  status: Ref<"loading" | "ready" | "error">;
  searchText: Ref<string>;
  results: ShallowRef<Record<string, unknown>[]>;
  searching: Ref<boolean>;
  labelIsFkValue: ComputedRef<boolean>;
  kickoff: () => Promise<void>;
  selectItem: (item: Record<string, unknown>) => void;
  clear: () => void;
}

function useAsValueHelp(options: UseAsValueHelpOptions): UseAsValueHelpReturn;
```

### `useAsDropdown(containerRef)`

Click-outside-aware dropdown state. The listener is lazy — attached only while open.

```typescript
function useAsDropdown(containerRef: Ref<HTMLElement | null>): {
  isOpen: Ref<boolean>;
  toggle: () => void;
  close: () => void;
  /** Run the callback and close immediately — convenience for option-click handlers. */
  select: (callback: () => void) => void;
};
```

## Composables — choreography

### `useAsOptionalAddFlow(options)`

Implements the "Add" affordance for an optional field. When the user clicks "Add", the value is set to its default; when they clear it, the field is set to `undefined`.

```typescript
function useAsOptionalAddFlow(options: UseAsOptionalAddFlowOptions): UseAsOptionalAddFlowReturn;
```

### `useAsTriStateCheckbox(options)`

Three-state checkbox (`true` / `false` / `undefined`) with keyboard support.

```typescript
function useAsTriStateCheckbox(options: UseAsTriStateCheckboxOptions): UseAsTriStateCheckboxReturn;
```

### `useAsFocusFirstAfter()` / `focusFirstAfter(...)` / `focusNewFocusableAfter(...)`

Focus utilities for "after-toggle" flows — moves DOM focus to the first focusable element added to a region after a toggle.

```typescript
function useAsFocusFirstAfter(): { focusAfter: () => void };
function focusFirstAfter(host: HTMLElement | undefined): void;
function focusNewFocusableAfter(prev: HTMLElement[], host: HTMLElement | undefined): void;
```

## Composables — date / number / decimal

### `useAsDate(options)`

Handles ISO ↔ display conversion for `<AsDate>` / `<AsDatetime>` / `<AsTime>`.

```typescript
function useAsDate(options: UseAsDateOptions): UseAsDateReturn;
```

### `useAsNumber(options)`

Integer input model — handles `select-all on focus`, prefix/suffix, optional toggle.

```typescript
function useAsNumber(options: UseAsNumberOptions): UseAsNumberReturn;
```

### `useAsDecimal(options)`

Decimal-string input model — enforces `precisionScale`, currency formatting, locale separators. Stores as string, never bounces through float.

```typescript
function useAsDecimal(options: UseAsDecimalOptions): UseAsDecimalReturn;
```

### `useAsDualInput(options)`

Powers the merged-shell `AsDecimal` / `AsNumber` layout — two visual inputs (integer and fraction) sharing a single model.

```typescript
function useAsDualInput(options: UseAsDualInputOptions): UseAsDualInputReturn;
```

## Composables — context / utility

### `useAsLocale()` / `provideAsLocale(getter)`

Provide / inject the BCP-47 locale used by date and decimal composables. The getter shape lets reactive sources flow through without an extra `computed()` at the call site.

```typescript
function provideAsLocale(getter: () => string | undefined): void;

interface UseAsLocaleReturn {
  /** Resolved locale; `undefined` when no provider is mounted. */
  locale: ComputedRef<string | undefined>;
}

function useAsLocale(): UseAsLocaleReturn;
```

### `useAsPath()` / `useAsTypeMap()` / `useAsData()`

Read-only context wrappers. Useful in deeply nested custom components that need the current field path, the form's `:types` map, or reactive read access to form data.

```typescript
function useAsPath(): UseAsPathReturn; // { path: ComputedRef<string> }
function useAsTypeMap(): UseAsTypeMapReturn; // { types: ComputedRef<TAsTypeComponents> }

interface UseAsDataReturn {
  /** Domain data — the unwrapped inner value of the form's `{ value }` container. */
  rootData: ComputedRef<unknown>;
  /** Read the value at an absolute dotted path inside the form. */
  getValueAt: (path: string) => ComputedRef<unknown>;
  /** Read a sibling field relative to the current `useAsPath()` prefix. */
  siblingValue: <T = unknown>(name: string) => ComputedRef<T | undefined>;
}

function useAsData(): UseAsDataReturn;
```

### `useAsErrorDismiss()`

Returns the dismissal callback bound by the closest `AsForm`. Lets a custom error-banner component dismiss its own path without bubbling through props.

```typescript
function useAsErrorDismiss(): AsErrorDismiss; // (path: string) => void
```

### `useAsNestedSectionsStore()` / `provideAsNestedSectionsStore()`

Shared collapsible-section store used by `AsObject`. Provide your own when wiring "Expand all" / "Collapse all" controls outside `AsForm`.

```typescript
interface AsNestedSectionsStore {
  isOpen(path: string): boolean;
  setOpen(path: string, open: boolean): void;
  toggle(path: string): void;
  expandAll(paths: Iterable<string>): void;
  collapseAll(paths: Iterable<string>): void;
}

function provideAsNestedSectionsStore(): AsNestedSectionsStore;
function useAsNestedSectionsStore(): AsNestedSectionsStore | undefined;
```

## Component prop & emit types

### `TAsComponentProps<V>`

The full prop contract for custom field components. Implement this so `AsField` can pass every resolved field state.

Key fields (excerpt — full type lives in `components/types.ts`):

```typescript
interface TAsBaseComponentProps {
  disabled?: boolean;
  hidden?: boolean;
}

interface TAsComponentProps<V = unknown> extends TAsBaseComponentProps {
  onBlur: () => void;
  error?: string;
  model: { value: V };
  /** Phantom display value (paragraph/action). */
  value?: unknown;
  label?: string;
  description?: string;
  hint?: string;
  placeholder?: string;
  prefixIcon?: string;
  suffixIcon?: string;
  prefix?: string;
  suffix?: string;
  class?: Record<string, boolean> | string;
  style?: Record<string, string> | string;
  optional?: boolean;
  onToggleOptional?: (enabled: boolean) => void;
  required?: boolean;
  readonly?: boolean;
  type: string;
  formAction?: TFormAction;
  name?: string;
  field?: FormFieldDef;
  options?: TFormEntryOptions[];
  maxLength?: number;
  autocomplete?: string;
  title?: string;
  level?: number;
  onRemove?: () => void;
  canRemove?: boolean;
  removeLabel?: string;
  arrayIndex?: number;
  path: string;
  valueHelp?: ValueHelpInfo;
  singularLabel?: string;
  inputId: string;
  errorId: string;
  descId: string;
  ariaDescribedBy?: string;
  currencyCode?: string;
  unitCode?: string;
  precisionScale?: number;
  scale?: number;
  hasAdornment?: boolean;
}
```

### `TAsComponentEmits<V>`

```typescript
interface TAsComponentEmits<_V = unknown> {
  (e: "action", name: string): void;
}
```

### `TAsChangeType`

```typescript
type TAsChangeType = "update" | "array-add" | "array-remove" | "union-switch";
```

### `TAsTypeComponents`

Required keys for built-in types plus an open index signature.

```typescript
type TAsTypeComponents = {
  text: Component;
  select: Component;
  radio: Component;
  checkbox: Component;
  paragraph: Component;
  action: Component;
  object: Component;
  array: Component;
  union: Component;
  tuple: Component;
  ref: Component;
  decimal: Component;
  number: Component;
  date: Component;
  datetime: Component;
  time: Component;
} & Record<string, Component>;
```

### `TAsUnionContext`

```typescript
interface TAsUnionContext {
  variants: FormUnionVariant[];
  currentIndex: Ref<number>;
  changeVariant: (index: number) => void;
}
```

### `TAsCollapsibleProps`

Exported. Public props contract for the standalone [`AsCollapsible`](#ascollapsible)
section component — see that entry for the annotated interface.

### `TAsCollapsibleSlots`

Exported. Slot contract for `AsCollapsible`: `title-extras`, `badges`,
`actions`, `body`, `empty` — every header slot renders inside `<summary>`.

```typescript
interface TAsCollapsibleSlots {
  "title-extras"(): unknown;
  badges(): unknown;
  actions(): unknown;
  body(): unknown;
  empty(): unknown;
}
```

## Other types

### `TFormState` / `TFormRule` / `TFormFieldCallbacks` / `TFormFieldRegistration`

Internal-ish but exported for advanced wrappers building their own field renderer. `TFormRule` is the per-field validator signature:

```typescript
type TFormRule<TValue, TFormData, TContext> = (
  value: TValue,
  data: TFormData,
  context: TContext,
) => true | string;
```

### Re-exports from `@atscript/ui`

`setDefaultClientFactory`, `getDefaultClientFactory`, `resetDefaultClientFactory`, `ClientFactory` — see [@atscript/ui — Client factory](/api/ui#client-factory).

## Cross-links

- [Forms — Hello World](/forms/hello-world)
- [Forms — Annotations Reference](/forms/annotations)
- [Forms — Field Types & Type Map](/forms/field-types)
- [Forms — Validation](/forms/validation)
- [Forms — Arrays](/forms/arrays), [Nested Objects](/forms/nested-objects), [Unions](/forms/unions), [Tuples](/forms/tuples)
- [Forms — Dynamic Fields](/forms/dynamic-fields)
- [Forms — Grid Layout](/forms/grid-layout)
- [Forms — Actions](/forms/actions)
- [Forms — References (FK)](/forms/references)
- [Forms — Three Levels of Override](/forms/customization), [Custom Components](/forms/custom-components), [Locale & Currency](/forms/locale)
- [@atscript/ui](/api/ui), [@atscript/ui-fns](/api/ui-fns)


---
URL: "ui.atscript.dev/api/vue-table"
LLMS_URL: "ui.atscript.dev/api/vue-table.md"
---

# @atscript/vue-table

Vue 3 smart table powered by `@atscript/ui` + `@atscript/ui-table`. Tier-1 primary components (`AsTableRoot`, `AsTable`, `AsWindowTable`, `AsFilters`, `AsPresetPicker`, `AsTableActions`) are tagged in templates; Tier-2 defaults (cells, dialogs, header cells, filter UI) are swapped via the `controls` / `types` / `components` prop maps. A single `useTable()` call returns a `ReactiveTableState` that every Vue piece subscribes to.

## Contents

- [Tier 1 — Primary components](#tier-1-primary-components)
- [Tier 2 — Cells](#tier-2-cells)
- [Tier 2 — Dialogs](#tier-2-dialogs)
- [Tier 2 — Filter UI](#tier-2-filter-ui)
- [Tier 2 — Headers & rows](#tier-2-headers-rows)
- [Composables — table root](#composables-table-root)
- [Composables — state contracts](#composables-state-contracts)
- [Composables — features](#composables-features)
- [Composables — presets](#composables-presets)
- [Factories](#factories)
- [Types](#types)
- [Utilities](#utilities)

## Tier 1 — Primary components

### `AsTableRoot`

Sets up `useTable()` once, provides the context, and renders the table chrome. Most apps tag this at the page level.

**Props** (excerpt — see [`UseTableOptions`](#composables-table-root) for the full reactive surface):

```typescript
interface AsTableRootProps {
  url: string;
  limit?: number;
  rowValueFn?: (row: Record<string, unknown>) => unknown;
  selectionPersistence?: "clear" | "trim" | "persist";
  forceFilters?: FilterExpr;
  forceSorters?: SortControl[];
  /** Leaf paths always added to `$select`, regardless of visible columns — for headless cell renderers. */
  alwaysSelected?: string[];
  queryFn?: (
    query: Uniquery,
    page: number,
    size: number,
  ) => Promise<PageResult<Record<string, unknown>>>;
  queryOnMount?: boolean;
  blockQuery?: boolean;
  blockSize?: number;
  dragReleaseDebounceMs?: number;
  clientFactory?: ClientFactory;
  controls?: TAsTableControls;
  types?: TAsCellTypeComponents;
  components?: Record<string, Component>;
  formTypes?: TAsTypeComponents;
  formComponents?: Record<string, Component>;
  preset?: PresetConfig;
  refreshOnAction?: boolean;
  urlQuerySync?: UrlQuerySync;
}
```

**v-models**: `urlQuery` (string), `filterFields` (string[]), `columnNames` (string[]), `columnWidths` (ColumnWidthsMap), `sorters` (SortControl[]), `selectedRows` (unknown[]).

**Emits**: `action(action, ids, result, event?)`, `main-action(row, absIndex, event)`.

**Slot props** (default slot, bound from `state`): `tableDef`, `loadingMetadata`, `metadataError`, `allColumns`, `columnNames`, `columnWidths`, `columns`, `filterFields`, `filters`, `sorters`, `results`, `querying`, `queryingNext`, `totalCount`, `loadedCount`, `pagination`, `queryError`, `mustRefresh`, `searchTerm`, `selectedRows`, `selectedCount`, `navBridge`, `query`, `queryNext`, `resetFilters`, `showConfigDialog`, `openFilterDialog`, `closeFilterDialog`, `setFieldFilter`, `removeFieldFilter`, `addFilterField`, `removeFilterField`, `actions`, `prompt`.

### `AsTable`

Paginated table renderer. Subscribes to `useTableContext()`. Use inside `<AsTableRoot>` or supply your own context.

```typescript
interface AsTableProps {
  rows?: Record<string, unknown>[];
  columns?: ColumnDef[];
  stickyHeader?: boolean;
  virtualRowHeight?: number;
  virtualOverscan?: number;
  columnMenu?: ColumnMenuConfig;
  reorderable?: boolean;
  resizable?: boolean;
  columnMinWidth?: number;
  /** Selection mode: "none" | "single" | "multi". */
  select?: SelectionMode;
  /** Row-delete opt-in. */
  rowDelete?: boolean | RowDeleteOpt;
  /**
   * Synthesised row-actions pseudo-column. `'first'` / `'last'` prepend or
   * append a fixed `__actions` column; `'merge-select'` only renders when
   * `select === 'none'` so the row gutter shares space with the multi-select
   * checkbox column. `false` (default) hides the column entirely.
   */
  rowActionsColumn?: "first" | "last" | "merge-select" | false;
}
```

**Emits**: `row-click(row, event)`, `row-dblclick(row, event)`, `main-action(row, absIndex, event)`.

### `AsWindowTable`

Windowed (virtualized) renderer for million-row datasets. Uses `planFetch` / page-aligned blocks under the hood. Same props as `AsTable` plus `rowHeight?: number`.

### `AsFilters`

Renders the active-filters bar. Reads `state.filterFields` and `state.filters`, emits writes through the same refs.

### `AsTableActions`

Toolbar action row. Reads `state.actions` and renders default/other actions per level. Slot-customizable.

### `AsPresetPicker`

Dropdown picker showing the active preset, the system presets, the user's saved presets, and the favorite row. Backed by `state.preset`.

## Tier 2 — Cells

Default cell renderers — all implement the standard cell-props contract (path, value, row, column, locale).

| Component          | Default cell type                          | Notes                                                     |
| ------------------ | ------------------------------------------ | --------------------------------------------------------- |
| `AsTableCellValue` | `text`, `number`, `boolean`, `enum`, `ref` | Generic value renderer with locale + value-help labels.   |
| `AsCellNumber`     | `number` (when used explicitly)            | Decimal-aware numeric cell.                               |
| `AsCellDate`       | `date`, `datetime`, `relative`             | Locale-aware date renderer.                               |
| `AsCellArray`      | `array`                                    | Pill chips for array values.                              |
| `AsCellJson`       | `object`                                   | Collapsible JSON renderer.                                |
| `AsCellUnion`      | unions                                     | Per-row dispatcher that renders the active union variant. |

Imports:

```typescript
import {
  AsTableCellValue,
  AsCellNumber,
  AsCellDate,
  AsCellArray,
  AsCellJson,
  AsCellUnion,
} from "@atscript/vue-table";
```

## Tier 2 — Dialogs

### `AsConfigDialog`

Tabbed config dialog (columns / filters / sorters). Open via `state.configDialogOpen = true`.

### `AsFilterDialog`

Per-column filter editor. Open via `state.filterDialogColumn = column`.

### `AsPresetDialog`

Manage saved presets — rename, delete, public toggle, favorite, default.

### `AsConfirmDialog`

Pure confirm dialog driven by `state.prompt(message, opts?)`. Replaces `window.confirm()`.

### `AsActionFormDialog`

Dialog for actions that declare an `@InputForm` schema. Opens via `state.requestActionInput(action, ctx)`. Pulls in the full `@atscript/vue-form` runtime, so it is **not** exported from the main entry — `<AsTableRoot>` lazy-mounts it only when an `@InputForm` action is detected. Import from the dedicated subpath when you need to override or eager-load:

```typescript
import AsActionFormDialog from "@atscript/vue-table/as-action-form-dialog";
```

## Tier 2 — Filter UI

### `AsFilterField`

Single column's filter row inside the filter dialog or active-filters bar.

### `AsFilterInput`

Input control for one condition — switches between text / number / date / boolean / ref based on column type.

## Tier 2 — Headers & rows

### `AsTableHeaderCell`

Default header cell — label, sort indicator, resize handle, column menu trigger.

### `AsColumnMenu`

Dropdown menu shown on header click — sort, filter, hide, reset width. Configurable via `ColumnMenuConfig`.

### `AsRowActions`

Per-row actions cell — single button or `…` dropdown.

## Composables — table root

### `useTable(url, opts?)`

Main entry point. Resolves table metadata, builds the `TableDef`, wires presets/drafts/selection, and returns the reactive state.

```typescript
function useTable(url: string, opts?: UseTableOptions): ReactiveTableState;
```

**`UseTableOptions`** (key fields):

```typescript
interface UseTableOptions {
  limit?: number;
  rowValueFn?: (row: Record<string, unknown>) => unknown;
  selectionPersistence?: "clear" | "trim" | "persist";
  filterFields?: Ref<string[]>;
  columnNames?: Ref<string[]>;
  columnWidths?: Ref<ColumnWidthsMap>;
  sorters?: Ref<SortControl[]>;
  selectedRows?: Ref<unknown[]>;
  forceFilters?: FilterExpr;
  forceSorters?: SortControl[];
  /** Leaf paths always added to `$select`, regardless of visible columns — see [Custom Cells](/tables/custom-cells). */
  alwaysSelected?: string[];
  queryFn?: QueryFn;
  queryOnMount?: boolean;
  blockQuery?: boolean;
  blockSize?: number;
  dragReleaseDebounceMs?: number;
  clientFactory?: ClientFactory;
  controls?: TAsTableControls;
  types?: TAsCellTypeComponents;
  components?: Record<string, Component>;
  formTypes?: TAsTypeComponents;
  formComponents?: Record<string, Component>;
  provideContext?: boolean;
  refreshOnAction?: () => boolean;
  onActionResolved?: (action, ids, result, event?) => void;
  urlQueryReady?: Ref<boolean>;
  onUrlQueryChange?: (urlString: string) => void;
  urlQuerySync?: UrlQuerySync;
  preset?: PresetConfig;
}
```

### `clearTableCache()`

Drops the shared `/meta` cache. Use after auth changes that invalidate server metadata.

## Composables — state contracts

### `useTableContext()` / `useTableContextOptional()`

Inject the context provided by `AsTableRoot` (or `provideTableContext`).

```typescript
interface TableContext {
  state: ReactiveTableState;
  client: Client;
  controls: TAsTableControls;
  types?: TAsCellTypeComponents;
  components?: Record<string, Component>;
  formTypes?: TAsTypeComponents;
  formComponents?: Record<string, Component>;
}

function useTableContext(): TableContext;
function useTableContextOptional(): TableContext | undefined;
```

### `createTableState(opts)`

Lower-level factory used by `useTable`. Returns `{ state, internals }`. Reach for this when building a custom root (e.g. a multi-table dashboard).

```typescript
function createTableState(opts: CreateTableStateOptions): {
  state: ReactiveTableState;
  internals: TableStateInternals;
};
```

### `createStaticTableState(opts)`

Builds a `ReactiveTableState` for static / in-memory data (no server, no `/meta`). Useful for stubs, demos, and unit tests.

```typescript
function createStaticTableState(opts: CreateStaticTableStateOptions): {
  state: ReactiveTableState;
  internals: TableStateInternals;
};
```

## Composables — features

### `useTableSelection(state, opts?)`

Wires the selection persistence policy onto an existing `state`. Called automatically by `useTable`; expose it for `createStaticTableState` consumers.

```typescript
type SelectionPersistence = "clear" | "trim" | "persist";

function useTableSelection(state: ReactiveTableState, opts?: { mode?: SelectionPersistence }): void;
```

### `useTableNavBridge()`

Returns the keyboard nav bridge for binding external inputs (custom search box, command palette).

```typescript
function useTableNavBridge(): TableNavBridge;

interface TableNavBridge {
  onKeydown: (event: KeyboardEvent, opts?: NavKeyOptions) => void;
  activeIndex: Ref<number>;
  setActive: (absIndex: number) => void;
  clearActive: () => void;
}
```

### `useTableFilter()`

Helpers for reading/writing the filter model from outside the dialog (toolbar chips, URL bridge, etc.).

### `useTableSearch()`

Search-term composable — reads/writes `state.searchTerm`, applies debouncing.

### `useTableActions()`

Returns `state.actions` (the full `TableActionsState`) from the closest `<AsTableRoot>` ancestor. Throws when called outside the provider tree.

```typescript
function useTableActions(): TableActionsState;
```

### `useTableUrlQuery(route, router, opts?)`

Bridge `<AsTableRoot v-model:url-query>` to vue-router. Owns the whole query string. Uses type-only imports of `Router` / `RouteLocationNormalizedLoaded` — no runtime dependency on `vue-router` is added to `@atscript/vue-table`.

```typescript
interface UseTableUrlQueryOptions {
  /** `"replace"` (default) or `"push"`. */
  mode?: "replace" | "push";
}

function useTableUrlQuery(
  route: RouteLocationNormalizedLoaded,
  router: Router,
  opts?: UseTableUrlQueryOptions,
): WritableComputedRef<string>;
```

```vue
<script setup>
import { useRoute, useRouter } from "vue-router";
import { useTableUrlQuery } from "@atscript/vue-table";
const urlQuery = useTableUrlQuery(useRoute(), useRouter());
</script>
<template>
  <AsTableRoot v-model:url-query="urlQuery" url="/db/products" />
</template>
```

### `useTableComponent(key, fallback)`

Resolve a single chrome skin-slot from the injected `controls` map, falling back to the supplied component when the consumer left that entry unset. `key` is one of the `TAsTableControls` keys (`headerCell`, `columnMenu`, `filterDialog`, etc.) — this is for chrome, not cell-type dispatch.

```typescript
function useTableComponent<K extends keyof TAsTableControls>(
  key: K,
  fallback: Component,
): Component;
```

### `provideCellLocale(source)` / `useCellLocale()`

Locale source for date / number cells. The provider takes a `MaybeRefOrGetter` so apps can wire it to `useAppPrefs` or to a global store without re-providing. The consumer side returns computed `locale` (falls back to `navigator.language`, then `"en-US"`) and `timezone` (`undefined` lets `Intl` pick the browser TZ).

```typescript
interface CellLocale {
  language?: string;
  timezone?: string;
}

function provideCellLocale(source: MaybeRefOrGetter<CellLocale | undefined>): void;
function useCellLocale(): {
  locale: ComputedRef<string>;
  timezone: ComputedRef<string | undefined>;
};
```

## Composables — presets

### `usePresets(options)`

Manages preset rows, userConf, capabilities, and the apply/save plumbing. `useTable` instantiates this internally when `preset` is configured; expose it for advanced consumers.

```typescript
interface UsePresetsOptions {
  url: string;
  app?: string;
  tableKey: string;
  clientFactory?: ClientFactory;
  systemPresets?: SystemPresetInput[];
}

interface UsePresetsReturn {
  presets: ShallowRef<AsPresetEntryRow[]>;
  userConf: ShallowRef<AsPresetEntryRow | null>;
  capabilities: Ref<PresetCapabilities | null>;
  systemPresets: ComputedRef<SystemPreset[]>;
  available: ComputedRef<boolean>;
  saveActive: () => Promise<void>;
  saveAs: (label: string, opts?: { aspects?: AspectMask; public?: boolean }) => Promise<string>;
  rename: (id: string, label: string) => Promise<void>;
  remove: (id: string) => Promise<void>;
  togglePublic: (id: string) => Promise<void>;
  setDefault: (id: string | null) => Promise<void>;
  toggleFav: (id: string) => Promise<void>;
  setFavorites: (ids: string[]) => Promise<void>;
  batch: <T>(fn: () => Promise<T>) => Promise<T>;
}
```

`apply` is not on `usePresets` — it lives on the wired `state.preset` surface (`PresetSurface`) and accepts a system id (`sys:*`), a stored row id, or a raw `PresetSnapshot`. Bypassing it and writing the underlying model arrays directly works too — the root watcher reacts either way.

### `useAppPrefs(options)`

Manages the `appConf` row (app-wide user prefs: appearance, density, locale). Calls with the same `(app, url)` share a single underlying instance — duplicate widgets make one `/query?type=appConf` request total. Cross-tab sync rides BroadcastChannel; in-window sync rides a `useEventBus`.

```typescript
interface UseAppPrefsOptions {
  /** App namespace; defaults to `inject(AS_PRESETS_APP)`. */
  app?: string;
  /** Presets controller URL, e.g. `"/db/_presets"`. */
  url: string;
  clientFactory?: ClientFactory;
  /** Auto-load on setup. Default `true`. */
  autoLoad?: boolean;
  /** Cache most recent prefs in `localStorage` keyed by app. Default `true`. */
  cache?: boolean;
}

interface UseAppPrefsReturn {
  /** Reactive prefs. Always non-null; defaults to `{}` until first load resolves. */
  prefs: WritableComputedRef<AppConfData>;
  loading: Ref<boolean>;
  /** Last non-auth error, or `null`. Auth errors flip `available` instead. */
  error: Ref<unknown>;
  /** False on 401/403 from initial load — hide pref-bound controls. */
  available: ComputedRef<boolean>;
  reload(): Promise<void>;
  /** Optimistic shallow-merge save; rolls back on error. */
  save(patch: Partial<AppConfData>): Promise<void>;
  reset(): void;
}
```

### `useLocalDraft(options)`

localStorage overlay manager for table preset drafts. One overlay per `(app, tableKey)`; switching presets clears it (the caller decides when to call `clear()`).

```typescript
interface UseLocalDraftOptions {
  app: string;
  tableKey: string;
  enabled: Ref<boolean> | boolean;
  availableAspects: readonly PresetAspect[];
  debounceMs?: number;
  storage?: StorageLike | null;
}

interface UseLocalDraftReturn {
  /** Layer the persisted draft (if any) on top of `applied`. */
  hydrate(applied: PresetSnapshot): PresetSnapshot;
  /**
   * Wire a debounced watcher that mirrors persisted aspects to localStorage.
   * Returns the unwatch handle.
   */
  watchAndPersist(
    currentSnapshot: () => PresetSnapshot,
    activePresetSnapshot: () => PresetSnapshot,
  ): () => void;
  clear(): void;
  readDraft(): PresetDraft | null;
}

interface StorageLike {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}
```

### `injectPresetsApp(override?)` / `AS_PRESETS_APP`

```typescript
const AS_PRESETS_APP: InjectionKey<string>;
function injectPresetsApp(override?: string): string;
```

`AS_PRESETS_APP` lets a parent component declare the active "app" id (multi-app deployments). `injectPresetsApp(override)` returns the override when provided, else falls back to the injected value or `'default'`.

## Factories

### `createDefaultControls()`

Returns a fresh `TAsTableControls` map pre-filled with the seven always-on Tier-2 defaults: `headerCell`, `columnMenu`, `filterInput`, `filterDialog`, `filterField`, `configDialog`, `confirmDialog`. The other six slots are intentionally **not** seeded: `rowActions` already falls back to the `types` map's `__actions` entry and then the built-in `AsRowActions` (set `controls.rowActions` only to override explicitly — it wins over the `types` entry); `fieldsSelector`, `sortersConfig`, and `filterValueHelp` default to internal (unexported) components resolved at their mount sites; `presetDialog` is lazy-mounted on first open; and `actionFormDialog` is lazy-loaded so it only pulls in `@atscript/vue-form` when an `@InputForm` action is detected.

You rarely need this helper for `:controls` — every dispatch site falls back to its built-in internally, and passing defaults wholesale statically bundles (and eager-mounts) the lazy dialogs. Pass only the entries you replace:

```typescript
function createDefaultControls(): TAsTableControls;

const controls = {
  filterDialog: MyFilterDialog,
};
```

### `createDefaultCellTypes()`

Returns a pre-built `TAsCellTypeComponents` map with `AsTableCellValue` for every built-in type.

```typescript
function createDefaultCellTypes(): TAsCellTypeComponents;
```

## Types

### `TAsTableControls`

Skin-slot override map for table chrome. Set any subset — unset slots fall back to defaults.

```typescript
interface TAsTableControls {
  headerCell?: Component;
  columnMenu?: Component;
  rowActions?: Component;
  filterInput?: Component;
  filterDialog?: Component;
  filterField?: Component;
  filterValueHelp?: Component;
  configDialog?: Component;
  fieldsSelector?: Component;
  sortersConfig?: Component;
  confirmDialog?: Component;
  actionFormDialog?: Component;
  presetDialog?: Component;
}
```

### `TAsCellTypeComponents`

```typescript
type TAsCellTypeComponents = {
  text: Component;
  number: Component;
  boolean: Component;
  date: Component;
  datetime?: Component;
  relative?: Component;
  array: Component;
  object: Component;
  enum: Component;
  ref: Component;
  __actions?: Component;
} & Record<string, Component>;
```

### `ReactiveTableState`

The full reactive state object. See the canonical definition in `packages/vue-table/src/types.ts`; the main slots are:

- **Metadata**: `tableDef`, `loadingMetadata`, `metadataError`.
- **Columns**: `columns`, `allColumns`, `columnNames`, `columnWidths`.
- **Filters / sorters / search**: `filters`, `filterFields`, `sorters`, `searchTerm`.
- **Results**: `results`, `windowCache`, `windowLoading`, `topIndex`, `viewportRowCount`, `totalCount`, `loadedCount`, `resultsStart`.
- **Pagination**: `pagination`.
- **Selection**: `selectedRows`, `selectedCount`, `rowValueFn`, `isPkSelected`.
- **Active row / nav**: `activeIndex`, `navMode`, `navViewportRowCount`, `hasMainActionListener`, `rowId`, `setActive`, `clearActive`, `toggleActiveSelection`, `requestMainAction`, `handleNavKey`, `registerMainActionListener`.
- **Errors**: `queryError`, `lastError`, `mustRefresh`.
- **Querying flags**: `querying`, `queryingNext`.
- **Actions namespace**: `actions: TableActionsState`.
- **Prompt / action-form**: `confirmRequest`, `prompt`, `acceptPrompt`, `dismissPrompt`, `actionFormRequest`, `requestActionInput`, `acceptActionForm`, `dismissActionForm`.
- **Presets namespace**: `preset: PresetSurface`.
- **URL bridge**: `applyUrlQuery`.

### `TableActionsState`

```typescript
interface TableActionsState {
  table: TVueTableActionInfo[];
  row: TVueTableActionInfo[];
  rows: TVueTableActionInfo[];
  default: {
    table?: TVueTableActionInfo;
    row?: TVueTableActionInfo;
    rows?: TVueTableActionInfo;
  };
  others: {
    table: TVueTableActionInfo[];
    row: TVueTableActionInfo[];
    rows: TVueTableActionInfo[];
  };
  cellRow: TVueTableActionInfo[];
  invoke: (
    action: TVueTableActionInfo,
    pk?: Record<string, unknown> | Record<string, unknown>[],
    opts?: InvokeOpts,
  ) => Promise<ActionResult>;
  invoking: ShallowRef<Set<string>>;
  lastResult: ShallowRef<Map<string, ActionResult>>;
}
```

### `ActionResult`

```typescript
type ActionResult =
  | { ok: true; kind: "backend"; data: unknown; message?: string }
  | { ok: true; kind: "navigate" }
  | { ok: true; kind: "custom"; dispatched: true }
  | { ok: true; kind: "remove"; data: TDbDeleteResult }
  | { ok: false; kind: "error"; error: ClientError | Error };
```

### `ColumnMenuConfig`

```typescript
interface ColumnMenuConfig {
  sort?: boolean;
  filters?: boolean;
  hide?: boolean;
  /** "Reset width" entry — shown only when current ≠ default. */
  resetWidth?: boolean;
}
```

### `RowDeleteOpt` / `InvokeOpts` / `NavKeyOptions` / `MainActionRequest` / `QueryErrorKind` / `TVueTableActionInfo`

```typescript
interface RowDeleteOpt {
  label?: string;
  icon?: string;
  confirm?: string;
  intent?: TDbActionInfo["intent"];
}

interface InvokeOpts {
  suppressRefresh?: boolean;
  event?: KeyboardEvent | MouseEvent;
  input?: unknown;
}

interface NavKeyOptions {
  enterAction?: "main-action" | "toggle-select" | "passthrough";
  mode?: SelectionMode;
}

interface MainActionRequest {
  row: Record<string, unknown>;
  absIndex: number;
  event: KeyboardEvent | MouseEvent;
}

type QueryErrorKind = "initial" | "query" | "queryNext" | "loadRange";

type TVueTableActionInfo = Omit<TDbActionInfo, "processor"> & {
  processor: TDbActionProcessor | "__remove";
};
```

### Re-exports from `@atscript/ui-table`

`ConfigTab`, `UrlQuerySync`, `AppConfData`, `AsPresetEntryRow`, `PresetAspect`, `PresetCapabilities`, `PresetData`, `PresetSnapshot`, `PresetSnapshotWire`, `SystemPreset`, `SystemPresetInput`, `UserConfData`, `PRESET_ASPECTS`, `STANDARD_PRESET_ID`, `SYSTEM_PRESET_PREFIX`, `isSystemPresetId`, `resolveSystemPresets`. See [@atscript/ui-table](/api/ui-table) for definitions.

### Re-exports from `@atscript/ui`

`setDefaultClientFactory`, `getDefaultClientFactory`, `resetDefaultClientFactory`, `ClientFactory`.

## Utilities

```typescript
function getColumnWidth(column: ColumnDef, widths: ColumnWidthsMap): string;
function getCellValue(row: Record<string, unknown>, path: string): unknown;
function formatCellValue(value: unknown, column: ColumnDef, opts?: { locale?: CellLocale }): string;
function extractIdentifier(
  row: Record<string, unknown>,
  preferredId: readonly string[],
): Record<string, unknown>;
```

`extractIdentifier` builds the identifier object sent with action invocations and URL `$1` substitution. Per `@atscript/db-client` invariant #11 the server rejects bare scalars — even single-field PK tables send `{ id: '...' }`.

## Cross-links

- [Tables — Hello World](/tables/hello-world)
- [Tables — Annotations Reference](/tables/annotations)
- [Tables — Query Function](/tables/query-function)
- [Tables — Filtering](/tables/filtering), [Sorting](/tables/sorting)
- [Tables — Pagination & Virtualization](/tables/pagination)
- [Tables — Cells](/tables/cells), [Custom Cells](/tables/custom-cells)
- [Tables — Config Dialog](/tables/config-dialog)
- [Tables — URL State](/tables/url-state)
- [Tables — Presets](/tables/presets), [Server-Side Presets](/tables/server-presets)
- [Tables — Actions & Selection](/tables/actions)
- [Tables — Slot Overrides & Swaps](/tables/customization)
- [@atscript/ui](/api/ui), [@atscript/ui-table](/api/ui-table)
- [@atscript/moost-ui-presets](/api/moost-ui-presets)


---
URL: "ui.atscript.dev/api/vue-wf"
LLMS_URL: "ui.atscript.dev/api/vue-wf.md"
---

# @atscript/vue-wf

Vue 3 client for the HTTP workflow loop. One component (`AsWfForm`) and one composable (`useWfForm`) that round-trip JSON-typed schemas with the server-side workflow runtime (see [`@atscript/moost-wf`](/api/moost-wf)). The server tells the client what to render and when the flow is done; the client renders via `@atscript/vue-form` and ships submissions back.

## Contents

- [Subpath](#subpath)
- [Component — AsWfForm](#component-aswfform)
- [Composable — useWfForm](#composable-usewfform)
- [Error resolution](#error-resolution)
- [Types](#types)

## Subpath

```typescript
// barrel
import { AsWfForm, useWfForm } from "@atscript/vue-wf";

// isolated component (for granular bundling)
import AsWfForm from "@atscript/vue-wf/as-wf-form";
```

`AsResolver()` from [`@atscript/ui-styles`](/api/ui-styles) auto-imports `AsWfForm`.

## Component — AsWfForm

Wraps `useWfForm` and `<AsForm>`. Owns the entire workflow lifecycle — start, render, submit, action, error, finished. Slot-customizable for loading / error / finished branches.

### Props

```typescript
interface AsWfFormProps {
  /** HTTP endpoint for the workflow trigger. */
  path: string;
  /** Workflow id to start (e.g. "auth/login"). */
  name: string;
  /** Initial input sent with the first POST. */
  input?: Record<string, unknown>;
  /**
   * Token transport.
   * - "body"   (default) — token travels inside the JSON envelope.
   * - "cookie" — token rides Set-Cookie / Cookie.
   * - "query"  — token read from the URL (for email magic links).
   */
  tokenTransport?: "body" | "cookie" | "query";
  /** Token parameter name. Default `"wfs"`. */
  tokenName?: string;
  /** Workflow id parameter name. Default `"wfid"`. */
  wfidName?: string;
  /** Additional `RequestInit` merged into every POST. */
  fetchOptions?: RequestInit;
  /** Custom fetch (e.g. for status-code bus hooks). Default `globalThis.fetch`. */
  fetch?: typeof fetch;
  /** Auto-start on mount. Default `true`. */
  autoStart?: boolean;
  /**
   * Pre-existing token to resume from — use when the token lives outside
   * `window.location.search` (Vue Router param, app state).
   */
  initialToken?: string;
  /** Type-to-component map for AsForm rendering. */
  types: TAsTypeComponents;
  /** First-validation strategy. */
  firstValidation?: TFormState["firstValidation"];
  /** Custom components map forwarded to AsForm. */
  components?: Record<string, Component>;
  /** Per-form value-help client factory. */
  clientFactory?: ClientFactory;
  /** Forwarded to `<AsForm>`. Suppress the root field's title only (the description still renders). */
  hideRootTitle?: boolean;
  /** Forwarded to `<AsForm>`. Suppress the default submit button. */
  hideSubmit?: boolean;
  /**
   * Forwarded to `<AsWfFinish>`. Invoked with the redirect target URL when a
   * `redirect` action fires. Pairs with `@atscript/db-client`'s
   * `Client({ navigate })` so one handler covers both.
   */
  navigate?: (url: string) => void | Promise<void>;
}
```

### Emits

```typescript
{
  finished: (response: unknown) => void;
  error:    (error: { message: string; status?: number }) => void;
  form:     (def: FormDef, context?: Record<string, unknown>) => void;
  submit:   (data: unknown) => void;
  loading:  (isLoading: boolean) => void;
  // Fired by the default AsWfFinish screen — see Finish Screens.
  dismiss:  () => void;
  action:   (action: WfActionRequest) => void;
}
```

### Slots

| Slot           | Scope                      | Purpose                                                                                                                                                                                        |
| -------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| default        | `{ form, state, actions }` | Wraps everything below — opt into a fully custom shell. `form` = `{ def, formData, formContext }`, `state` = `{ loading, error, finished, response }`, `actions` = `{ start, submit, retry }`. |
| `wf.loading`   | —                          | First-load placeholder (only fires before the first FormDef arrives).                                                                                                                          |
| `wf.error`     | `{ error, retry }`         | Transport / 4xx error. Renders both before a form loads AND as a banner above a mounted form.                                                                                                  |
| `wf.finished`  | `{ response, payload }`    | Terminal state. `payload` is the typed `WfFinished` envelope. See [Finish Screens](/workflows/finish-screens) for the `wf.finish.*` sub-slots.                                                 |
| `form.header`  | AsForm `slotProps` bag     | Form chrome above the fields.                                                                                                                                                                  |
| `form.before`  | AsForm `slotProps` bag     | Above the field tree.                                                                                                                                                                          |
| `form.after`   | AsForm `slotProps` bag     | Below the field tree.                                                                                                                                                                          |
| `form.error`   | bag + `message`, `dismiss` | AsForm's own form-level error banner (distinct from the transport-level `wf.error`).                                                                                                           |
| `form.submit`  | bag + `text`               | Replace the submit button.                                                                                                                                                                     |
| `form.footer`  | AsForm `slotProps` bag     | Below the submit row.                                                                                                                                                                          |
| `form.loading` | AsForm `slotProps` bag     | Contents of the loading overlay.                                                                                                                                                               |

The `form.*` slots are forwarded verbatim to the inner `<AsForm>`, so each
carries that component's unified `slotProps` bag — documented once in
[Forms — Slots & the slotProps bag](/forms/customization#slots-the-slotprops-bag).
The `wf.finish.*` sub-slots live on the [Finish Screens](/workflows/finish-screens)
page. For the narrative on every slot (with defaults and examples), see
[Client: AsWfForm](/workflows/client).

### Example

```vue
<script setup lang="ts">
import { AsWfForm } from "@atscript/vue-wf";
import { createDefaultTypes } from "@atscript/vue-form";

const types = createDefaultTypes();
</script>

<template>
  <AsWfForm
    path="/api/auth/flow"
    name="auth/login"
    :types="types"
    @finished="onLogin"
    @error="onError"
  >
    <template #wf.finished="{ payload }">
      <p>Welcome back, {{ payload?.data?.user?.email }}!</p>
    </template>
  </AsWfForm>
</template>
```

## Composable — useWfForm

The HTTP loop without the renderer. Call it from a custom component when you want fully bespoke chrome but the same round-trip semantics.

```typescript
function useWfForm(options: UseWfFormOptions): UseWfFormReturn;
```

### `UseWfFormOptions`

```typescript
interface UseWfFormOptions {
  path: string;
  name: string;
  input?: Record<string, unknown>;
  tokenTransport?: "body" | "cookie" | "query";
  tokenName?: string;
  wfidName?: string;
  fetchOptions?: RequestInit;
  fetch?: typeof fetch;
  autoStart?: boolean;
  initialToken?: string;
}
```

### `UseWfFormReturn`

```typescript
interface UseWfFormReturn {
  /** Current form schema. `null` when there is no inputRequired pause. */
  formDef: ShallowRef<FormDef | null>;
  /** Reactive form data container `{ value: domainData }`. Null between pauses. */
  formData: ShallowRef<Record<string, unknown> | null>;
  /** Whitelisted server context (`@wf.context.pass`). */
  formContext: ShallowRef<Record<string, unknown>>;
  /** Server-supplied field errors. */
  errors: ShallowRef<Record<string, string>>;
  /** Incremented on every schema change — use as `:key` on `<AsForm>` for clean remounts. */
  formKey: Ref<number>;
  loading: Ref<boolean>;
  finished: Ref<boolean>;
  response: ShallowRef<unknown>;
  error: ShallowRef<unknown>;

  /** Begin the workflow (or resume from `initialToken`). */
  start: (input?: Record<string, unknown>) => Promise<void>;
  /** Submit the current form payload. */
  submit: (data: unknown) => Promise<void>;
  /** Dispatch a stateless action (no form payload). */
  action: (name: string) => Promise<void>;
  /** Dispatch an action that ships partial form data. */
  actionWithData: (name: string, data: unknown) => Promise<void>;
  /** Re-issue the last request — used by the default error retry button. */
  retry: () => Promise<void>;
}
```

### Behaviour notes

- **Outlet pauses** (`{ sent: true }` / `{ outlet: 'email' }`) are treated as `finished` — the current client's role is done; someone else resumes via the token.
- **Re-validation** is detected by hashing the `inputRequired.payload`. Identical schemas keep the same FormDef and `formData` reference; new schemas force a remount via `formKey`.
- **AbortController** is created per request and cancelled when a newer request starts or the component unmounts — no race conditions during quick action chains.
- **`initialToken`** takes precedence over `tokenTransport: "query"` auto-detection so Router-level params win over query strings.

### Custom-shell example

```vue
<script setup lang="ts">
import { useWfForm } from "@atscript/vue-wf";
import { AsForm, createDefaultTypes } from "@atscript/vue-form";

const wf = useWfForm({ path: "/api/auth/flow", name: "auth/login" });
const types = createDefaultTypes();

function onSubmit(data: unknown) {
  wf.submit(data);
}
</script>

<template>
  <div v-if="wf.loading.value && !wf.formDef.value">Loading…</div>
  <p v-else-if="wf.finished.value">Done.</p>
  <AsForm
    v-else-if="wf.formDef.value && wf.formData.value"
    :key="wf.formKey.value"
    :def="wf.formDef.value"
    :form-data="wf.formData.value"
    :form-context="wf.formContext.value"
    :errors="wf.errors.value"
    :types="types"
    @submit="onSubmit"
  />
</template>
```

## Error resolution

When a request returns a non-2xx response, `error.value` is set to `{ message, status }`. The message is resolved from the response body in this priority order:

1. `body.message` — the human-readable application intent. This is what `HttpError(status, message)` ships as `body.message` across the Wooks/Moost stack.
2. `body.error` — fallback when `message` is absent. The workflow-trigger engine emits `{ error: "Invalid or expired workflow state" }` (and similar) when state tokens are consumed or expired — this clause picks those up.
3. A friendly message keyed off the HTTP status code — used when the body is missing, empty, or has neither field. Examples:
   - `401` → "You need to sign in to continue."
   - `403` → "You don't have permission to do that."
   - `410` → "This session has expired. Please start over."
   - `429` → "Too many requests. Please wait a moment and try again."
   - Unmapped 4xx → "Something went wrong with that request. Please try again."
   - Any 5xx → "Something went wrong on our end. Please try again in a moment."

`message` wins over `error` because, in a wooksjs `HttpError` envelope, `error` carries the HTTP reason phrase mechanically derived from the status (`"Forbidden"`, `"Conflict"`), while `message` carries the application's intended user-facing copy.

`error.value.status` is the HTTP status code regardless of which clause supplied the message. Network failures (no response, non-`AbortError` exceptions) surface as `{ message }` with no `status` field.

## Types

`UseWfFormOptions` and `UseWfFormReturn` are exported from the package root. Re-export `FormDef` / `TAsTypeComponents` / `ClientFactory` from their owning packages — `@atscript/vue-wf` only re-exports its own surface.

## Cross-links

- [Workflows — Overview](/workflows/)
- [Workflows — Hello World](/workflows/hello-world)
- [Workflows — Server Authoring](/workflows/server-authoring)
- [Workflows — Form Input](/workflows/form-input)
- [Workflows — Actions](/workflows/actions), [Context Passing](/workflows/context)
- [Workflows — Outlets & Resume](/workflows/outlets-resume), [State Persistence](/workflows/state-persistence)
- [Workflows — AsWfForm](/workflows/client), [Recipes](/workflows/recipes)
- [@atscript/moost-wf](/api/moost-wf) — server runtime
- [@atscript/vue-form](/api/vue-form) — underlying form renderer


---
URL: "ui.atscript.dev/forms"
LLMS_URL: "ui.atscript.dev/forms.md"
outline: "deep"
---

# Forms

`@atscript/vue-form` renders Vue 3 forms directly from an annotated `.as`
type. You write the type once — labels, defaults, validation, layout,
field components and submit text all flow from the same source of truth.
No render boilerplate, no field-by-field wiring, no schema duplication
between the form and the API contract that consumes it.

## Mental model

The pipeline is three short steps:

```text
.as type  →  FormDef  →  <AsForm>
 (source)    (parsed)    (rendered)
```

1. **`.as` type.** A normal atscript interface decorated with `@meta.*`,
   `@expect.*`, `@ui.form.*` and optionally `@ui.form.fn.*` (dynamic).
   See [atscript.dev](https://atscript.dev) for the language; see
   [Annotations](/forms/annotations) for everything vue-form reads.

2. **`createAsFormDef(MyType)`.** A one-liner that parses the type into
   a framework-agnostic `FormDef` (from `@atscript/ui`) and returns a
   reactive `formData` container shaped as `{ value: domainData }`.

3. **`<AsForm :def :form-data :types @submit>`.** The Tier-1 component.
   It walks the FormDef and dispatches each field to a Vue component
   from the `types` map (defaults + your overrides).

## Component tiers

Every component in `vue-form` lives in one of three tiers (see
`CLAUDE.md`):

- **Tier 1 — Primary.** What users tag in templates: `AsForm`,
  `AsField`, `AsIterator`, and `AsCollapsible` (the auto-resolved
  section-chrome component for custom layouts). Auto-resolved by
  `AsResolver()`.
- **Tier 2 — Defaults.** Swappable via `:types` or `:components`:
  `AsInput`, `AsNumber`, `AsDecimal`, `AsSelect`, `AsRadio`,
  `AsCheckbox`, `AsDate`, `AsDatetime`, `AsTime`, `AsParagraph`,
  `AsAction`, `AsObject`, `AsArray`, `AsUnion`, `AsTuple`, `AsRef`,
  `AsFieldShell`. Importable from `@atscript/vue-form`, not
  auto-imported.
- **Tier 3 — Internals.** Composition helpers. Not exported.

You will spend most of your time in Tier 1 + annotations. Reach for
Tier 2 when you want to replace a default renderer; reach for the
`types` map when you want to register a brand-new field type.

## Where to go next

- [Hello World](/forms/hello-world) — a full working form in 25 lines.
- [Annotations](/forms/annotations) — the authoritative reference for
  every `@meta.*`, `@expect.*`, `@ui.form.*` and `@ui.form.fn.*` key
  vue-form reads.
- [Field Types](/forms/field-types) — the default type map and how
  component resolution works.
- [Validation](/forms/validation) — `@expect.*`, custom rules, external
  errors, fresh-field strategies.
- [Arrays](/forms/arrays), [Nested Objects](/forms/nested-objects),
  [Unions](/forms/unions), [Tuples](/forms/tuples) — structured fields.
- [Dynamic Fields](/forms/dynamic-fields) — `@ui.form.fn.*` JS
  expressions (requires `@atscript/ui-fns`).
- [Grid Layout](/forms/grid-layout), [Actions](/forms/actions),
  [References](/forms/references) — layout, submit/server actions, FK
  pickers.
- [Customization](/forms/customization),
  [Custom Components](/forms/custom-components),
  [Locale](/forms/locale) — make it yours.
- [Collapsible Sections](/forms/collapsible-sections) — wrap a custom
  component in `AsObject`'s section chrome with your own header actions, and
  full-bleed section dividers to a padded card's edges (`--as-inset`).
- [Aooth Components](/forms/aooth-components) — pre-built field
  components for consent collection, password rules, QR-code enrolment,
  one-shot copy values and SSO/social-login provider picking, shipped by
  `@atscript/vue-aooth`.

::: tip Related ecosystem docs
The `.as` language, `asc` CLI, `@meta.*`, `@expect.*` and validators
live in the [atscript core docs](https://atscript.dev). The `@db.*`
annotations (FK, currency, units, precision) are covered in the
[atscript-db docs](https://db.atscript.dev). vue-form reads several
of them too — see [References](/forms/references) and
[Annotations](/forms/annotations#db-annotations-cross-cutting).
:::


---
URL: "ui.atscript.dev/forms/actions"
LLMS_URL: "ui.atscript.dev/forms/actions.md"
---

# Actions

Forms ship with a single Submit button by default. To add extra buttons —
"Save draft", "Discard", "Send for review", workflow step transitions — declare
them as **phantom fields** annotated with `@ui.form.action`. The form renders a
button per action and emits an `action` event when the user clicks it. No data
is collected for these fields.

## The annotation

```atscript
@ui.form.action 'actionId', 'Button label'
fieldName: ui.action
```

- `'actionId'` is the id emitted back to the host.
- `'Button label'` is the rendered text.
- The `ui.action` primitive marks the field as a phantom — no value is stored
  on `formData`, no validator runs.

## Listen with `@action`

`<AsForm>` emits `action` with the id and the current form data:

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { OrderForm } from "./order-form.as";

const { def, formData } = createAsFormDef(OrderForm);
const types = createDefaultTypes();

function onAction(name: string, data: unknown) {
  if (name === "save-draft") saveDraft(data);
  if (name === "discard") resetForm();
}

function onSubmit(data: unknown) {
  submitOrder(data);
}
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" @submit="onSubmit" @action="onAction" />
</template>
```

The `action` event signature is `(name: string, data: TFormData) => void` —
see `useAsForm`'s emits contract in
`packages/vue-form/src/composables/use-as-form.ts`.

## Multi-action form

```atscript
@meta.label 'Order'
export interface OrderForm {
    @meta.label 'Item'
    item: string

    @meta.label 'Quantity'
    quantity: number

    @ui.form.action 'save-draft', 'Save draft'
    saveDraft: ui.action

    @ui.form.action 'discard', 'Discard'
    discard: ui.action
}
```

Submit still works as usual. The phantom action fields render as additional
buttons inline with the form. Use grid annotations to control their placement:

```atscript
@ui.form.action 'save-draft', 'Save draft'
@ui.form.grid.colSpan '6'
saveDraft: ui.action

@ui.form.action 'discard', 'Discard'
@ui.form.grid.colSpan '6'
discard: ui.action
```

## Placing actions below the submit button

Action fields render in the form grid **above** the submit button by default, in
declaration order. Add `@ui.form.pushDown` to move a field into its own grid
**below** the submit button instead — the classic "Already have an account?
Sign in" affordance under a sign-up button. Pushed-down fields keep the same
12-column grid, so `@ui.form.order` and `@ui.form.grid.*` apply there too.

```atscript
@meta.label 'Create account'
@ui.form.submit.text 'Create account'
export interface SignUpForm {
    @meta.label 'Email'
    email: string.email

    @meta.label 'Password'
    @ui.type 'password'
    password: string

    @ui.form.pushDown
    @ui.form.attr 'text', 'Already have an account?'
    @ui.form.attr 'align', 'center'
    @ui.form.action 'sign-in', 'Sign in'
    signIn: ui.action
}
```

### Alt-action text and alignment

The default `AsAction` reads two optional props off `@ui.form.attr`, which
forwards arbitrary name/value pairs to the field component:

| `@ui.form.attr`                          | Effect                                                |
| ---------------------------------------- | ----------------------------------------------------- |
| `'text', 'Already have an account?'`     | Text rendered before the action link → `text [link]`. |
| `'align', 'left' \| 'center' \| 'right'` | Alignment of the text + link row. Defaults to `left`. |

`text` / `align` apply to `ui.action` phantom fields (rendered by `AsAction`),
not to the inline-on-input variant below. `@ui.form.pushDown` only controls
_where_ a field renders, not _how_ — combine the two for the centred,
below-submit sign-in link shown above.

These annotations carry into `<AsWfForm>` unchanged: workflow forms render
through `<AsForm>`, and `@atscript/moost-wf` serializes `@ui.form.pushDown` /
`@ui.form.attr` over the HTTP round-trip, so a pushed-down centred alt-action
behaves identically server-driven.

## Inline action on an input field

`@ui.form.action` may also sit on a regular input field (string, password,
number, …) instead of a `ui.action` phantom. It then renders as a link-styled
button in the field's footer, right-aligned next to any error or hint, and
emits the same `action` event. Disabling the field also dims the link.

Typical use — a "Forgot password?" link below a password input:

```atscript
@meta.label 'Sign In'
export interface LoginForm {
    @meta.label 'Username'
    username: string

    @meta.label 'Password'
    @ui.type 'password'
    @ui.form.action 'forgot-password', 'Forgot password?'
    password: string
}
```

In a workflow form (`<AsWfForm>`), the action is forwarded to
`useWfForm().action(id)` and resolved server-side via `@WfAction(Form)`
from `@atscript/moost-wf`:

```ts
@Step("login-credentials")
async enterCredentials(
  @WorkflowParam("context") ctx: LoginCtx,
  @WfAction(LoginForm) action: string | undefined,
  @WfInput({ pass: true }) input?: LoginForm,
) {
  if (action === "forgot-password") {
    ctx.recovery = true;
    return;
  }
  // …normal credential flow
}
```

## Customising the Submit button

The Submit button is rendered by `<AsForm>` itself (not a phantom field). Two
annotations on the root interface customise it:

```atscript
@meta.label 'Registration'
@ui.form.submit.text 'Register'
@ui.form.fn.submit.disabled '(data) => !data.email'
export interface Registration { ... }
```

- `@ui.form.submit.text` — static label
- `@ui.form.fn.submit.text` — dynamic label (requires `@atscript/ui-fns`)
- `@ui.form.fn.submit.disabled` — dynamic disabled state

To suppress the built-in Submit button entirely (host chrome owns it):

```vue
<AsForm :def="def" :form-data="formData" :types="types" hide-submit />
```

Or override the slot:

```vue
<AsForm :def="def" :form-data="formData" :types="types">
  <template #form.submit="{ disabled, text }">
    <MyPrimaryButton type="submit" :disabled>{{ text }}</MyPrimaryButton>
  </template>
</AsForm>
```

## Unsupported actions

When the emitted action id doesn't match any `@ui.form.action` (or
`@wf.action.withData`) in the def, `<AsForm>` fires
`unsupported-action` instead of `action`. Useful as a no-op guard rail when
controllers refactor action ids.

```vue
<AsForm @action="onAction" @unsupported-action="(name) => console.warn('Unknown action:', name)" />
```

## Workflow actions

In a workflow form (`<AsWfForm>`, see [Workflows](/workflows/)),
`@wf.action.withData` is a workflow-aware variant of `@ui.form.action` that
includes the form data with the action invocation. It's recognised by the same
action-routing pipeline — see [Workflow actions](/workflows/actions) for the
full picture.

## The AsAction component

The default `AsAction` component (Tier 2 swap target) is intentionally minimal:
an optional prefix `text`, then a `<button type="button">` that emits `action`
with its `formAction.id`. The link styling (`as-field-action-link`) sits on the
button itself, so its hover/focus underline stays scoped to the link — not the
whole row — and the row's `align` (left by default) positions it. Swap the
component through the `:types` map to use your design system's button:

```vue
<script setup lang="ts">
import { createDefaultTypes } from "@atscript/vue-form";
import MyActionButton from "./MyActionButton.vue";

const types = { ...createDefaultTypes(), action: MyActionButton };
</script>
```

The custom component receives the standard `TAsComponentProps` contract —
inspect `formAction` for the id and label, and emit `'action'` with the id:

```vue
<script setup lang="ts">
import type { TAsComponentProps, TAsComponentEmits } from "@atscript/vue-form";

defineProps<TAsComponentProps>();
const emit = defineEmits<TAsComponentEmits>();
</script>

<template>
  <button type="button" class="c8-light" @click="formAction && emit('action', formAction.id)">
    {{ formAction?.label }}
  </button>
</template>
```

See [Custom field components](/forms/custom-components) for the full
`TAsComponentProps` contract.

## Next steps

- [Customization](/forms/customization) — override `AsAction` globally
- [Dynamic fields](/forms/dynamic-fields) — `@ui.form.fn.submit.disabled` and friends
- [Workflow actions](/workflows/actions) — `@wf.action.withData` for partial-data flows


---
URL: "ui.atscript.dev/forms/annotations"
LLMS_URL: "ui.atscript.dev/forms/annotations.md"
outline: "deep"
---

# Annotations Reference

This is the authoritative list of every annotation `@atscript/vue-form`
reads. Keep it open while you write `.as` types — most form questions
("how do I hide this field on weekends?", "how do I add a prefix `$`
to a price input?") resolve to "find the right annotation key".

Annotations come from three families:

- **`@meta.*`** and **`@expect.*`** — defined by atscript core. vue-form
  reads them; the language defines them. Full reference at
  [atscript.dev](https://atscript.dev).
- **`@ui.form.*`** — static UI configuration, defined by `@atscript/ui`.
- **`@ui.form.fn.*`** — dynamic JS-expression equivalents of the static
  keys. Require [`@atscript/ui-fns`](/forms/dynamic-fields) to evaluate.
- **`@ui.type`** — cross-cutting render-type override.
- **`@db.*`** — defined by `@atscript/db`. vue-form reads a few of them
  for measurement adornments and FK pickers. See
  [db.atscript.dev](https://db.atscript.dev).

Annotation key constants live in `packages/ui/src/plugin/*.ts` — every
table below pairs the `.as` syntax with the underlying string key so
you can grep the source.

## `@meta.*` — semantics

Defined by the atscript core (`@atscript/typescript`). These describe
**what the field means**, independent of how it's rendered.

| Annotation              | Arg    | Effect in vue-form                                                             |
| ----------------------- | ------ | ------------------------------------------------------------------------------ |
| `@meta.label 'X'`       | string | Field title / structured-section title; on the type itself it titles the form. |
| `@meta.description 'X'` | string | Help text rendered below the field label.                                      |
| `@meta.default 'X'`     | string | Default value applied by `createFormData` at form mount.                       |
| `@meta.required 'msg'`  | string | Marks the field required + supplies the validation error message.              |
| `@meta.readonly`        | flag   | Renders read-only; value can still be set programmatically.                    |
| `@meta.id`              | flag   | Marks the identity field (used by atscript-db and AsRef pickers).              |
| `@meta.sensitive`       | flag   | Hint to consumers that the value is sensitive (passwords, tokens).             |

Example:

```atscript
@meta.label 'Age'
@meta.required 'Age is required'
@meta.default '18'
age: number
```

See [atscript.dev — Annotations](https://atscript.dev) for the full
list of meta annotations the language ships with.

## `@expect.*` — validation

Defined by atscript core. `vue-form` runs them through the standard
atscript validator (`getFormValidator(def)`) — no extra wiring on the
Vue side.

| Annotation                      | Effect                            |
| ------------------------------- | --------------------------------- |
| `@expect.min N, 'msg'`          | numeric lower bound               |
| `@expect.max N, 'msg'`          | numeric upper bound               |
| `@expect.minLength N, 'msg'`    | string / array length lower bound |
| `@expect.maxLength N, 'msg'`    | string / array length upper bound |
| `@expect.pattern '/re/', 'msg'` | regex match                       |

On arrays, `@expect.minLength` and `@expect.maxLength` also drive the
`canAdd` / `canRemove` toggles on the rendered `AsArray` — see
[Arrays](/forms/arrays).

```atscript
@meta.label 'Username'
@meta.required 'Username is required'
@expect.minLength 3, 'Must be at least 3 characters'
@expect.maxLength 20, 'Must be at most 20 characters'
username: string
```

## `@ui.type` — built-in renderer override

The cross-surface render-type override. Flips which **built-in**
renderer a field uses on whichever surface lacks its own override
(`@ui.form.type` for forms, `@ui.table.type` for tables). The value
must be one of the built-in type ids that the form/cell type maps
know how to dispatch — `text`, `password`, `textarea`, `number`,
`decimal`, `select`, `radio`, `checkbox`, `multiselect`, `paragraph`,
`action`, `date`, `datetime`, `time`, etc.

For primitives it folds into the field's structural `type` at
FormDef-build time; for structured fields (`object`, `array`, `union`,
`tuple`) it lives in `customType` and is checked first in the lookup
(see `packages/vue-form/src/components/as-field.vue:373-386`).

```atscript
@ui.type 'password'
password: string

@ui.type 'select'
@ui.form.options 'admin' | 'user' | 'guest'
role: string

@ui.type 'textarea'
bio?: string
```

For **custom** renderers, use `@ui.form.component` (and
`@ui.table.component` on the table side) instead. Those routes look up
in the dedicated `:components` map — see
[Custom Components](/forms/custom-components) and
[Field Types](/forms/field-types).

## `@ui.form.*` — static UI config

The bulk of form customization lives here. Every key is **read once**
at field-setup time; values are inlined into the rendered component's
props. For values that depend on other field data, use the matching
`@ui.form.fn.*` key (next section).

### Display

| Annotation                      | Type   | Controls                                                                                                     |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ |
| `@ui.form.placeholder 'X'`      | string | input placeholder                                                                                            |
| `@ui.form.hint 'X'`             | string | inline hint below the input (overrides `meta.description` when both present and the field is in error state) |
| `@ui.form.label.singular 'tag'` | string | item-noun for arrays — drives "Add tag" / "Remove tag" buttons                                               |
| `@ui.form.submit.text 'X'`      | string | submit button text (on the type, not on a field)                                                             |

Field descriptions come from `@meta.description` — there is no
`@ui.form.description` static counterpart. For dynamic descriptions
use `@ui.form.fn.description` (see [Dynamic Fields](/forms/dynamic-fields)).

### Behaviour

| Annotation                      | Controls                                    |
| ------------------------------- | ------------------------------------------- |
| `@ui.form.hidden`               | hide field — phantom-renders, never visible |
| `@ui.form.disabled`             | disable input                               |
| `@ui.form.autocomplete 'email'` | sets HTML `autocomplete=` attribute         |

For read-only, use `@meta.readonly` — it is the single source of truth
that both forms and other surfaces read. For the dynamic counterpart
use `@ui.form.fn.readonly`.

### Layout

| Annotation                                                       | Controls                                             |
| ---------------------------------------------------------------- | ---------------------------------------------------- |
| `@ui.form.order N`                                               | sort order within siblings                           |
| `@ui.form.grid.colSpan 'full' \| 'half' \| 'third' \| '1'..'12'` | grid column width (12-col grid)                      |
| `@ui.form.grid.rowSpan '1'..'4'`                                 | grid row span                                        |
| `@ui.form.classes 'a b'`                                         | extra classes on the field wrapper                   |
| `@ui.form.styles { ... }`                                        | inline style object                                  |
| `@ui.form.attr { ... }`                                          | extra HTML attributes forwarded to the input element |

See [Grid Layout](/forms/grid-layout) for the 12-column grid and the
`full`/`half`/`third` aliases.

### Adornments

Read together to drive the merged prefix / suffix chrome inside
numeric and decimal inputs. See `as-field.vue:199-307` for the full
resolution chain.

| Annotation                                | Effect                                              |
| ----------------------------------------- | --------------------------------------------------- |
| `@ui.form.prefix '$'`                     | literal prefix string                               |
| `@ui.form.prefix.ref 'currency'`          | resolve prefix from a sibling field's current value |
| `@ui.form.prefix.icon 'icon-credit-card'` | render an icon glyph as the prefix                  |
| `@ui.form.suffix '%'`                     | literal suffix string                               |
| `@ui.form.suffix.ref 'unit'`              | resolve suffix from a sibling field                 |
| `@ui.form.suffix.icon 'icon-percent'`     | suffix icon glyph                                   |

Currency and unit values are also pulled from `@db.amount.currency*`
and `@db.unit*` — see [DB annotations](#db-annotations-cross-cutting)
below.

### Actions

| Annotation                                             | Effect                                                                                  |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `@ui.type 'action'`                                    | renders the field as an action button (uses `AsAction`)                                 |
| `@ui.form.action { id, label }`                        | declares the action's id + label; `AsForm` emits `action` with the form data when fired |
| `@ui.form.pushDown`                                    | render this field in its own grid **below** the submit button instead of above it       |
| `@ui.form.attr 'text', '…'`                            | on an action field — text rendered before the link (e.g. "Already have an account?")    |
| `@ui.form.attr 'align', 'left' \| 'center' \| 'right'` | on an action field — alignment of the text + link row (default `left`)                  |
| `@ui.form.submit.text 'Save'`                          | on the type itself — submit button text                                                 |

See [Actions](/forms/actions) for the action lifecycle, below-submit placement,
and how `AsWfForm` extends this with workflow round-trips.

### Choice fields

| Annotation                                 | Effect                                        |
| ------------------------------------------ | --------------------------------------------- |
| `@ui.form.options 'a' \| 'b' \| 'c'`       | static option list for `select` / `radio`     |
| `@ui.form.options [{ value, label }]`      | richer static option list (objects)           |
| `@ui.form.fn.options '(v, data) => [...]'` | dynamic options (requires `@atscript/ui-fns`) |

`@ui.form.options` accepts either a string-literal-union shorthand or
an explicit array. Inline string unions (`'admin' | 'user'` directly
on the field type) are extracted automatically — no
`@ui.form.options` needed:

```atscript
role: 'admin' | 'user' | 'guest'
```

The same option sources also feed the `multiselect` renderer on array
fields — see [Field Types — Multi-select arrays](/forms/field-types#multi-select-arrays)
for the dispatch rules.

### Custom validation

| Annotation                                       | Effect                                                                                               |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `@ui.form.validate '(v) => !!v \|\| "required"'` | custom validator expression (requires `@atscript/ui-fns`). Returns `true` on pass or a string error. |

The validator receives `(value, data, context)`. See
[Validation](/forms/validation).

### Component swap

| Annotation                     | Effect                                                                                                                                                                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@ui.form.type 'textarea'`     | Flips to a different **built-in** renderer (`text`, `password`, `textarea`, `number`, `decimal`, `select`, `radio`, `checkbox`, `multiselect`, `date`, `datetime`, `time`, `paragraph`, `action`). Reserved for built-ins. |
| `@ui.form.component 'MyInput'` | Resolves a **named** component from the `:components` map (highest precedence). The dedicated mechanism for custom renderers.                                                                                              |

Resolution precedence (see `as-field.vue:373-386`):

```text
@ui.form.component  →  components[name]
@ui.form.type       →  types[customType]
field.type          →  types[type]
```

`@ui.form.type` is preferred for structured types where you want the
type-map (so the swap also applies to nested same-typed fields);
`@ui.form.component` is preferred when you have a one-off swap or
multiple shapes of the same structural type that need different
renderers. See [Custom Components](/forms/custom-components).

## `@ui.form.fn.*` — dynamic UI config

Identical key namespace to `@ui.form.*` but the value is a JS
function expression. The expression is parsed and evaluated through
`@atscript/ui-fns` against a per-field scope:

```ts
type TFnScope = {
  v: unknown; // current field value
  data: Record<string, unknown>; // entire form domain data
  context: Record<string, unknown>; // form-level context
  entry: { type; component; name; optional; disabled; hidden; readonly };
};
```

Field-level (declared on a prop):

| Annotation                | Computes                                                                          |
| ------------------------- | --------------------------------------------------------------------------------- |
| `@ui.form.fn.label`       | label string                                                                      |
| `@ui.form.fn.description` | description string                                                                |
| `@ui.form.fn.hint`        | hint string                                                                       |
| `@ui.form.fn.placeholder` | placeholder string                                                                |
| `@ui.form.fn.hidden`      | boolean                                                                           |
| `@ui.form.fn.disabled`    | boolean                                                                           |
| `@ui.form.fn.readonly`    | boolean                                                                           |
| `@ui.form.fn.classes`     | class object / string                                                             |
| `@ui.form.fn.styles`      | style object                                                                      |
| `@ui.form.fn.attr`        | HTML attribute map                                                                |
| `@ui.form.fn.options`     | dynamic option list                                                               |
| `@ui.form.fn.value`       | derived value (readonly fields are auto-synced; phantom paragraph/action display) |

Top-level (declared on the root `interface` / `type`, receives `(data, context)`):

| Annotation                    | Computes                        |
| ----------------------------- | ------------------------------- |
| `@ui.form.fn.title`           | dynamic form title              |
| `@ui.form.fn.description`     | dynamic form description        |
| `@ui.form.fn.submit.text`     | dynamic submit button text      |
| `@ui.form.fn.submit.disabled` | dynamic submit-disabled boolean |

Example — hide a "Room" field when no Floor has been picked:

```atscript
@meta.label 'Room'
@ui.form.fn.hidden '(v, data) => !data.contact?.department?.floor'
room?: string
```

Full coverage in [Dynamic Fields](/forms/dynamic-fields).

::: warning Trade-offs
Every `@ui.form.fn.*` key on a field promotes it from the static
fast-path to the dynamic path (`as-field.vue:409` vs `:446`). The
dynamic path builds a reactive `TFnScope` per evaluation, so reach
for `fn.*` when the value depends on other form state and stick with
the static keys when it doesn't.
:::

## DB annotations (cross-cutting)

vue-form reads these even though they're defined by `@atscript/db`.
Use them on `.as` types that are shared between the form and the
database layer — you write the metadata once and both surfaces pick it
up. Full coverage at [db.atscript.dev](https://db.atscript.dev).

### Currency & units

| Annotation                                  | Effect on form                                                                            |
| ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `@db.amount.currency 'USD'`                 | hard-code the currency — drives `AsDecimal`'s prefix glyph + `Intl.NumberFormat` decimals |
| `@db.amount.currency.ref 'cur'`             | resolve currency from a sibling field at runtime                                          |
| `@db.unit 'kg'`                             | hard-code a measurement unit — drives suffix                                              |
| `@db.unit.ref 'unit'`                       | resolve unit from a sibling                                                               |
| `@db.column.precision { precision, scale }` | numeric precision/scale; `scale` caps the displayed decimals                              |

### Foreign keys (AsRef value-help)

| Annotation                       | Effect                                     |
| -------------------------------- | ------------------------------------------ |
| `@db.rel.FK 'OtherTable'`        | declares a foreign-key relation            |
| `@db.http.path '/api/customers'` | URL the `AsRef` picker queries for options |

When both are present the field renders an `AsRef` picker by default
(searchable, paged, server-driven). See [References](/forms/references).

## Cross-cutting reads

A few patterns you'll see again and again:

- **Optional + required** — `firstName?: string` with `@meta.required`
  means "if you provide it, you must provide a value". In practice
  vue-form treats this as not-required for the field marker (the `*`
  would mislead) — see `as-field.vue:167-181`.
- **Phantom fields** — fields with no input element (paragraphs,
  actions) read `@meta.default` (or `@ui.form.fn.value` dynamically) as
  the displayed value.
- **Order resolution** — `@ui.form.order` is numeric; ties fall through
  in declaration order. Mixing some-ordered + some-unordered fields
  works.

## Next steps

- [Field Types](/forms/field-types) — what each `@ui.type` value
  resolves to.
- [Validation](/forms/validation) — `@expect.*`, `@ui.form.validate`,
  external errors.
- [Dynamic Fields](/forms/dynamic-fields) — full coverage of
  `@ui.form.fn.*`.
- [References](/forms/references) — `@db.rel.FK` and value-help pickers.


---
URL: "ui.atscript.dev/forms/aooth-components"
LLMS_URL: "ui.atscript.dev/forms/aooth-components.md"
outline: "deep"
---

# Aooth-flavoured field components

`@atscript/vue-aooth` ships a small set of pre-built custom field components
used across [Aooth](https://aooth.moost.org) flows — multi-consent collection,
password-policy display, QR-code enrolment, one-shot link/token sharing, and
SSO / social-login provider picking.
All five implement the `TAsComponentProps` contract from
[`@atscript/vue-form`](/forms/custom-components) and drop into
`<AsForm :components>` via the `@ui.form.component` annotation.

None of them are auto-resolved — register each one by name in the components
map. The component name in the `.as` annotation is just a key into that map;
match whichever convention you prefer (`'AsConsentArray'`, `'consent-array'`,
`'consents'` — pick one, stay consistent).

```ts
import {
  AsConsentArray,
  AsCopy,
  AsPasswordRules,
  AsQrCode,
  AsSsoProviders,
} from "@atscript/vue-aooth";

const components = {
  "consent-array": AsConsentArray,
  copy: AsCopy,
  "password-rules": AsPasswordRules,
  "qr-code": AsQrCode,
  "sso-providers": AsSsoProviders,
};
```

Styles ship two ways. Pre-built CSS lives at
`@atscript/ui-styles/dist/css/aooth.css` — import it once at app start to get
the entire aooth bundle. Apps already running
[vunor](/styling/) pick the classes up through the runtime UnoCSS preset
without an extra import.

## AsConsentArray

Multi-consent checkbox group with per-item required validation and inline
markdown links. The bound value is `string[]`; checked ids are committed
in insertion order.

Source: `packages/vue-aooth/src/components/as-consent-array.vue`.

```ts
interface AsConsentArrayItem {
  id: string;
  text: string; // supports [label](url) for http(s)/mailto
  required?: string; // non-empty string ⇒ mandatory; doubles as the error message
}

interface AsConsentArrayProps extends TAsComponentProps<string[]> {
  pendingConsents?: AsConsentArrayItem[];
}
```

- Empty / missing `pendingConsents` hides the entire shell — useful for "show
  the legal block only when the backend has pending consents".
- Required misses surface their `required` string under the row; the shell
  footer is suppressed to avoid duplicate messaging.
- Only `http://`, `https://`, and `mailto:` link schemes render as anchors —
  anything else falls back to verbatim text.

```atscript
@ui.form.component 'consent-array'
@ui.form.fn.attr 'pendingConsents', '(v, data, ctx) => ctx.pendingConsents'
consents: string[]
```

The full server-driven flow lives in the API reference at
[@atscript/vue-aooth](/api/vue-aooth#component-asconsentarray).

## AsPasswordRules

Display-only readout of password-policy fulfilment. Pair it with a sibling
password field; the component re-evaluates on every keystroke and toggles each
row's met / unmet state via `data-passed="true" | "false"`.

Source: `packages/vue-aooth/src/components/as-password-rules.vue`.

```ts
interface AsPasswordRulesPolicy {
  rule: string; // function-string, evaluated through compileFieldFn
  description?: string;
  errorMessage?: string;
}

interface AsPasswordRulesProps extends TAsComponentProps {
  policies?: AsPasswordRulesPolicy[];
  password?: string;
}
```

- Rule strings reuse `@atscript/ui-fns`' `compileFieldFn` — the same FNPool
  cache the framework uses for `@ui.form.fn.*`. Two policies with the same
  rule body share one compiled instance.
- Empty password ⇒ every row reads as unpassed, even if a no-op rule would
  technically return true.
- Throwing rules are treated as unpassed and logged once per distinct source.

```atscript
@ui.form.type 'paragraph'
@ui.form.component 'password-rules'
@ui.form.fn.attr 'policies', '(v, data, ctx) => ctx.passwordPolicies'
@ui.form.fn.attr 'password', '(v, data) => data.newPassword'
passwordHints: string
```

See [@atscript/vue-aooth](/api/vue-aooth#component-aspasswordrules) for the
full reference and a worked example.

## AsQrCode

Phantom field that renders an SVG QR code from any string. Primarily used for
TOTP enrolment — for `otpauth://` URIs it also surfaces the `?secret=` query
param as a manual-entry fallback so users on devices that can't scan can type
the secret in by hand.

Source: `packages/vue-aooth/src/components/as-qr-code.vue`.

```ts
interface AsQrCodeProps extends TAsComponentProps<string | undefined> {
  size?: number; // SVG width in px, default 192
  errorCorrection?: "L" | "M" | "Q" | "H"; // default "M"
  manualSecret?: boolean; // default true — hide the secret fallback for non-otpauth use cases
}
```

- The value is read as `props.value ?? props.model?.value`. Phantom
  registrations (`ui.paragraph` + `@ui.form.fn.value`) push through
  `props.value`; data-bound fields use `model.value`.
- `qrcode` is an **optional peer dependency** — install it in the consumer app
  when you ship a flow that uses `AsQrCode`. The module is dynamic-imported,
  so apps without the dep don't pay the bundle cost.

```bash
npm install qrcode
```

```atscript
@meta.label 'Scan with your authenticator app'
@ui.form.fn.value '(v, data, ctx) => ctx.totpUri'
@ui.form.component 'qr-code'
totpUri: ui.paragraph
```

When the value is an `otpauth://` URI, the parsed secret is rendered beneath
the SVG as plain text — set `:manualSecret="false"` when surfacing the secret
defeats the threat model (e.g. screen-sharing demos).

## AsCopy

Phantom field that surfaces a one-shot string with a read-only input and a
Copy button. Click writes through `navigator.clipboard.writeText` and swaps the
button label to "Copied" for ~1.5 s; focusing the input selects the full value
for fallback Ctrl+C / Cmd+C copy.

Source: `packages/vue-aooth/src/components/as-copy.vue`.

```ts
interface AsCopyProps extends TAsComponentProps<string | undefined> {
  copyLabel?: string; // default "Copy"
  copiedLabel?: string; // default "Copied"
}
```

- Value is read as `props.value ?? props.model?.value`, same phantom +
  data-bound dual-mode as `AsQrCode`.
- Failed clipboard writes (no permission, no API) flip the button back and
  surface "Copy failed — select and copy manually" through the field's error
  slot.

```atscript
@meta.label 'Magic link'
@ui.form.fn.value '(v, data, ctx) => ctx.magicLink'
@ui.form.component 'copy'
magicLink: ui.paragraph
```

Use it for magic links, share tokens, generated identifiers — any one-off
value the user needs to paste somewhere else.

## AsSsoProviders

SSO / social-login provider picker. Renders providers as a main stack of
full-width buttons, with any flagged `secondary: true` dropping below an "or"
divider as compact chips. Each button is a **one-click action**: clicking
selects the provider id _and_ fires the form action in a single click — there
is no separate submit button. The bound value is the selected provider id
(`string | undefined`).

Source: `packages/vue-aooth/src/components/as-sso-providers.vue`.

```ts
interface AsSsoProvider {
  id: string; // committed to the model on click AND carried by the fired action
  text: string; // rendered verbatim — the backend owns the full display string
  icon?: string; // CSS class for the brand glyph, applied as-is (same contract as prefixIcon)
  secondary?: boolean; // true ⇒ compact chip below the "or" divider; omitted ⇒ full-width button (default)
}

interface AsSsoProvidersProps extends TAsComponentProps<string | undefined> {
  providers?: AsSsoProvider[];
}
```

- One-click: a click sets `model.value = provider.id` then emits the form
  `action` declared by `@ui.form.action` on the field. `<AsForm>` surfaces it
  as `@action(name, data)` with the selected provider in `data`. Without a
  wired `@ui.form.action` the click still selects but emits nothing.
- Default providers land in the prominent main stack; `secondary: true` drops
  to compact chips below the "or" divider. The divider renders only when
  _both_ groups are non-empty.
- `text` is rendered verbatim — the component never composes a
  "Continue with {name}" prefix; the backend supplies the full string.
- `icon` is applied as-is — you manage the icon collection and UnoCSS
  safelist (icon classes referenced from `.as` files aren't seen by the static
  extractor; safelist them).
- Empty / missing `providers` hides the whole field — same "render only when
  the backend supplied providers" pattern as `AsConsentArray`.
- No separate submit / "Continue" button — the provider buttons _are_ the
  action (the component renders chromeless and suppresses the shell's footer
  action link).

```atscript
@ui.form.component 'sso-providers'
@ui.form.action 'sso', 'Continue'
@ui.form.fn.attr 'providers', '(_v, _d, ctx) => ctx.ssoProviders'
ssoProvider?: string
```

In a workflow form add `@wf.action.withData 'sso'` on the same field so the
chosen provider rides the submission (the same mechanism `forgotPassword`
uses to carry a typed value). The full reference, plus a Vue mount showing the
`@action` handler, lives at
[@atscript/vue-aooth](/api/vue-aooth#component-asssoproviders).

## Phantom vs data-bound

`AsQrCode` and `AsCopy` are most useful as **phantom** fields backed by
context. The pattern combines three pieces:

1. The field type is `ui.paragraph` so the form treats it as non-data chrome —
   nothing is read or written on submit.
2. `@ui.form.fn.value '(v, data, ctx) => ctx.someKey'` supplies the displayed
   value from the form context.
3. `@wf.context.pass 'someKey'` (on workflow forms) opts the key into the
   client form context — without it, `ctx.someKey` is `undefined`.

Worked example for a workflow form rendering both at once:

```atscript
@wf.context.pass 'totpUri'
@wf.context.pass 'magicLink'
@meta.label 'Activate TOTP & share invite link'
@ui.form.submit.text 'Continue'
export interface QrCopyDemoForm {
    @meta.label 'Scan with your authenticator app'
    @ui.form.fn.value '(v, data, ctx) => ctx.totpUri'
    @ui.form.component 'qr-code'
    totpUri: ui.paragraph

    @meta.label 'Magic link'
    @ui.form.fn.value '(v, data, ctx) => ctx.magicLink'
    @ui.form.component 'copy'
    magicLink: ui.paragraph
}
```

::: warning Field-level fn signature

Field-level `@ui.form.fn.*` callbacks are `(v, data, ctx, entry)` — that's
the full signature, though most usages only consume the first two or three
arguments (`entry`, the resolved metadata entry, is rarely needed). The
two-argument shape `(_, ctx) => ...` is **wrong** — the second argument is
`data`, not the context, and `ctx` would silently resolve to the current
form-data object. Only **form-level** keys
(`@ui.form.fn.title`, `@ui.form.fn.description`, `@ui.form.fn.submit.text`,
`@ui.form.fn.submit.disabled`)
use `(data, ctx)`. See [Dynamic Fields](/forms/dynamic-fields#scope-passed-to-every-function).
:::

When the value should land in the bound data slot (typed columns, downstream
serialization), use a **data field** with `@meta.readonly` + `@ui.form.fn.value`
instead. `AsField` resolves the function and writes the result into the bound
path through a watcher (see `packages/vue-form/src/components/as-field.vue`,
the "Readonly watcher" block around the `phantomValue` setup). Phantom is the
cleaner shape whenever the value is display-only.

## Cross-links

- [@atscript/vue-aooth](/api/vue-aooth) — package API reference
- [Custom Field Components](/forms/custom-components) — the underlying contract
- [Dynamic Fields](/forms/dynamic-fields) — `@ui.form.fn.*` reference
- [Workflows · Context Passing](/workflows/context) — `@wf.context.pass`


---
URL: "ui.atscript.dev/forms/arrays"
LLMS_URL: "ui.atscript.dev/forms/arrays.md"
outline: "deep"
---

# Arrays

`vue-form` renders any `T[]` field through the `AsArray` Tier-2 default.
Add and remove are wired automatically, length constraints flow from
`@expect.minLength` / `@expect.maxLength`, and the item-noun for the
"Add" button is configurable.

## Patterns at a glance

```text
T[]   →  AsArray
T[]?  →  AsArray with "enable this section" affordance when undefined
```

Four shapes show up in practice:

1. **Optional scalar arrays** — `tags?: string[]`. Collapsed to an Add
   placeholder until the user starts.
2. **Required scalar arrays** — `headers: string[]`. Starts with zero
   items; submit blocks on `@expect.minLength 1`.
3. **Object arrays** — `contacts?: { ... }[]`. Each item renders as a
   card with its own Remove button.
4. **Union-item arrays** — `events: EventA | EventB[]`. Adding picks a
   variant; switching wipes the item data.

Plus the composition pattern: **nested arrays** — `team?: { name,
members?: string[] }[]`.

## The canonical example

A `Team.as` schema that covers every array shape in one form.

```atscript
@meta.label 'Array Showcase'
@meta.description 'Every array variant in one form.'
@ui.form.submit.text 'Save'
export interface ArrayShowcaseForm {
    // Optional array of primitives — collapsed to the Add placeholder
    // when empty.
    @meta.label 'Tags'
    @ui.form.label.singular 'tag'
    tags?: string[]

    // Required array of primitives — opens with zero items and a
    // footer Add button.
    @meta.label 'HTTP headers'
    @ui.form.label.singular 'header'
    @expect.minLength 1, 'At least one header is required'
    headers: string[]

    // Optional array of objects — each item is a card.
    @meta.label 'Contacts'
    @ui.form.label.singular 'contact'
    contacts?: {
        @meta.label 'First name'
        @meta.required 'First name is required'
        @ui.form.grid.colSpan '6'
        firstName: string

        @meta.label 'Last name'
        @ui.form.grid.colSpan '6'
        lastName?: string

        @meta.label 'Email'
        @meta.required 'Email is required'
        email: string.email
    }[]

    // Required array of objects — at least one entry.
    @meta.label 'Phone numbers'
    @ui.form.label.singular 'phone'
    @expect.minLength 1, 'At least one phone is required'
    phones: {
        @meta.label 'Label'
        @meta.required 'Label is required'
        @ui.form.grid.colSpan '4'
        label: string

        @meta.label 'Number'
        @meta.required 'Number is required'
        @ui.form.grid.colSpan '8'
        number: string
    }[]

    // Nested array.
    @meta.label 'Team'
    @ui.form.label.singular 'team'
    team?: {
        @meta.label 'Team name'
        @meta.required 'Team name is required'
        name: string

        @meta.label 'Members'
        @ui.form.label.singular 'member'
        members?: string[]
    }[]
}
```

Mount the form the usual way and every array gets +/− buttons, count
badges, and per-item validation for free:

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { ArrayShowcaseForm } from "./ArrayShowcase.as";

const types = createDefaultTypes();
const { def, formData } = createAsFormDef(ArrayShowcaseForm);
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" @submit="onSave" />
</template>
```

## Add / Remove constraints

`canAdd` and `canRemove` are derived from the length constraints
(`packages/vue-form/src/composables/use-as-array.ts:92-98`):

```ts
const canAdd = !disabled && length < maxLength;
const canRemove = !disabled && length > minLength;
```

| Annotation                            | Effect                                             |
| ------------------------------------- | -------------------------------------------------- |
| `@expect.minLength N, 'msg'`          | Add starts enabled; Remove hides once length === N |
| `@expect.maxLength N, 'msg'`          | Add hides once length === N                        |
| `@ui.form.disabled` on the array prop | Both Add and Remove disable                        |

Validation runs at submit (and live, depending on
`firstValidation`) — exceeding `maxLength` is gated by the UI, but
`minLength` is enforced by both the UI (Remove disabled) and the
submit-time validator.

## The "Add \_\_\_" button text

`@ui.form.label.singular 'tag'` controls the noun used in the Add
button: "Add tag", "Add tag", "Add tag". Without it the default is
"item" — fine for prototypes, not for real UI.

Falls back to the item's prop name if not set on the array prop —
useful for tuples and inline arrays. See
`packages/vue-form/src/components/as-field.vue:308-316`.

## Item identity

Each item gets a stable string key generated by `useAsArray`
(`as-item-0`, `as-item-1`, …). The key persists across remounts as
long as the item doesn't get re-added; removing item 2 from `[a, b, c]`
leaves `a` and `c` with their original keys.

This is what makes per-item validation behave correctly — a fresh-just-
added item stays fresh; an existing item that gets edited promotes out
of freshness, no matter what its current array index is.

The key is exposed on `useAsArray()`'s `itemKeys` array if you write
a custom array renderer.

## Nested arrays

Nested arrays just work — `AsArray` recurses through `AsField` →
`AsArray`. Each level provides its own `PATH_PREFIX_KEY` so child
fields compute absolute paths automatically (`team.0.members.2`).
Required/optional toggles cascade naturally: an optional outer array
is collapsed until enabled; a required inner array under it starts
with the inner constraint.

## Union-item arrays

`events: EventA | EventB[]` renders the Add button as a multi-action
menu (one Add per variant). Switching variants on an existing item
wipes the item's data — see [Unions](/forms/unions) for the underlying
behaviour and how to preserve user input across switches.

## Custom array renderer

If you want a fully custom array UI — a sortable list, a chip input,
an SAP-like detail-master — call `useAsArray(field)` from a Tier-2
swap component:

```vue
<script setup lang="ts">
import { useAsArray, AsField, AsFieldShell, type TAsComponentProps } from "@atscript/vue-form";
import type { FormArrayFieldDef } from "@atscript/ui";

const props = defineProps<TAsComponentProps>();
const {
  arrayValue,
  itemKeys,
  isUnion,
  unionVariants,
  isEmpty,
  getItemField,
  addItem,
  removeItem,
  canAdd,
  canRemove,
} = useAsArray(props.field as FormArrayFieldDef);
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default>
      <div v-for="(_, idx) in arrayValue" :key="itemKeys[idx]">
        <AsField :field="getItemField(idx)" />
        <button v-if="canRemove" @click="removeItem(idx)">−</button>
      </div>
      <button v-if="canAdd" @click="addItem()">Add</button>
    </template>
  </AsFieldShell>
</template>
```

Register it via the `:components` map and opt-in per field with
`@ui.form.component 'sortable-array'`.

## Phantom helpers

`@ui.array.add.label 'X'` (alias for `@ui.form.label.singular`) is
still accepted for backwards compatibility — both produce the same
button text. Prefer `@ui.form.label.singular`.

## Next steps

- [Nested Objects](/forms/nested-objects) — combining arrays and
  objects.
- [Unions](/forms/unions) — union-item arrays in depth.
- [Validation](/forms/validation) — how `@expect.minLength` /
  `maxLength` errors surface.
- [Custom Components](/forms/custom-components) — building a Tier-2
  swap with `useAsArray`.


---
URL: "ui.atscript.dev/forms/collapsible-sections"
LLMS_URL: "ui.atscript.dev/forms/collapsible-sections.md"
outline: "deep"
---

# Collapsible Sections

Use `<AsCollapsible>` directly to give your own custom component the same
section chrome `AsObject` renders nested objects with — plus header-row
actions `AsObject` can't expose. A custom `@ui.form.component` only renders
_inside_ a section body, so it can never reach the header. Tag
`AsCollapsible` yourself and you own the title row: badges, sub-text, and
action buttons aligned with the heading.

## The smallest example

A custom "Active sessions" component that owns its own section header and
hangs a "Log out all others" button off the title row. It receives the
standard [`TAsComponentProps`](/forms/custom-components#the-contract), so
`path` and `level` thread in from the resolved field.

```vue
<!-- SessionsSection.vue -->
<script setup lang="ts">
import { AsCollapsible, type TAsComponentProps } from "@atscript/vue-form";

const props = defineProps<TAsComponentProps<unknown[]>>();

function logoutOthers(): void {
  /* call your API */
}
</script>

<template>
  <AsCollapsible
    :level="props.level ?? 1"
    :path="props.path"
    :class="props.class"
    title="Active sessions"
    description="Devices currently signed in to your account"
  >
    <template #actions>
      <button type="button" @click="logoutOthers">Log out all others</button>
    </template>
    <template #body>
      <ul>
        <li v-for="s of props.model.value" :key="(s as any).id">
          {{ (s as any).device }}
        </li>
      </ul>
    </template>
  </AsCollapsible>
</template>
```

Register it in the components map and tag the field:

```atscript
@meta.label 'Active sessions'
@ui.form.component 'sessions-section'
sessions: {
    id: string
    device: string
}[]
```

```vue
<AsForm
  :def="def"
  :form-data="formData"
  :types="types"
  :components="{ 'sessions-section': SessionsSection }"
/>
```

The section renders with the standard chrome — clickable summary, chevron,
expand/collapse — and the "Log out all others" button sits on the title row.

## When to reach for it vs `AsObject`

- **`AsObject`** — the default. It already wraps every nested object in
  `AsCollapsible` and recurses into the children automatically. If you only
  need stock section chrome around a nested object, do nothing; you get it
  for free. See [Nested Objects](/forms/nested-objects).
- **`AsCollapsible`** — reach for it when you need that chrome around a
  _custom_ component, or when you need **header-row actions** (sessions,
  roles, devices, API keys…) that `AsObject` doesn't expose.

## Props

Full signatures live in the [API reference](/api/vue-form#ascollapsible).
The fields you'll set most:

| Prop              | Meaning                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `level`           | **Required.** Selects chrome + nesting depth (see table below).                                                           |
| `path`            | Unique key registered with the sections store for expand/collapse + error-driven auto-open. Must be unique (see gotchas). |
| `title`           | Header heading text.                                                                                                      |
| `description`     | Sub-text under the title.                                                                                                 |
| `error`           | Renders an alert row at the top of the body.                                                                              |
| `defaultOpen`     | Open on first mount. Defaults to `false`.                                                                                 |
| `hidden`          | Hides via `v-show` — the section stays mounted and registered.                                                            |
| `arrayIndex`      | Appends a `#N` suffix to the title.                                                                                       |
| `optional`        | When `true` and not enabled, the `empty` slot renders instead of the section.                                             |
| `optionalEnabled` | Gates the `empty` slot — the placeholder shows when `optional && !optionalEnabled`.                                       |

`level` drives both the visual variant and the heading tag:

| `level`           | Variant     | Chrome                                                               |
| ----------------- | ----------- | -------------------------------------------------------------------- |
| `≤ 0`             | **root**    | No chrome — renders the body only.                                   |
| `1, 3, 5…` (odd)  | **section** | Clickable `<summary>`, top divider, `<h3>` at level ≤ 1 else `<h4>`. |
| `2, 4, 6…` (even) | **island**  | Padded card with an even/odd background layer alternating by depth.  |

For a standalone top-level section, pass `level: 1`.

## Slots

Every header slot renders **inside `<summary>`**.

| Slot           | Renders                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------- |
| `title-extras` | Inline, right after the title text.                                                         |
| `badges`       | After the title row.                                                                        |
| `actions`      | Header action buttons. ⚠ Always visible, **even when collapsed** (it lives in `<summary>`). |
| `body`         | The section content.                                                                        |
| `empty`        | The "enable this section" placeholder, shown when `optional && !optionalEnabled`.           |

## Header actions only when expanded

Because `actions` renders in `<summary>`, it shows whether the section is
open or closed. For an action that should appear only when the section is
expanded, either put it in `body`, or gate it on the store's open state:

```vue
<script setup lang="ts">
import { AsCollapsible, useAsNestedSectionsStore } from "@atscript/vue-form";

const props = defineProps<{ path: string }>();
const sections = useAsNestedSectionsStore();
</script>

<template>
  <AsCollapsible :level="1" :path="props.path" title="Active sessions">
    <template #actions>
      <button v-if="sections?.isOpen(props.path)" type="button">Log out all others</button>
    </template>
    <template #body><!-- … --></template>
  </AsCollapsible>
</template>
```

## Participating in expand/collapse & auto-open

On mount (when `level` is non-root and `path` is set), `AsCollapsible`
registers its `path` with the shared sections store, so it joins the form's
**Expand all / Collapse all** and **error-driven auto-open**, and shows a
descendant-error-count badge when collapsed. This works as long as an
[`<AsForm>`](/api/vue-form#asform) ancestor — or an explicit
[`provideAsNestedSectionsStore()`](/forms/nested-objects#shared-sections-store)
— supplies the store. Those mechanics are owned by
[Nested Objects](/forms/nested-objects#error-aware-auto-open); this page
only consumes them.

## Full-bleed dividers in a padded card

A **section** (odd `level`) draws only top/bottom dividers, so it inlines into
the surrounding form. By default those dividers stop at the padded content box
of whatever wraps the section. Set the inherited `--as-inset` CSS variable to
the wrapper's horizontal padding and the dividers full-bleed to its edges,
while the section's own title and fields stay aligned inside the padding.

**Nested inside an island — automatic.** Each **island** (even `level`)
declares `--as-inset` equal to its own padding, so a section nested in it
bleeds its dividers to the island's inner edges with no extra work.

**A whole form inside your own card — opt in.** Set `--as-inset` on the card
to match its horizontal padding:

```vue
<div class="layer-0 border-1 rounded-r2 p-$m [--as-inset:1em]">
  <AsForm :def="def" :form-data="formData" :types="types" />
</div>
```

`p-$m` is `1em`, so `[--as-inset:1em]` matches it. Top-level section dividers
now span the card's edges; plain fields and nested islands stay inside the
padding. For a different padding token, set `--as-inset` to that value (e.g.
`[--as-inset:var(--card-spacing)]` with Vunor's `card`). When `--as-inset` is
unset it resolves to `0px`, so nothing changes — the feature is opt-in, and
only the **section** variant bleeds; the **island** keeps its full border.

## DOs and DON'Ts

- **DO pick a unique `path`.** The store keys open-state by `path`. A `path`
  that collides with a real form-field path shares that field's open-state.
  For standalone use, choose a stable key that won't clash with any dotted
  field path in your form.
- **DON'T expect `actions` to hide when collapsed.** It renders in
  `<summary>`, so it's always visible. Use `body` or the
  `useAsNestedSectionsStore().isOpen(path)` gate above for expanded-only
  actions.
- **DO bind `:class="props.class"` yourself** when used as a custom
  `@ui.form.component`. `AsCollapsible` is a **bare root** — it has no
  `AsFieldShell` — so it does **not** auto-apply the field's grid
  placement. The bare-root rule is covered in
  [Custom Components](/forms/custom-components).
- **DO match `--as-inset` to the wrapper's horizontal padding** when you wrap
  a form for full-bleed dividers. Larger than the padding overflows the card;
  smaller leaves the divider short. The value is `em`-based, so keep the card
  and form at the same font size.

## See also

- [Nested Objects](/forms/nested-objects) — the automatic `AsObject` chrome
  and the shared sections store.
- [Custom Components](/forms/custom-components) — the `TAsComponentProps`
  contract and the bare-root class rule.
- [API reference](/api/vue-form#ascollapsible) — full prop and slot
  signatures.


---
URL: "ui.atscript.dev/forms/custom-components"
LLMS_URL: "ui.atscript.dev/forms/custom-components.md"
---

# Building Custom Field Components

`AsField` resolves each field's metadata, picks the right component, and passes
**the full resolved field state** as props. A custom field component is any Vue
3 component that accepts the `TAsComponentProps<T>` contract.

This page is the reference for the contract, the typical skeleton, the built-in
composables you can pull in, and a complete worked example. For when to use
custom components, see [Customization](/forms/customization).

## The contract

Every field component receives a `TAsComponentProps<T>` interface (declared in
`packages/vue-form/src/components/types.ts`). `T` is the field's value type:
`string`, `number`, `string[]`, etc.

```typescript
import type { TAsComponentProps, TAsComponentEmits } from "@atscript/vue-form";

defineProps<TAsComponentProps<string | null | undefined>>();
defineEmits<TAsComponentEmits>();
```

Annotated breakdown of the props you'll touch most:

| Prop                        | Meaning                                                                    |
| --------------------------- | -------------------------------------------------------------------------- |
| `model`                     | `{ value: T }` — bind with `v-model="model.value"`                         |
| `label`                     | Resolved label (`@meta.label` / `@ui.form.fn.label`)                       |
| `description`               | Resolved description                                                       |
| `hint`                      | Resolved hint                                                              |
| `placeholder`               | Resolved placeholder                                                       |
| `disabled`                  | Resolved `@ui.form.disabled` / `@ui.form.fn.disabled`                      |
| `hidden`                    | Resolved `@ui.form.hidden` / `@ui.form.fn.hidden`                          |
| `readonly`                  | Resolved `@meta.readonly` / `@ui.form.fn.readonly`                         |
| `required` / `optional`     | Mirror each other; true/false for required-status                          |
| `onToggleOptional`          | Callable when `optional` is true — `true` sets default, `false` sets undef |
| `error`                     | Current validation error message                                           |
| `errorId` / `descId`        | Stable ids for `aria-describedby` wiring                                   |
| `inputId`                   | Stable id for `<label :for>` on your inner control                         |
| `ariaDescribedBy`           | Pre-resolved — bind directly to `aria-describedby`                         |
| `type`                      | Resolved field type string                                                 |
| `name`                      | Last segment of the field's dotted path                                    |
| `path`                      | Absolute dotted path inside form data                                      |
| `field`                     | Full `FormFieldDef` for advanced inspection                                |
| `formAction`                | For phantom action fields — `{ id, label }`                                |
| `options`                   | Resolved options for select/radio/checkbox                                 |
| `valueHelp`                 | FK ref descriptor (`ValueHelpInfo`)                                        |
| `singularLabel`             | From `@ui.form.label.singular` — used by arrays                            |
| `prefix` / `suffix`         | Resolved adornment text                                                    |
| `prefixIcon` / `suffixIcon` | Resolved adornment icon class                                              |
| `currencyCode`              | Resolved currency code (post sibling-ref)                                  |
| `unitCode`                  | Resolved unit code (post sibling-ref)                                      |
| `scale`                     | Effective display scale for decimals                                       |
| `hasAdornment`              | True when at least one adornment annotation is set                         |
| `arrayIndex`                | Index when rendered as a direct array item                                 |
| `onRemove`                  | Callback to remove this array item (only present inside arrays)            |
| `canRemove`                 | Whether removal respects `minLength` constraints                           |
| `removeLabel`               | Label for the remove button (`@ui.array.remove.label`)                     |
| `level`                     | Nesting depth (0 at root, increments per nested object/array)              |
| `onBlur`                    | Call when your control blurs — triggers field validation                   |

The complete list (and forward-compat fields) is in
`packages/vue-form/src/components/types.ts`.

## Emits

```typescript
interface TAsComponentEmits<_V = unknown> {
  (e: "action", name: string): void;
}
```

Only relevant when your component is registered as the `action` renderer or
emits other workflow actions. Forward the id through to `<AsForm>`'s `@action`
handler.

## Skeleton

The minimum viable custom field component, wrapped with `AsFieldShell` to
inherit standard label/error chrome:

```vue
<script setup lang="ts" generic="T">
import { AsFieldShell, type TAsComponentProps } from "@atscript/vue-form";

const props = defineProps<TAsComponentProps<T>>();

function commit(next: T): void {
  props.model.value = next;
}
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default="{ inputId }">
      <!-- your control, bound to model.value, plus :id="inputId" -->
      <input
        :id="inputId"
        :value="model.value"
        :placeholder="placeholder"
        :disabled="disabled"
        :readonly="readonly"
        :aria-required="required || undefined"
        :aria-invalid="!!error || undefined"
        :aria-describedby="ariaDescribedBy"
        @input="commit(($event.target as HTMLInputElement).value as T)"
        @blur="onBlur"
      />
    </template>
  </AsFieldShell>
</template>
```

Notes:

- `v-bind="$props"` forwards every contract prop to the shell so it can render
  label/description/error/optional toggle.
- The shell exposes the resolved `inputId` via the default slot scope — put it
  on your innermost control so the shell's `<label :for>` works.
- `onBlur` is a prop (not an emit). Call it from your control's blur handler.

## Useful composables inside a custom component

These are exported from `@atscript/vue-form` and safe to call inside any custom
field rendered as a descendant of `<AsForm>`.

### `useAsField`

The field-level state machine — model wrapper, validator pipeline, error
resolution, blur tracking. Use it when your component owns its own commit
path instead of routing through `<AsField>`:

```typescript
import { useAsField } from '@atscript/vue-form'

const props = defineProps<{ field: FormFieldDef; path: string }>()

const { model, error, onBlur } = useAsField<string>({
  getValue: () => /* read your value */,
  setValue: (v) => /* write your value */,
  rules: [(v) => !!v || 'Required'],
  path: () => props.path,
  resetValue: '',
})
```

Returns `{ model, error, onBlur }`. The composable registers with the parent
`<AsForm>` so the field participates in submit-time validation, reset, and
external-error wiring. See `packages/vue-form/src/composables/use-as-field.ts`
for the full options shape.

### `useAsData`

Reactive read-only access to the same data, including a relative-sibling
helper:

```typescript
import { useAsData } from "@atscript/vue-form";

const { rootData, getValueAt, siblingValue } = useAsData();

const country = siblingValue<string>("country");
// Inside an array item, this resolves to the sibling on the same item.
```

`siblingValue<T>(name)` reads relative to the current `useAsPath()` prefix —
i.e. it walks up to the nearest parent object and reads `name` on it.

### `useAsLocale`

Read the BCP-47 locale provided by `provideAsLocale` at the app root:

```typescript
import { useAsLocale } from "@atscript/vue-form";

const { locale } = useAsLocale();
const fmt = new Intl.NumberFormat(locale.value ?? "en-US");
```

See [Locale & currency](/forms/locale).

### `useAsDate`, `useAsNumber`, `useAsDecimal`, `useAsDualInput`

Higher-level composables for building date / numeric / decimal / merged-input
widgets that mirror the built-ins' behaviour. Useful when you want a different
visual but the same locale-aware parsing.

## Worked example — color swatch picker

A `ColorSwatch.vue` custom field component:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { AsFieldShell, type TAsComponentProps } from "@atscript/vue-form";

const props = defineProps<TAsComponentProps<string | null | undefined>>();

const PALETTE = [
  "#ef4444",
  "#f97316",
  "#facc15",
  "#22c55e",
  "#0ea5e9",
  "#6366f1",
  "#a855f7",
  "#64748b",
] as const;

const buttonRefs = ref<HTMLButtonElement[]>([]);

function pick(hex: string): void {
  props.model.value = hex;
}

function focusIndex(idx: number): void {
  const clamped = (idx + PALETTE.length) % PALETTE.length;
  buttonRefs.value[clamped]?.focus();
}

function onKeyDown(e: KeyboardEvent, idx: number, hex: string): void {
  switch (e.key) {
    case "ArrowRight":
    case "ArrowDown":
      e.preventDefault();
      focusIndex(idx + 1);
      break;
    case "ArrowLeft":
    case "ArrowUp":
      e.preventDefault();
      focusIndex(idx - 1);
      break;
    case "Enter":
    case " ":
      e.preventDefault();
      pick(hex);
      break;
  }
}

function onGroupBlur(e: FocusEvent): void {
  const next = e.relatedTarget as Node | null;
  const group = e.currentTarget as HTMLElement;
  if (group && next && group.contains(next)) return;
  props.onBlur();
}
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default="{ inputId }">
      <div
        role="radiogroup"
        :aria-label="label || name"
        :aria-describedby="ariaDescribedBy"
        :aria-required="required || undefined"
        :aria-invalid="!!error || undefined"
        @focusout="onGroupBlur"
      >
        <button
          v-for="(hex, idx) in PALETTE"
          :key="hex"
          :ref="(el) => (buttonRefs[idx] = el as HTMLButtonElement)"
          :id="idx === 0 ? inputId : undefined"
          type="button"
          :style="{ backgroundColor: hex }"
          :aria-label="hex"
          :aria-checked="model.value === hex"
          role="radio"
          :disabled="disabled"
          @click="pick(hex)"
          @keydown="onKeyDown($event, idx, hex)"
        />
      </div>
    </template>
  </AsFieldShell>
</template>
```

Wire it up via `:components` and tag the field:

```atscript
@meta.label 'Brand color'
@ui.form.component 'color-swatch'
brandColor: string
```

```vue
<AsForm
  :def="def"
  :form-data="formData"
  :types="types"
  :components="{ 'color-swatch': ColorSwatch }"
/>
```

## Accessibility checklist

- Bind `:id="inputId"` to the focusable element so `<label :for>` wired by
  `AsFieldShell` works.
- Bind `:aria-describedby="ariaDescribedBy"` to inherit the shell's
  description/error wiring.
- Set `:aria-required="required || undefined"` and
  `:aria-invalid="!!error || undefined"` on the inner control.
- For composite widgets (radiogroup, listbox, combobox), declare the right
  `role` on the container and label it with `:aria-label="label || name"`.
- Call `props.onBlur()` once when focus leaves the entire widget — see the
  `onGroupBlur` pattern above for multi-button widgets.

## When **not** to use a composable

Some built-in composables (`useAsArray`, `useAsNumber`, `useAsDecimal`) carry
specific assumptions: per-item recursion for arrays, a single text input with
locale-aware decimal parsing for `useAsNumber`. If your widget is a fundamentally
different shape — a tag input over `string[]` rendered as a single control, or
a stepper with `+`/`-` buttons over `number` — direct prop binding
(`props.model.value = ...`) stays cleaner. A `TagInput` or `NumberStepper`
typically follows that pattern.

## Next steps

- [Customization](/forms/customization) — wire your component into the form
- [Locale & currency](/forms/locale) — locale-aware composables
- [Validation](/forms/validation) — how the `error` prop gets populated


---
URL: "ui.atscript.dev/forms/customization"
LLMS_URL: "ui.atscript.dev/forms/customization.md"
---

# Customization

Every aspect of how a field renders is replaceable. Pick the smallest hammer
that fits — atscript-ui exposes four layered override mechanisms, from a
one-line global swap to a fully custom field render.

| Level | Scope                      | Use when                                              |
| ----- | -------------------------- | ----------------------------------------------------- |
| 1     | Global type swap           | Every field of a given type should use your component |
| 2     | Per-field named component  | One specific field needs a different widget           |
| 3     | Wrap with `AsFieldShell`   | Custom control, standard label/error chrome           |
| 4     | Full `AsForm` default slot | Take over the entire field-rendering loop             |

Mix as needed: a global swap for `text` plus a single per-field `'colorSwatch'`
override is normal.

## Level 1 — Global type swap

Pass a `:types` map to `<AsForm>`. The map's keys are the **built-in field
type ids** resolved by `<AsField>`:
`text`, `password`, `textarea`, `number`, `decimal`, `select`, `radio`,
`checkbox`, `multiselect`, `paragraph`, `action`, `object`, `array`,
`union`, `tuple`, `ref`, `date`, `datetime`, `time`.

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { ContactForm } from "./ContactForm.as";
import GrowingTextarea from "@/components/GrowingTextarea.vue";

const { def, formData } = createAsFormDef(ContactForm);

const types = {
  ...createDefaultTypes(),
  text: GrowingTextarea,
};
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" />
</template>
```

Every `string` field on the form now renders with `GrowingTextarea`. Other
types are untouched.

`createDefaultTypes()` returns a freshly-built map of the built-in defaults
(`AsInput`, `AsSelect`, …). Always spread it — the map shape is required by
`TAsTypeComponents`.

To **flip one specific field** to a different built-in renderer without
replacing the whole types map, use `@ui.form.type` (or the cross-cutting
`@ui.type`). The value must be one of the built-in ids above — `@ui.form.type`
is a _built-in renderer dispatcher_, not a place to wire custom components.

```atscript
@meta.label 'Bio'
@ui.form.type 'textarea'
bio: string

@meta.label 'Confirm password'
@ui.form.type 'password'
confirm: string
```

For anything outside the built-in id list — your own widgets, design-system
components, third-party pickers — jump to Level 2.

## Level 2 — Per-field named component

`@ui.form.component` is the dedicated mechanism for custom renderers. Tag the
field with a name, then register that name in the `:components` map:

```atscript
@meta.label 'Rating'
@ui.form.component 'stars'
rating: number

@meta.label 'Brand color'
@ui.form.component 'color-swatch'
brandColor: string

@meta.label 'Tags'
@ui.form.component 'tag-input'
@ui.form.label.singular 'tag'
tags: string[]
```

```vue
<script setup lang="ts">
import { StarRating, ColorSwatch, TagInput } from "@/components/custom";

const components = {
  stars: StarRating,
  "color-swatch": ColorSwatch,
  "tag-input": TagInput,
};
</script>

<template>
  <AsForm :def="def" :form-data="formData" :components="components" />
</template>
```

`as-field.vue` resolves components in this order
(`packages/vue-form/src/components/as-field.vue:373-386`):

1. `@ui.form.component 'name'` → `components[name]`
2. `@ui.form.type 'name'` → `types[name]` (built-in id)
3. Structural type → `types[type]` (`'text'`, `'number'`, etc.)

A field with no annotation falls all the way back to the structural lookup —
fine, that's how every default form already works.

:::tip Convention
The `:types` map is reserved for **built-in renderer ids**. Custom
components always go through `@ui.form.component` + the `:components` map.
The same rule applies to `@ui.type` / `@ui.table.type` — built-ins only.
:::

## Level 3 — Wrap with `AsFieldShell`

When you want a custom control but the standard label / description / error /
optional-toggle chrome should stay consistent with the rest of the form,
compose your widget inside `<AsFieldShell>`. The shell is the same wrapper the
built-in defaults use; it consumes the full `TAsComponentProps` contract via
`v-bind="$props"` and exposes a `default` slot with the resolved `inputId`.

```vue
<script setup lang="ts">
import { AsFieldShell, type TAsComponentProps } from "@atscript/vue-form";

const props = defineProps<TAsComponentProps<string | null | undefined>>();

const PALETTE = ["#ef4444", "#f97316", "#facc15", "#22c55e", "#0ea5e9"];

function pick(hex: string): void {
  props.model.value = hex;
}
</script>

<template>
  <AsFieldShell v-bind="$props" data-testid="color-swatch">
    <template #default="{ inputId }">
      <div role="radiogroup" :aria-label="label || name" :aria-describedby="ariaDescribedBy">
        <button
          v-for="(hex, idx) in PALETTE"
          :key="hex"
          :id="idx === 0 ? inputId : undefined"
          type="button"
          :style="{ backgroundColor: hex }"
          :aria-checked="model.value === hex"
          role="radio"
          :disabled="disabled"
          @click="pick(hex)"
        />
      </div>
    </template>
  </AsFieldShell>
</template>
```

What you get for free by wrapping with `AsFieldShell`:

- Label (`@meta.label` / `@ui.form.fn.label`)
- Description (`@meta.description` / `@ui.form.fn.description`)
- Hint text (`@ui.form.hint` / `@ui.form.fn.hint`)
- Error message and `scope-error` styling
- Optional-field toggle (`onToggleOptional`)
- `aria-describedby` wiring via `errorId` / `descId`

`ColorSwatch.vue`, `StarRating.vue`, `TagInput.vue`,
`NumberStepper.vue`, and `GrowingTextarea.vue` are typical working
examples of this pattern.

## Level 4 — Default slot of `AsForm`

The default slot of `<AsForm>` (well, technically the body content — the field
loop is `<AsField :field="def.rootField" />` inside the form template) lets you
take over rendering entirely. In practice this means: don't use the default
slot. Instead, build your own root component that calls `useAsForm()` directly
and renders the field tree however you want.

```vue
<script setup lang="ts">
import { useAsForm, AsField } from "@atscript/vue-form";
import { getFieldMeta, META_LABEL } from "@atscript/ui";
import { computed } from "vue";

const props = defineProps<{ def; formData; types }>();

const form = useAsForm({
  def: () => props.def,
  formData: () => props.formData,
  types: () => props.types,
});

// Resolve the root form title from the type's `@meta.label`.
const title = computed(() => getFieldMeta(props.def.type, META_LABEL) as string | undefined);
</script>

<template>
  <form @submit.prevent="form.onSubmit">
    <MyCustomHeader :title="title" />
    <AsField v-for="field in def.fields" :key="field.path" :field="field" />
    <MySubmitFooter :disabled="form.submitDisabled.value">
      {{ form.submitText.value }}
    </MySubmitFooter>
  </form>
</template>
```

`def.fields` is the flat list of root-level child fields; for the
header label you can also render `<AsField :field="def.rootField" />`
and let `AsForm`'s default chrome resolve the title for you.

For lower-level access — replacing `<AsField>` itself with your own per-field
component that calls `useAsField()` — see
[Custom field components](/forms/custom-components).

## Slots & the `slotProps` bag

Short of taking over the whole render loop, `<AsForm>` exposes named slots for
the chrome around the field tree — header, footer, error banner, submit button,
loading overlay. Every one receives the **same unified `slotProps` bag**, so you
can read form state from any slot without prop drilling.

The bag every slot gets:

| Key                                         | What it is                                             |
| ------------------------------------------- | ------------------------------------------------------ |
| `title` / `description`                     | Resolved form header text (`@meta.label` / fn variant) |
| `data`                                      | The reactive form-data container `{ value }`           |
| `errors` / `formError`                      | External leaf errors + the form-level message          |
| `disabled` / `loading`                      | Submit-disabled flag and busy state                    |
| `submitText`                                | Resolved submit-button label                           |
| `submit` / `reset`                          | Trigger submit / reset the form                        |
| `clearErrors` / `setErrors`                 | Imperative error control                               |
| `dismissError(path)` / `dismissFormError()` | Dismiss a leaf error or the banner                     |
| `formContext`                               | The reactive form context                              |

Slot list (each gets the bag, plus the extras noted):

| Slot           | Extra scope props    | Renders                         |
| -------------- | -------------------- | ------------------------------- |
| `form.header`  | —                    | Above the field tree            |
| `form.before`  | —                    | Inside the form, above fields   |
| `form.after`   | —                    | Inside the form, below fields   |
| `form.error`   | `message`, `dismiss` | Form-level error banner         |
| `form.submit`  | `text`               | The submit button               |
| `form.footer`  | —                    | Below the submit row            |
| `form.loading` | —                    | Contents of the loading overlay |

```vue
<template>
  <AsForm :def="def" :form-data="formData" :types="types">
    <template #form.header="{ title, description }">
      <h2 class="as-form-title">{{ title }}</h2>
      <p v-if="description" class="as-form-description">{{ description }}</p>
    </template>
  </AsForm>
</template>
```

The full bag type lives in the [`useAsForm` return](/api/vue-form#useasform-options)
(API reference) — narrative pages link rather than restate it.

### Hide props

Three booleans on `<AsForm>` control the default chrome:

- **`hideRootTitle`** — suppress the root field's title (use when the host
  chrome already shows the form's `@meta.label`, e.g. a dialog header) — this
  hides the title only; the field's `@meta.description` still renders. There is
  no built-in switch to hide both; render your own header via the `form.header`
  slot if you need full control.
- **`hideSubmit`** — suppress the default submit button (use when the host owns
  the submit affordance).
- **`loading`** — freeze the form: the body becomes `inert` and a loading
  overlay paints over the whole form area. `<AsWfForm>` wires this to its
  server round-trip.

::: warning Empty slot ≠ hidden
Vue 3 treats an empty `<template #form.submit />` as **"slot provided"**, which
suppresses the default button's fallback content but still renders the slot
wrapper. To actually drop the default submit button, use the `hideSubmit` prop —
not an empty slot.
:::

### Restyling the chrome

To restyle (not replace) the header, footer, submit, or error banner, override
their `as-*` shortcuts — `as-form-title`, `as-form-description`, `as-submit-btn`,
`as-form-error` — instead of writing a slot. See
[Overriding a built-in `as-*` shortcut](/styling/shortcuts#overriding-a-built-in-as-shortcut).

## Worked example — combining levels

A page can run two forms side-by-side to exercise multiple override
mechanisms.

**Section A** uses Level 1 — every `string` field on the form picks up
`GrowingTextarea` via the types map:

```typescript
const typesA = { ...createDefaultTypes(), text: GrowingTextarea };
```

**Section B** uses Levels 1 + 2 — `bio` is flipped to the built-in `textarea`
renderer via `@ui.form.type`; the rest are `@ui.form.component '<name>'`
widget swaps routed through the components map. `displayName: string` has no
annotation and falls back to the default `text` renderer:

```typescript
const componentsB = {
  stepper: NumberStepper,
  stars: StarRating,
  "color-swatch": ColorSwatch,
  "tag-input": TagInput,
  "address-card": AddressCard,
  "rgb-picker": RgbPicker,
  "contact-card": ContactCard,
};
```

## Picking between `@ui.form.type` and `@ui.form.component`

| Annotation           | Looks up in   | Value space                               |
| -------------------- | ------------- | ----------------------------------------- |
| `@ui.form.type`      | `:types`      | Built-in ids only (`text`, `textarea`, …) |
| `@ui.form.component` | `:components` | Any custom name you register              |

Rule of thumb:

- Use **`@ui.form.type`** to flip between built-in renderers — render a
  `string` as `textarea` / `password`, force a `number` field to use the
  `decimal` input, etc.
- Use **`@ui.form.component`** for every custom widget — your design system's
  date range picker, a domain-specific color swatch, a tag input, an
  address card.

The runtime resolver itself is open-ended — you _can_ stuff a custom name
into `@ui.form.type` and it will be looked up in `:types`. Reserving the
types map for built-ins is the convention: schemas read more predictably and
a future cleanup of unused custom entries is less likely to accidentally
unhook a field.

## Next steps

- [Custom field components](/forms/custom-components) — the `TAsComponentProps` contract in detail
- [Locale & currency](/forms/locale) — common composables for custom date/decimal widgets
- [Validation](/forms/validation) — how errors reach your custom widget


---
URL: "ui.atscript.dev/forms/dynamic-fields"
LLMS_URL: "ui.atscript.dev/forms/dynamic-fields.md"
---

# Dynamic Fields

Static `@ui.form.*` annotations describe a frozen form. Real apps need fields
that react to other fields — hide a "plus-one name" until the "bringing a
plus-one" checkbox is set, recompute a select's options from a sibling country
code, swap a submit button's label based on the current draft.

`@atscript/ui-fns` adds a parallel `@ui.form.fn.*` family of annotations. Each
takes a function body as a string. The body is compiled once with `new Function`
and re-evaluated whenever form data changes.

## Install the resolver

`@atscript/ui` ships a static resolver that ignores every `*.fn.*` key. Install
the dynamic resolver once at app startup — both client and server entries when
SSR is involved.

```typescript
// entry-client.ts / entry-server.ts
import { installDynamicResolver } from "@atscript/ui-fns";

installDynamicResolver();
```

`installDynamicResolver()` swaps in `DynamicFieldResolver` and registers the
ui-fns validator plugin so `@ui.form.validate '(v, data) => ...'` strings also
compile.

## Scope passed to every function

Every compiled function body sees these variables in scope:

| Variable  | What it is                                                                 |
| --------- | -------------------------------------------------------------------------- |
| `v`       | Current value of the annotated field                                       |
| `data`    | Unwrapped domain data (`formData.value`)                                   |
| `context` | The `:form-context` prop passed to `<AsForm>`, or `{}`                     |
| `entry`   | Per-field evaluated snapshot (name, type, disabled, options, …)            |
| `action`  | Dispatched action id when the evaluation was kicked off by an action click |

The full type is `TFnScope` from `@atscript/ui-fns/runtime/types.ts`.

```typescript
interface TFnScope<V = unknown> {
  v?: V;
  data: Record<string, unknown>;
  context: Record<string, unknown>;
  entry?: TFieldEvaluated;
  action?: string;
}
```

Form-level functions — `@ui.form.fn.title`, `@ui.form.fn.description`,
`@ui.form.fn.submit.text`, and `@ui.form.fn.submit.disabled` on the root
`interface` — receive only `(data, context)`; there is no `v`, `entry`, or
`action` at the form-level scope. The same `fn.title` / `fn.description`
keys on a **nested object field** (its section header) are field-level and
use the full `(v, data, context, entry)` signature.

## Every static prop has a dynamic counterpart

Field-level keys:

| Static                 | Dynamic                   |
| ---------------------- | ------------------------- |
| `@meta.label`          | `@ui.form.fn.label`       |
| `@meta.description`    | `@ui.form.fn.description` |
| `@ui.form.placeholder` | `@ui.form.fn.placeholder` |
| `@ui.form.hint`        | `@ui.form.fn.hint`        |
| `@ui.form.hidden`      | `@ui.form.fn.hidden`      |
| `@ui.form.disabled`    | `@ui.form.fn.disabled`    |
| `@meta.readonly`       | `@ui.form.fn.readonly`    |
| `@ui.form.options`     | `@ui.form.fn.options`     |
| `@meta.default`        | `@ui.form.fn.value`       |
| `@ui.form.attr`        | `@ui.form.fn.attr`        |
| `@ui.form.classes`     | `@ui.form.fn.classes`     |
| `@ui.form.styles`      | `@ui.form.fn.styles`      |

Form-level keys (on the root `interface`):

| Static                 | Dynamic                       |
| ---------------------- | ----------------------------- |
| `@meta.label`          | `@ui.form.fn.title`           |
| `@meta.description`    | `@ui.form.fn.description`     |
| `@ui.form.submit.text` | `@ui.form.fn.submit.text`     |
| —                      | `@ui.form.fn.submit.disabled` |

When both static and dynamic are present, the dynamic one wins.

## Worked example

A `DynamicForm.as` schema that exercises every dynamic key on one form:

```atscript
@meta.label 'Event Registration'

@ui.form.fn.title '(data) => data.firstName ? "Registration for " + data.firstName : "Event Registration"'
@ui.form.fn.submit.text '(data) => data.hasPlusOne ? "Register 2 attendees" : "Register"'
@ui.form.fn.submit.disabled '(data) => !data.firstName || !data.email'
export interface EventRegistration {
    @meta.label 'First Name'
    @ui.form.grid.colSpan '6'
    firstName: string

    @meta.label 'Email'
    @ui.form.grid.colSpan '6'
    @ui.form.fn.placeholder '(v, data) => data.firstName ? "Email for " + data.firstName : "you@example.com"'
    email: string

    @meta.label 'Bringing a plus-one?'
    hasPlusOne: boolean

    @meta.label "Plus-one's name"
    @ui.form.fn.hidden '(v, data) => !data.hasPlusOne'
    plusOneName: string

    @meta.label 'T-shirt size'
    @ui.form.fn.options '(v, data) => data.hasPlusOne ? [{ key: "S", label: "Small" }, { key: "M", label: "Medium" }, { key: "L", label: "Large" }, { key: "XS-PLUS", label: "Plus-One Small" }] : [{ key: "S", label: "Small" }, { key: "M", label: "Medium" }, { key: "L", label: "Large" }]'
    shirtSize: ui.select

    @meta.label 'Notes'
    @ui.form.fn.hint '(v, data) => (v ? v.length : 0) + " / 500 chars"'
    @ui.form.fn.classes '(v, data) => (v && v.length > 400) ? "as-notes-warn" : ""'
    @ui.form.validate '(v, data) => !v || v.length <= 500 || "Notes must be 500 chars or fewer"'
    notes: string

    @meta.label 'Total attendees'
    @ui.form.fn.value '(v, data) => data.hasPlusOne ? 2 : 1'
    attendees: ui.paragraph
}
```

The matching Vue page is a normal `<AsForm>`:

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { EventRegistration } from "./schemas/EventRegistration.as";

const { def, formData } = createAsFormDef(EventRegistration);
const types = createDefaultTypes();
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" />
</template>
```

No imperative wiring. Every dependent prop re-evaluates whenever `formData`
mutates, because each `@ui.form.fn.*` resolver reads through the same reactive
`data` getter exposed to `<AsField>`.

## Common patterns

### Hide a field unless a sibling is set

```atscript
@meta.label "Plus-one's name"
@ui.form.fn.hidden '(v, data) => !data.hasPlusOne'
plusOneName: string
```

### Dynamic options list

```atscript
@meta.label 'City'
@ui.form.fn.options '(v, data) => citiesByCountry[data.country] ?? []'
city: ui.select
```

`citiesByCountry` must be in scope. Functions only see `v`, `data`, `context`,
`entry`. To inject an external lookup table, pass it through the `:form-context`
prop on `<AsForm>` and read `context.citiesByCountry` instead.

```vue
<AsForm :def="def" :form-data="formData" :form-context="{ citiesByCountry }" :types="types" />
```

```atscript
@ui.form.fn.options '(v, data, ctx) => ctx.citiesByCountry[data.country] ?? []'
city: ui.select
```

### Computed label from form context

```atscript
@meta.label 'Welcome'
@ui.form.fn.title '(data, ctx) => "Welcome " + ctx.userName'
export interface WelcomeForm { ... }
```

### Disable submit until required fields are set

```atscript
@ui.form.fn.submit.disabled '(data) => !data.firstName || !data.email'
export interface RegistrationForm { ... }
```

The form-level scope reuses the same compiler — `data` is the first argument.

### Read-only depending on a sibling

```atscript
@meta.label 'Dietary preferences'
@ui.form.fn.readonly '(v, data) => !data.email'
@ui.form.fn.hint '(v, data) => !data.email ? "Enter your email first to enable this" : "Comma-separated"'
dietary: string
```

### Custom validator string

`@ui.form.validate` lives outside the `fn.*` namespace but uses the same
compiler. Return `true` for pass, a string message for fail.

```atscript
@ui.form.validate '(v, data) => !v || v.length <= 500 || "Notes must be 500 chars or fewer"'
notes: string
```

The validator runs alongside `@expect.*` rules and reports through the same
error pipeline. See [Validation](/forms/validation).

## Performance

Compiled functions are cached by `@prostojs/deserialize-fn`'s `FNPool`, keyed on
the function-body string. Two annotations with identical bodies share a single
compiled function instance.

The resolver is invoked per field per data change; bodies should stay cheap.
Pull lookup tables through `context` instead of allocating new arrays inside the
function body when possible.

## Security

`new Function` is real `eval`. The function strings ship in your `.as` files,
which are compile-time artifacts you own — that's safe. Two things to never do:

::: warning

- **Don't store user-authored expressions** in a database and feed them to
  `ui-fns`. Anyone with write access to that store gets arbitrary code
  execution in the browser.
- **Don't disable `installDynamicResolver()` in production while keeping
  `@ui.form.fn.*` in your `.as`** — the static resolver silently ignores
  `*.fn.*` keys and your forms will appear broken with no error.
  :::

## Next steps

- [Validation](/forms/validation) for `@ui.form.validate` and `@expect.*` rules
- [Grid layout](/forms/grid-layout) for the `@ui.form.grid.*` annotations used above
- [Actions](/forms/actions) for action buttons and dynamic submit text


---
URL: "ui.atscript.dev/forms/field-types"
LLMS_URL: "ui.atscript.dev/forms/field-types.md"
outline: "deep"
---

# Field Types & the Type Map

Every field rendered by `<AsForm>` is resolved against a **type map** —
a record from string keys (the field's `type` / `customType`) to Vue
components. The map is supplied as the `:types` prop. `createDefaultTypes()`
ships a complete set of unstyled defaults; you override entries to
plug in your own design system.

## The default type map

`createDefaultTypes()` is a six-line factory
(`packages/vue-form/src/composables/create-default-types.ts`) that
returns a fresh map of every built-in type to a Tier-2 default
component:

| Key           | Default component | Renders                                                         |
| ------------- | ----------------- | --------------------------------------------------------------- |
| `text`        | `AsInput`         | `<input type="text">`                                           |
| `textarea`    | `AsInput`         | `<textarea>` variant                                            |
| `password`    | `AsInput`         | `<input type="password">`                                       |
| `number`      | `AsNumber`        | numeric input with optional currency/unit chrome                |
| `decimal`     | `AsDecimal`       | fixed-point decimal with split integer/fraction halves          |
| `select`      | `AsSelect`        | `<select>` for static option lists                              |
| `radio`       | `AsRadio`         | radio-button group                                              |
| `checkbox`    | `AsCheckbox`      | single boolean checkbox / tri-state for optional booleans       |
| `multiselect` | `AsMultiSelect`   | combobox popup with chip-style selections, bound to `T[]`       |
| `date`        | `AsDate`          | date picker (`YYYY-MM-DD`)                                      |
| `datetime`    | `AsDatetime`      | date + time picker                                              |
| `time`        | `AsTime`          | time picker (`HH:MM` / `HH:MM:SS`)                              |
| `paragraph`   | `AsParagraph`     | read-only paragraph — value from `@meta.default` / `fn.value`   |
| `action`      | `AsAction`        | left-aligned link-styled button that emits `action` on the form |
| `object`      | `AsObject`        | nested object renderer (collapsible at depth)                   |
| `array`       | `AsArray`         | dynamic +/− array of items                                      |
| `union`       | `AsUnion`         | variant picker + dispatch to selected variant                   |
| `tuple`       | `AsTuple`         | fixed-position positional list                                  |
| `ref`         | `AsRef`           | searchable FK picker (driven by `@db.rel.FK` + `@db.http.path`) |

All Tier-2 defaults are exported from `@atscript/vue-form` and can be
imported by name when you want to reuse one inside a custom renderer.

## Atscript primitive → field type

`createFormDef` maps atscript primitive types onto these keys without
any annotation:

| `.as` type                 | → field type  | Notes                                                                  |
| -------------------------- | ------------- | ---------------------------------------------------------------------- |
| `string`                   | `text`        | also `string.email`, `string.url`, `string.uuid`, …                    |
| `number`                   | `number`      | use `@db.column.precision` for decimal placement                       |
| `boolean`                  | `checkbox`    | optional booleans render tri-state                                     |
| `Date`                     | `date`        | flip to `datetime` / `time` with `@ui.form.type`                       |
| `T[]`                      | `array`       | item type recurses                                                     |
| `('a' \| 'b')[]`           | `multiselect` | array of a literal union — options extracted from the item type        |
| `T[]` + `@ui.form.options` | `multiselect` | primitive-item array with an option list — `T` is `string` or `number` |
| `[A, B]`                   | `tuple`       | fixed-length positional                                                |
| `A \| B \| C`              | `union`       | discriminated union by required-prop fingerprint                       |
| `{ … }`                    | `object`      | nested structure — renders via AsObject                                |
| `RefToTable`               | `ref`         | only when `@db.rel.FK` + `@db.http.path` are present                   |

`string.email` carries the `email` format constraint through to the
atscript validator; the rendered control is still a `text` input. Use
`@ui.form.component` if you want to wire a dedicated email widget — see
[Custom Components](/forms/custom-components).

## Flipping to a different built-in renderer

`@ui.form.type` (and the cross-cutting `@ui.type`) overrides the
default structural lookup, but the value **must be one of the built-in
ids above**. Use it to switch a primitive between built-in renderers:

```atscript
@ui.form.type 'password'
password: string             // would default to 'text'; rendered as password

@ui.form.type 'select'
@ui.form.options 'admin' | 'user' | 'guest'
role: string                 // string union extracted to options

@ui.form.type 'textarea'
bio?: string                 // multi-line input

@ui.form.type 'datetime'
when: Date                   // upgrade Date → datetime picker
```

## Multi-select arrays

`multiselect` renders a combobox popup with chip-style selected
values inside the trigger — pick zero or more options from a fixed
list. The structural type stays `array` (so `@expect.minLength` /
`@expect.maxLength` still validate at the array level); only
`customType` flips to `multiselect`.
The two auto-dispatch cases are the last two `T[]` rows in the
primitive-type table above. Other `T[]` shapes fall back to the
dynamic +/- `array` renderer unless you tag them with
`@ui.form.type 'multiselect'`.

```atscript
colors: ('red' | 'green' | 'blue')[]       // auto → multiselect

@ui.form.options 'a' | 'b' | 'c'
tags: string[]                              // auto → multiselect (via options)

@ui.form.type 'multiselect'
@ui.form.options [1, 2, 3, 4]
sizes: number[]                             // forced
```

Value model is the array itself (`T[]`) — no wrapping, no positional
sentinel. Swap the default `AsMultiSelect` through the `:types` map
under the `multiselect` key.

For **custom** renderers — anything outside the built-in id list — use
`@ui.form.component` instead, with the name registered in the
`:components` prop map. The `:types` map is reserved for built-ins.

## Component resolution

When `<AsField>` mounts it picks a component in this order
(`packages/vue-form/src/components/as-field.vue:373-386`):

```text
1. @ui.form.component  →  components[name]
2. @ui.form.type / @ui.type  →  types[customType]   (built-in id)
3. field.type  →  types[type]
```

- `@ui.form.component` resolves a **named** component from the
  `:components` prop map. Highest precedence — the dedicated mechanism
  for custom widgets.
- `@ui.form.type` (and `@ui.type` on structured fields) resolves a
  **built-in type entry** in the `:types` map. Use it to swap built-in
  renderers, not to wire custom components.

If no match is found, `<AsField>` renders a small in-place diagnostic
message rather than erroring out — useful for catching typos without
crashing the whole form.

## Overriding by type — replace a default

The most common customization: keep the entire default map but swap
one entry for your design system's component.

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import MyInput from "./MyInput.vue";
import { BasicForm } from "../forms/BasicForm.as";

const types = { ...createDefaultTypes(), text: MyInput, password: MyInput };
const { def, formData } = createAsFormDef(BasicForm);
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" @submit="onSubmit" />
</template>
```

`MyInput` is a normal Vue component that accepts the
`TAsComponentProps` interface (model, label, error, ...). Wrapping it
in `<AsFieldShell>` is the fastest way to inherit the label /
description / error chrome — see
[Custom Components](/forms/custom-components).

## Wiring a custom component

When you have a one-off custom field (an RGB color picker, a chip
selector, a map widget), give it a name and register it in the
`:components` prop map. Tag the field with `@ui.form.component`:

```ts
import RgbPicker from "./RgbPicker.vue";

const components = {
  "rgb-picker": RgbPicker,
};
```

```atscript
@meta.label 'Brand color'
@ui.form.component 'rgb-picker'
logoRgb: [number, number, number]
```

The structural type stays `tuple`, so removing the
`@ui.form.component` annotation falls back to `AsTuple` automatically.

`@ui.form.component` is the dedicated mechanism for custom renderers
and the highest-precedence resolution path. It ignores the type map
entirely — the same custom name will not be looked up in `:types`,
which keeps the two maps cleanly separated.

:::tip Convention

- `:types` map — built-in renderer ids only (`text`, `textarea`, `date`, …).
  Touched by `@ui.form.type` / `@ui.type`.
- `:components` map — your custom renderers. Touched by `@ui.form.component`.

Don't mix the two: don't put custom components in `:types`, and don't
duplicate built-in renderers in `:components`. The runtime allows it,
but the convention keeps schemas predictable.
:::

## Built-in defaults — at a glance

| Component       | Use it when                                                              |
| --------------- | ------------------------------------------------------------------------ |
| `AsInput`       | text / password / textarea — the workhorse                               |
| `AsNumber`      | integer-y `number` fields, optionally with currency/unit chrome          |
| `AsDecimal`     | fixed-point inputs with controlled scale (money, percentages)            |
| `AsSelect`      | small static option lists                                                |
| `AsRadio`       | small option lists where seeing all options matters                      |
| `AsCheckbox`    | boolean — tri-state for optional booleans                                |
| `AsMultiSelect` | array of literal-union or option-list values — combobox popup with chips |
| `AsDate`        | date-only                                                                |
| `AsDatetime`    | date + time                                                              |
| `AsTime`        | time-only                                                                |
| `AsParagraph`   | read-only displayed text (no input)                                      |
| `AsAction`      | form-embedded button (fires `action` event)                              |
| `AsObject`      | nested record fields                                                     |
| `AsArray`       | dynamic-length lists                                                     |
| `AsUnion`       | discriminated unions / "pick one of N shapes"                            |
| `AsTuple`       | fixed-position positional arrays                                         |
| `AsRef`         | FK pickers driven by `@db.rel.FK` + `@db.http.path`                      |
| `AsFieldShell`  | wrapper providing label/description/error chrome inside custom renderers |

## Next steps

- [Validation](/forms/validation) — how the atscript validator wires
  into every type.
- [Customization](/forms/customization) — bigger-picture overrides,
  per-form `clientFactory`, theme integration.
- [Custom Components](/forms/custom-components) — building a Tier-2
  swap target from scratch.


---
URL: "ui.atscript.dev/forms/grid-layout"
LLMS_URL: "ui.atscript.dev/forms/grid-layout.md"
---

# Grid Layout

Every `AsObject` is a 12-column CSS grid. By default every field takes the full
row (`col-span-12`). Two annotations override that:

- `@ui.form.grid.colSpan` — column footprint
- `@ui.form.grid.rowSpan` — row footprint

Layouts are container-query driven: the grid container declares
`container-name: as-grid`, and a built-in `as-narrow:` variant kicks in when the
container measures `<= 480px` wide. Fields collapse to full-width on a narrow
container regardless of their desktop span.

## Quick example

```atscript
export interface AddressForm {
    @meta.label 'First name'
    @ui.form.grid.colSpan '6'
    firstName: string

    @meta.label 'Last name'
    @ui.form.grid.colSpan '6'
    lastName: string

    @meta.label 'City'
    @ui.form.grid.colSpan '4'
    city: string

    @meta.label 'State'
    @ui.form.grid.colSpan '4'
    state: string

    @meta.label 'ZIP'
    @ui.form.grid.colSpan '4'
    zip: string
}
```

Renders as two rows: half/half on the first, third/third/third on the second.
Drop the container below 480px and every field stacks vertically.

## Accepted values

`colSpan` accepts numeric strings `'1'`..`'12'` plus three aliases:

| Alias     | Columns |
| --------- | ------- |
| `'full'`  | 12      |
| `'half'`  | 6       |
| `'third'` | 4       |

`rowSpan` accepts positive numeric strings (`'1'`, `'2'`, `'3'`, …). There are
no aliases for rows.

Invalid values (`'0'`, negatives, decimals, unknown aliases) silently fall back
to the default. See `packages/ui/src/form/grid.ts` for the parser.

## Responsive override

Both annotations take an optional second argument for the narrow breakpoint:

```atscript
@meta.label 'Discount %'
@ui.form.grid.colSpan '4', '6'
discount: number
```

- `'4'` = one-third on desktop (4 of 12 columns, so 3 fields per row).
- `'6'` = half-width on narrow containers.

If the narrow argument is omitted, narrow defaults to `'12'` (full-width). You
do not need to write `'6', '12'` — the auto-stack already handles that case.

## Row span

Stretches a field across multiple grid rows so neighbours flow into the freed
slots instead of wrapping below:

```atscript
@meta.label 'Bio'
@ui.type 'textarea'
@ui.form.grid.colSpan '6'
@ui.form.grid.rowSpan '2'
bio: string

@meta.label 'Nickname'
@ui.form.grid.colSpan '6'
nickname: string

@meta.label 'Website'
@ui.form.grid.colSpan '6'
website: string
```

`bio` occupies the left half over two rows; `nickname` and `website` stack into
the right half of those rows.

## Container queries, not viewport queries

The `as-narrow:` variant compiles to:

```css
@container as-grid (max-width: 480px) { ... }
```

The grid container is registered via the `as-form-grid` shortcut. This means a
nested `AsObject` inside a half-width parent re-checks its own width — an
optional struct at `colSpan '6'` whose inner grid contains a `colSpan '6'`
child will auto-stack on a desktop viewport, because its own container is
narrower than 480px:

```atscript
@meta.label 'Address'
@ui.form.grid.colSpan '6'
address?: {
    @meta.label 'Street'
    street: string

    @meta.label 'City'
    @ui.form.grid.colSpan '6'
    city: string

    @meta.label 'ZIP'
    @ui.form.grid.colSpan '6'
    zip: string
}
```

The outer half is still side-by-side with another field; the inner `city/zip`
pair stacks because their container is narrow enough.

## How spans translate to classes

`packages/ui/src/form/grid.ts:buildGridClasses` emits a UnoCSS class string per
field:

| Desktop span | Narrow span | Generated classes                                |
| ------------ | ----------- | ------------------------------------------------ |
| `'6'`        | (default)   | `col-span-6` (narrow falls back to full)         |
| `'4'`        | `'6'`       | `col-span-4 as-narrow:col-span-6`                |
| `'6'`        | `'12'`      | `col-span-6` (no narrow class — `12` is default) |

`col-span-1`..`col-span-12` and `row-span-1`..`row-span-6` are pre-safelisted by
`@atscript/ui-styles`, so adding arbitrary spans never requires preset edits.

## Real-world annotations

A typical `Product.as` table schema:

```atscript
@db.table 'products'
export interface ProductsTable {
    @meta.label 'Name'
    @ui.form.grid.colSpan 'half'
    name: string

    @meta.label 'SKU'
    @ui.form.grid.colSpan 'half'
    sku: string

    @meta.label 'Category'
    @db.rel.FK
    @ui.form.grid.colSpan 'half'
    categoryId: CategoriesTable.id

    @meta.label 'Price'
    @db.amount.currency 'USD'
    @db.column.precision 10, 2
    @ui.form.grid.colSpan 'half'
    price: decimal
}
```

And a nested-grid example from `Customer.as`:

```atscript
@db.table 'customers'
export interface CustomersTable {
    @meta.label 'Address'
    @db.json
    address: {
        street: string

        @ui.form.grid.colSpan 'third'
        city: string

        @ui.form.grid.colSpan 'third'
        state: string

        @ui.form.grid.colSpan 'third'
        zip: string

        country: string
    }
}
```

`street` and `country` get default full rows; `city`/`state`/`zip` form a
three-column band in between.

## Combining with `@ui.form.hidden`

Hidden fields render with `display: none` — the grid cell is released and
following fields reflow into the gap. The field stays mounted and keeps its
value in the form data; hiding never clears anything.

To swap fields in and out without disturbing a balanced band, toggle a pair of
fields with matching spans via `@ui.form.fn.hidden` (see
[Dynamic fields](/forms/dynamic-fields)) — one shows while the other hides, so
the band's total span stays constant.

## Next steps

- [Nested objects](/forms/nested-objects) — every nested struct is its own grid
- [Arrays](/forms/arrays) — array items use the item's own field-level grid
- [Dynamic fields](/forms/dynamic-fields) — combine grid with `@ui.form.fn.hidden`


---
URL: "ui.atscript.dev/forms/hello-world"
LLMS_URL: "ui.atscript.dev/forms/hello-world.md"
outline: "deep"
---

# Hello World

This page builds a full working form end-to-end. It is the canonical
"prove the pipeline runs" example: a `.as` type, a Vue 3 mount, a
submit handler.

## Install

```bash
pnpm add @atscript/core @atscript/typescript @atscript/ui @atscript/vue-form
```

Make sure your `atscript.config.*` enables the TypeScript plugin so
`.as` imports compile to runtime metadata. See the
[atscript docs](https://atscript.dev) for compiler setup.

## 1. Write the type

`src/forms/BasicForm.as` — the source of truth for both the data
shape and the rendered form.

```atscript
@meta.label 'Basic Form'
@ui.form.submit.text 'Submit'
export interface BasicForm {
    @meta.label 'First Name'
    @meta.description 'Your given name'
    @ui.form.placeholder 'John'
    @ui.type 'text'
    @meta.required 'First name is required'
    @ui.form.order 1
    firstName: string

    @meta.label 'Last Name'
    @ui.form.placeholder 'Doe'
    @ui.type 'text'
    @meta.required 'Last name is required'
    @ui.form.order 2
    lastName: string

    @meta.label 'Age'
    @ui.type 'number'
    @meta.default '25'
    @ui.form.order 3
    @expect.min 18, 'Must be 18 or older'
    age: number

    @meta.label 'Email'
    @ui.type 'text'
    @ui.form.placeholder 'john@example.com'
    @ui.form.order 4
    email?: string.email

    @meta.label 'Password'
    @ui.form.placeholder 'Enter password'
    @ui.type 'password'
    @meta.required 'Password is required'
    @ui.form.order 5
    password: string
}
```

A few things to notice without diving in yet:

- `@meta.label` at the top decorates the **type** itself — it becomes
  the form title.
- `@ui.form.submit.text` sets the submit-button text. The form
  composable also accepts `@ui.form.fn.submit.text` (dynamic) — see
  [Dynamic Fields](/forms/dynamic-fields).
- `@ui.form.order` is sufficient to control field order; missing
  fields fall through in declaration order.
- `?: string.email` makes `email` optional and applies an `email`
  format check via the atscript validator.

## 2. Mount the form

`src/views/MyForm.vue` — the consumer side.

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { BasicForm } from "../forms/BasicForm.as";

const types = createDefaultTypes();
const { def, formData } = createAsFormDef(BasicForm);

function onSubmit(data: unknown) {
  console.log("BasicForm submitted:", data);
}
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" @submit="onSubmit" />
</template>
```

That is the entire form. Twelve lines of Vue, including imports.

## How the three pieces line up

**`createAsFormDef(BasicForm)`** parses the imported type's runtime
metadata into a `FormDef` (the framework-agnostic shape from
`@atscript/ui`) and creates a reactive `formData` container with all
declared defaults already applied. The implementation is six lines —
see `packages/vue-form/src/composables/create-as-form-def.ts`.

The returned `formData` is **wrapped**: `{ value: domainData }`. This
wrapping lets `getByPath`/`setByPath` treat the root the same way as
any other path. Read `formData.value` when you want the raw form
data (or just hand the whole thing to JSON.stringify for debugging).

```ts
formData.value ===
  {
    firstName: "",
    lastName: "",
    age: 25, // from @meta.default '25'
    email: undefined, // optional → undefined
    password: "",
  };
```

**`createDefaultTypes()`** returns a fresh map of every built-in field
type (`text`, `number`, `password`, `select`, `object`, `array`, …) to
its default Vue component. Spread it to override one type while
keeping the rest:

```ts
const types = { ...createDefaultTypes(), text: MyDesignSystemInput };
```

See [Field Types](/forms/field-types) for the full map.

**`<AsForm>`** is the Tier-1 component. Required props:

| Prop        | Type                | Why                                                         |
| ----------- | ------------------- | ----------------------------------------------------------- |
| `def`       | `FormDef`           | What to render — produced by `createAsFormDef`.             |
| `types`     | `TAsTypeComponents` | Type-to-component map. Use `createDefaultTypes()` to start. |
| `form-data` | reactive object     | Container `{ value: domainData }`. Recommended — see below. |

If `form-data` is omitted, `useAsForm` falls back to a bare
`ref<{}>` with **no `{ value }` wrapper and no `@meta.default`
values applied**. For anything but the most trivial throwaway form,
always pass `formData = createAsFormDef(MyType).formData` (or a
manually-wrapped `ref({ value: { ... } })`). That keeps the wrapper
invariant intact and ensures declared defaults are in place at first
render.

The full prop surface is in
`packages/vue-form/src/components/as-form.vue` (e.g. `errors`,
`firstValidation`, `loading`, `hideRootTitle`, `clientFactory`,
`components`).

## Submit flow

`@submit` fires with the **unwrapped domain data** (no `value`
wrapper) once submit-time validation passes. If validation fails,
`@error` fires instead with `{ path, message }[]`.

```vue
<AsForm :def="def" :form-data="formData" :types="types" @submit="onSubmit" @error="onErrors" />
```

```ts
function onSubmit(data: BasicForm) {
  // data: { firstName, lastName, age, email?, password }
}

function onErrors(errors: { path: string; message: string }[]) {
  console.warn("validation failed:", errors);
}
```

Validation runs through the atscript validator
(`getFormValidator(def)`) so every `@expect.*`, `@meta.required` and
`string.email` constraint baked into the type is enforced
automatically. Add custom rules with `@ui.form.validate`; see
[Validation](/forms/validation).

::: info Where state lives
`<AsForm>` calls `useAsForm()` under the hood
(`packages/vue-form/src/composables/use-as-form.ts`). It owns the
data container, validator, external-error dismissal, action dispatch
and change-merging logic. You can call `useAsForm()` directly from a
custom form root if you need a non-standard chrome.
:::

## Next steps

You now have a form rendering. The next thing you almost certainly
want is more control over what each field looks like and how it
validates — both live on the type, via annotations.

- [Annotations](/forms/annotations) — the authoritative reference.
- [Field Types](/forms/field-types) — the default type map.
- [Validation](/forms/validation) — `@expect.*`, custom rules,
  external errors.


---
URL: "ui.atscript.dev/forms/locale"
LLMS_URL: "ui.atscript.dev/forms/locale.md"
---

# Locale & Currency

Decimal separators, thousands grouping, currency symbols, and date/time
formatting all key off a single BCP-47 locale string. `<AsForm>` resolves it
through `useAsLocale()`, which reads from the nearest `provideAsLocale()`
ancestor — typically the app shell.

## Provide once at the shell

`provideAsLocale(getter)` takes a function that returns a BCP-47 locale (or
`undefined`). Wire it from your app prefs / user-settings reactive source:

```vue
<script setup lang="ts">
import { computed } from "vue";
import { provideAsLocale } from "@atscript/vue-form";
import { provideCellLocale, useAppPrefs } from "@atscript/vue-table";
import { clientFactory } from "@/api/client-factory";

const { prefs } = useAppPrefs({ url: "/api/db/_presets", clientFactory });

// Forms — drives decimal separator, currency symbol, AsDate/AsDatetime formatting.
provideAsLocale(() => prefs.value.language);

// Tables — same source, separate provider for the table side.
provideCellLocale(
  computed(() => ({
    language: prefs.value.language,
    timezone: prefs.value.timezone,
  })),
);
</script>

<template>
  <div>
    <SidebarNav />
    <main><slot /></main>
  </div>
</template>
```

Two providers because forms and tables intentionally don't depend on each
other — both read from the same source on the host side.

`useAsLocale()` returns `{ locale: ComputedRef<string | undefined> }`. When no
provider is present (`undefined`), built-in components fall back to the
browser's runtime locale via `new Intl.NumberFormat(undefined, ...)`.

## Inside a custom field

```vue
<script setup lang="ts">
import { computed } from "vue";
import { useAsLocale, type TAsComponentProps } from "@atscript/vue-form";

const props = defineProps<TAsComponentProps<number | null | undefined>>();
const { locale } = useAsLocale();

const formatted = computed(() => {
  if (props.model.value == null) return "";
  return new Intl.NumberFormat(locale.value ?? undefined).format(props.model.value);
});
</script>
```

The same source feeds the built-in `AsNumber`, `AsDecimal`, `AsDate`,
`AsDatetime`, and `AsTime` defaults — they all read `useAsLocale()` internally.

## Currency

Two annotations declare a decimal field as a currency amount.

### Static currency

```atscript
@meta.label 'Price'
@db.amount.currency 'USD'
@db.column.precision 10, 2
price: decimal
```

`AsDecimal` renders the locale-narrow currency symbol as a prefix adornment,
clamps display scale to the currency's natural decimals (USD → 2, JPY → 0),
and stores the canonical decimal string honoring `@db.column.precision`.

### Currency from a sibling

```atscript
@meta.label 'Currency'
currencyCode: string

@meta.label 'Amount'
@db.amount.currency.ref 'currencyCode'
@db.column.precision 10, 2
amount: decimal
```

Now the same field renders `$1,234.50`, `€1.234,50`, or `¥1235` depending on
what `currencyCode` resolves to in the same record. Useful for multi-currency
invoices.

The resolved `currencyCode` and `prefix` flow through `TAsComponentProps`:

| Prop           | Holds                                                |
| -------------- | ---------------------------------------------------- |
| `currencyCode` | The symbolic identifier (`'USD'`, `'EUR'`, …)        |
| `prefix`       | The locale-aware narrow symbol (`'$'`, `'€'`, `'¥'`) |
| `scale`        | Effective fractional digits (currency-clamped)       |

Both are reactive — flip the sibling's value and the prefix updates.

## Units of measure

`@db.unit` is the unitless counterpart of `@db.amount.currency`. It paints the
unit code as a **suffix adornment**:

```atscript
@meta.label 'Weight'
@db.unit 'kg'
@db.column.precision 6, 2
weight: decimal

@meta.label 'Speed'
@db.unit.ref 'speedUnit'
speed: decimal
```

The `unitCode` and `suffix` props on `TAsComponentProps` carry the same string
when resolved from a unit annotation.

## Precision and scale

`@db.column.precision precision, scale` caps storage:

- `precision` = total significant digits
- `scale` = maximum fractional digits

`AsDecimal` reads both — outgoing values are padded to `scale`, display values
clamp to `min(currencyDecimals, scale)`.

Without `@db.amount.currency`, only the scale matters for the form:

```atscript
@meta.label 'Tax rate'
@db.column.precision 5, 4
taxRate: decimal
```

Renders with 4 fractional digits regardless of locale.

## Date and time

`AsDate`, `AsDatetime`, and `AsTime` use the resolved locale for formatting:

```atscript
@meta.label 'Published'
publishedAt?: number.timestamp
```

A timestamp field (`number.timestamp`) routes through `datetime` in the default
types map; pair with `@ui.form.type 'date'` to get a date-only renderer.

The timezone is **not** owned by `provideAsLocale` — only the language. For
table cells, `provideCellLocale` carries both `language` and `timezone`. Form
date inputs use the runtime timezone by default; pass an explicit timezone via
`@ui.form.attr` or a custom `AsDate` swap if you need a fixed one.

## Tables, briefly

The table side has its own provider, `provideCellLocale`, exported from
`@atscript/vue-table`. It carries `{ language, timezone }`. Wire both from the
same source at the shell — see [Table cells](/tables/cells).

## Worked example — multi-currency line item

```atscript
@meta.label 'Line item'
export interface LineItem {
    @meta.label 'Description'
    description: string

    @meta.label 'Currency'
    @ui.form.options 'USD', 'EUR', 'GBP', 'JPY'
    @ui.form.grid.colSpan 'third'
    currencyCode: ui.select

    @meta.label 'Unit price'
    @db.amount.currency.ref 'currencyCode'
    @db.column.precision 12, 2
    @ui.form.grid.colSpan 'third'
    unitPrice: decimal

    @meta.label 'Quantity'
    @db.unit 'pcs'
    @ui.form.grid.colSpan 'third'
    quantity: number

    @meta.label 'Weight'
    @db.unit.ref 'weightUnit'
    weight?: decimal

    @meta.label 'Weight unit'
    @ui.form.options 'kg', 'lb'
    weightUnit?: ui.select
}
```

Inside a `<AsForm>` mounted under a `provideAsLocale(() => 'de-DE')` ancestor,
`unitPrice` reads as `€ 1.234,50`. Switch the currency dropdown to `'JPY'` and
it becomes `¥ 1235` — display scale drops to 0, no fractional digits.

## Next steps

- [Field types](/forms/field-types) — built-in renderers and their adornments
- [Custom components](/forms/custom-components) — call `useAsLocale` inside your own widget
- [Table cells](/tables/cells) — `provideCellLocale` and per-cell formatting


---
URL: "ui.atscript.dev/forms/nested-objects"
LLMS_URL: "ui.atscript.dev/forms/nested-objects.md"
outline: "deep"
---

# Nested Objects

Inline object literals in `.as` types nest naturally. `AsObject` renders
the root field as an iterator grid and every deeper level as a
collapsible section, with path-aware children that compute absolute
paths automatically.

## The canonical example

A `NestedForm.as` schema that builds a two-level company profile.

```atscript
@meta.label 'Company Profile'
@ui.form.submit.text 'Save Profile'
export interface NestedForm {
    @meta.label 'Company Name'
    @meta.required 'Company name is required'
    @ui.form.order 1
    companyName: string

    @meta.label 'Headquarters'
    @ui.form.order 2
    address: {
        @meta.label 'Street'
        @meta.required 'Street is required'
        street: string

        @meta.label 'City'
        @meta.required 'City is required'
        city: string

        @meta.label 'ZIP Code'
        @meta.required 'ZIP code is required'
        zip: string

        country: {
            @meta.label 'Country Name'
            @meta.required 'Country name is required'
            name: string

            @meta.label 'Country Code'
            @meta.required 'Country code is required'
            @ui.form.fn.hint '(v) => v && v.length !== 2 ? "Use a 2-letter ISO code" : ""'
            code: string
        }
    }

    @ui.form.order 10
    contact: {
        @meta.label 'Contact First Name'
        @meta.required 'First name is required'
        firstName: string

        @meta.label 'Contact Last Name'
        lastName?: string

        @meta.label 'Contact Email'
        @ui.form.fn.description
            '(v, data) => data.contact?.firstName ? "Email for " + data.contact.firstName : "Contact email address"'
        email?: string.email

        department: {
            @meta.label 'Department Name'
            name?: string

            @meta.label 'Floor'
            @expect.min 1, 'Floor must be at least 1'
            @expect.max 100, 'Floor must be at most 100'
            floor?: number

            @meta.label 'Room'
            @ui.form.fn.hidden '(v, data) => !data.contact?.department?.floor'
            room?: string
        }
    }
}
```

Mount it like any other form:

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { NestedForm } from "./NestedForm.as";

const types = createDefaultTypes();
const { def, formData } = createAsFormDef(NestedForm);
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" @submit="onSave" />
</template>
```

## How nesting renders

- The **root** level (`NestedForm`) is the form itself — its
  `@meta.label` becomes the form title.
- The **first nested level** (`address`, `contact`) renders inside a
  collapsible section. The section's open/closed state lives in the
  shared sections store (see below).
- **Deeper levels** (`address.country`, `contact.department`) render
  as their own collapsible sections — nested inside the parent's body.

Each `AsObject` shows a header with the field's label, an
error-count badge (if any descendants have errors), and a toggle
arrow.

## Path provision

`AsField` provides `PATH_PREFIX_KEY` for its descendants. Each level's
prefix is the parent's prefix joined with this field's prop name:

```text
root:                  ""
└─ address:            "address"
   └─ country:         "address.country"
      └─ name:         "address.country.name"
      └─ code:         "address.country.code"
└─ contact:            "contact"
   └─ department:      "contact.department"
      └─ room:         "contact.department.room"
```

You see these absolute paths in external errors
(`{ "address.street": "Unknown address" }`), in change events emitted
by `<AsForm>`, and in dynamic `data.*` accesses inside
`@ui.form.fn.*` expressions.

## Optional toggle on object fields

Top-level optional fields render with an "enable this section"
affordance — the user expands the placeholder to instantiate the
object's defaults. Closing the placeholder sets the value back to
`undefined`. Behaviour is identical at every depth.

For example:

```atscript
@meta.label 'Billing address'
billingAddress?: {
    street: string
    city: string
}
```

The form renders an "Add billing address" placeholder; clicking it
populates the field with `{ street: "", city: "" }` and opens the
section.

## Error-aware auto-open

`useAsForm` watches every error path and walks ancestors, opening
each section along the way
(`packages/vue-form/src/composables/use-as-form.ts:238-248`). After a
submit with errors in `address.country.code`, both the `address` and
`address.country` sections are open before the next paint.

This combines with [Validation](/forms/validation) — the user sees
exactly which field failed without having to hunt through closed
sections.

## Shared sections store

`AsForm` provides a `AsNestedSectionsStore` so the entire form shares
one expand/collapse registry
(`packages/vue-form/src/composables/use-as-nested-sections-store.ts`).

That registry can be **lifted above** the form. Call
`provideAsNestedSectionsStore()` from a page-level setup block when
you want page chrome (Expand All / Collapse All toolbar) to drive the
form's sections.

```vue
<script setup lang="ts">
import {
  AsForm,
  createDefaultTypes,
  createAsFormDef,
  provideAsNestedSectionsStore,
} from "@atscript/vue-form";
import { NestedForm } from "./NestedForm.as";

const sections = provideAsNestedSectionsStore();
const types = createDefaultTypes();
const { def, formData } = createAsFormDef(NestedForm);
</script>

<template>
  <header class="toolbar">
    <button @click="sections.expandAll()">Expand all</button>
    <button @click="sections.collapseAll()">Collapse all</button>
  </header>
  <AsForm :def="def" :form-data="formData" :types="types" />
</template>
```

`AsForm` will inherit the page-supplied store instead of creating its
own
(`packages/vue-form/src/composables/use-as-form.ts:222-225`).

## Custom object renderer

Replace `AsObject` for one shape (e.g. an address card with a map
preview) via the components map:

```ts
import AddressCard from "./AddressCard.vue";
const components = { "address-card": AddressCard };
```

```atscript
@ui.form.component 'address-card'
address: {
    street: string
    city: string
}
```

Inside `AddressCard.vue`, iterate `field.objectDef.fields` with
`<AsField>` to recurse into the children (or use `AsIterator` for the
default grid):

```vue
<script setup lang="ts">
import { AsField, AsFieldShell, type TAsComponentProps } from "@atscript/vue-form";
const props = defineProps<TAsComponentProps>();
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default>
      <div v-for="child of props.field.objectDef.fields" :key="child.name">
        <AsField :field="child" />
      </div>
    </template>
  </AsFieldShell>
</template>
```

`AsFieldShell` keeps the label/description/error chrome consistent
with built-in object fields.

## Dynamic visibility on nested fields

Combine nesting with `@ui.form.fn.*` for context-aware children:

```atscript
@meta.label 'Room'
@ui.form.fn.hidden '(v, data) => !data.contact?.department?.floor'
room?: string
```

`data` is always the **whole form's** domain data — so
`data.contact?.department?.floor` works from any depth. See
[Dynamic Fields](/forms/dynamic-fields).

## Next steps

- [Arrays](/forms/arrays) — array-of-objects and nested arrays.
- [Dynamic Fields](/forms/dynamic-fields) — context-aware sections.
- [Grid Layout](/forms/grid-layout) — splitting nested fields across
  columns.


---
URL: "ui.atscript.dev/forms/references"
LLMS_URL: "ui.atscript.dev/forms/references.md"
---

# References (FK)

A foreign-key field — a customer id on an order, a category id on a product —
renders as a **value-help picker**: a searchable combobox backed by the target
table's own metadata. atscript-ui resolves everything from two annotations on
the field plus a couple of dictionary hints on the target type.

## The annotations

The shape comes from `.as` schemas (see
[atscript-db relations](https://db.atscript.dev/relations)).

```atscript
import { CustomersTable } from './Customer.as'
import { ProductsTable } from './Product.as'

@db.table 'orders'
export interface OrdersTable {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Customer'
    @db.rel.FK
    customerId: CustomersTable.id

    @meta.label 'Product'
    @db.rel.FK
    productId: ProductsTable.id

    @meta.label 'Quantity'
    quantity: number
}
```

- `@db.rel.FK` plus `CustomersTable.id` declares the foreign-key relationship.
- The target type (`CustomersTable`) carries `@db.http.path '/api/customers'`
  in its own definition so the form knows where to query.

When `<AsField>` resolves to a FK field it routes through the `ref` entry in
your types map — by default `AsRef`, a Reka-ui Combobox driven by a
`ValueHelpClient` (`packages/ui/src/value-help/value-help-client.ts`).

## How the picker resolves the target

`ValueHelpClient` is a thin wrapper around a `Client` from `@atscript/db-client`
that:

1. Fetches the target type's `@db.http.path` metadata once and caches it.
2. Queries the target with `$select` scoped to PK + label + (optional) descr.
3. On search, sends `$search` to a `@db.index.fulltext` target, or builds an
   `$or` regex filter for non-searchable targets, plus an exact-PK match.
4. Honours `$limit` (default 20).

The client is created lazily and shared by every ref field in the form — see
the `clientFactory` provide in `packages/vue-form/src/components/as-form.vue`.

## Controlling display with `@ui.dict.*`

The target type's dictionary annotations decide what the picker shows for each
row.

```atscript
@db.table 'customers'
@db.http.path '/api/customers'
export interface CustomersTable {
    @meta.id
    id: number

    @ui.dict.label
    @db.index.fulltext 'customers_search'
    name: string

    @ui.dict.descr
    email: string

    @ui.dict.attr
    region: string

    @ui.dict.attr
    tier: 'gold' | 'silver' | 'bronze'
}
```

| Annotation            | Picker behaviour                                                |
| --------------------- | --------------------------------------------------------------- |
| `@ui.dict.label`      | Primary text shown for each row                                 |
| `@ui.dict.descr`      | Secondary text under the label                                  |
| `@ui.dict.attr`       | Extra columns shown in the expanded mini-table view             |
| `@ui.dict.searchable` | Forces the picker to send `$search` even without fulltext index |
| `@ui.dict.filterable` | Field appears in the picker's filter dialog                     |
| `@ui.dict.sortable`   | Field appears in the picker's sort options                      |

Without `@ui.dict.label`, the picker falls back to the primary-key column —
useable but not pretty.

See [atscript-db queries](https://db.atscript.dev/api/queries) for the server
side of `$search`, `$select`, `$limit`, and `$or` filter syntax.

## Authenticated fetches: `clientFactory`

The default `clientFactory` builds a plain `Client(url)` — no auth headers. To
inject a session token (or any other transport concern) pass a `clientFactory`
prop to `<AsForm>` (or `<AsWfForm>`):

```vue
<script setup lang="ts">
import { AsForm, type ClientFactory } from "@atscript/vue-form";
import { Client } from "@atscript/db-client";

const clientFactory: ClientFactory = (url) =>
  new Client(url, {
    fetch: (req) => fetch(req, { headers: { Authorization: `Bearer ${getToken()}` } }),
  });
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" :client-factory="clientFactory" />
</template>
```

For an app-wide default, call `setDefaultClientFactory` once at startup:

```typescript
import { setDefaultClientFactory } from "@atscript/vue-form";

setDefaultClientFactory(
  (url) =>
    new Client(url, {
      /* auth */
    }),
);
```

Per-form `clientFactory` props override the default. Both fall back to the
built-in `new Client(url)` factory when unset.

## Picker UX

The default `AsRef` component is a Reka-ui Combobox with:

- Inline text search (debounced; `$search` for fulltext targets, `$or` regex
  fallback for non-searchable ones).
- Keyboard-navigable list of results (`data-highlighted` / `data-state` driven
  by Reka).
- Display of `@ui.dict.label` plus a faint secondary `@ui.dict.descr` line.
- Clear button to reset the FK to `null`.
- Loading and empty-state slots.

For deeper customisation (column layout, filters, mini-tables) swap the `ref`
entry in the types map — see [Customization](/forms/customization).

## Cross-references

- Server-side relation metadata — [db.atscript.dev/relations](https://db.atscript.dev/relations)
- Query controls (`$search`, `$select`, `$limit`, filters) —
  [db.atscript.dev/api/queries](https://db.atscript.dev/api/queries)
- Building the target's REST controller — [db.atscript.dev/moost-db](https://db.atscript.dev/moost-db)

## Next steps

- [Customization](/forms/customization) — swap `AsRef` for your own picker
- [Validation](/forms/validation) — error messages for required FKs
- [Locale & currency](/forms/locale) — formatting nearby decimal columns


---
URL: "ui.atscript.dev/forms/tuples"
LLMS_URL: "ui.atscript.dev/forms/tuples.md"
outline: "deep"
---

# Tuples

Fixed-length positional arrays in `.as` types — `[A, B, C]` — render
through the `AsTuple` default. Each position has a fixed type;
positions can be individually labelled; the tuple auto-pads to its
declared length on mount.

## Declaring a tuple

```atscript
@meta.label 'Brand color'
@meta.description 'RGB channel triple, 0-255.'
logoRgb: [number, number, number]
```

A tuple position can carry its own annotations:

```atscript
coords: [
    @meta.label 'Latitude'
    @expect.min -90, 'Latitude must be ≥ -90'
    @expect.max 90, 'Latitude must be ≤ 90'
    number,

    @meta.label 'Longitude'
    @expect.min -180, 'Longitude must be ≥ -180'
    @expect.max 180, 'Longitude must be ≤ 180'
    number
]
```

The default `AsTuple` renderer iterates positions, dispatching each to
`<AsField>` with `array-index` set so the position labels read as
`Latitude #1`, `Longitude #2` (or just the position label when one is
set with `@meta.label`).

## Auto-padding

`useAsTuple()` runs an `onMounted` hook that fills missing positions
with their type's default value — non-optional tuples are guaranteed
to be the correct length before the user sees them
(`packages/vue-form/src/composables/use-as-tuple.ts:45-71`).

```ts
function fillMissing() {
  let arr = getByPath(pathPrefix.value);
  if (!Array.isArray(arr)) {
    arr = [];
    setByPath(pathPrefix.value, arr);
  }
  if (arr.length >= itemFields.length) return;
  for (let i = arr.length; i < itemFields.length; i++) {
    arr.push(createFormData(field.itemFields[i].prop, resolver).value);
  }
}
```

Optional tuples (`coords?: [number, number]`) skip the auto-pad until
the user toggles them on; clear() then resets them to `undefined`.

## Custom tuple renderer

A `RgbPicker` custom tuple — three R/G/B sliders + a live preview
swatch.

```vue
<script setup lang="ts">
import { computed } from "vue";
import { AsFieldShell, type TAsComponentProps, useAsTuple } from "@atscript/vue-form";
import type { FormTupleFieldDef } from "@atscript/ui";

const props = defineProps<TAsComponentProps<[number, number, number] | null | undefined>>();
useAsTuple(props.field as FormTupleFieldDef);

function readChannel(idx: number): number {
  const v = props.model.value;
  if (!Array.isArray(v)) return 0;
  const n = v[idx];
  return typeof n === "number" && Number.isFinite(n) ? clamp(n) : 0;
}

function clamp(n: number): number {
  if (n < 0) return 0;
  if (n > 255) return 255;
  return Math.round(n);
}

function setChannel(idx: number, raw: number): void {
  const next: [number, number, number] = [readChannel(0), readChannel(1), readChannel(2)];
  next[idx] = clamp(raw);
  props.model.value = next;
}

const r = computed(() => readChannel(0));
const g = computed(() => readChannel(1));
const b = computed(() => readChannel(2));
const rgbCss = computed(() => `rgb(${r.value}, ${g.value}, ${b.value})`);
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default>
      <input
        type="range"
        min="0"
        max="255"
        :value="r"
        @input="(e) => setChannel(0, +e.target.value)"
      />
      <input
        type="range"
        min="0"
        max="255"
        :value="g"
        @input="(e) => setChannel(1, +e.target.value)"
      />
      <input
        type="range"
        min="0"
        max="255"
        :value="b"
        @input="(e) => setChannel(2, +e.target.value)"
      />
      <div :style="{ backgroundColor: rgbCss }" />
    </template>
  </AsFieldShell>
</template>
```

Two design notes:

- **`useAsTuple` is consumed for its `fillMissing` `onMounted` hook
  only.** The per-position itemFields / clear API isn't used because
  the UI is one integrated widget rather than three nested AsField
  shells.
- **`AsFieldShell` provides the label/description/error chrome.** The
  custom renderer focuses on the value-editing UI itself.

Opt in per field with `@ui.form.component`:

```atscript
@ui.form.component 'rgb-picker'
logoRgb: [number, number, number]
```

Register in the components map:

```ts
const components = { "rgb-picker": RgbPicker };
```

## `useAsTuple` return

```ts
const {
  itemFields, // FormFieldDef[] — one per position, with index path
  positionLabeled, // boolean[] — whether each position carries @meta.label
  isOptional, // boolean — from prop.optional
  isEmpty, // ComputedRef<boolean> — value is missing / empty array
  clear, // () => void — optional tuples only; resets to undefined
  fillMissing, // () => void — pad to declared length
} = useAsTuple(field as FormTupleFieldDef);
```

`positionLabeled[i] === true` means the position carries
`@meta.label`. The default `AsTuple` uses this to decide whether to
render a `#N` index suffix — if every position is labelled, the
suffix is suppressed.

## Validation

Tuples participate in the regular validation pipeline. Per-position
`@expect.*` annotations validate the corresponding array slot at
submit time; the error path uses the index (`logoRgb.0`,
`logoRgb.1`, …).

```atscript
@meta.label 'Hue'
@expect.min 0, 'Hue must be ≥ 0'
@expect.max 359, 'Hue must be ≤ 359'
hsl: [number, number, number]
```

For multi-position constraints (e.g. "saturation + lightness must sum
to at most 100"), use a tuple-level `@ui.form.validate`:

```atscript
@meta.label 'HSL'
@ui.form.validate '(v) => v[1] + v[2] <= 100 || "S + L must be ≤ 100"'
hsl: [number, number, number]
```

## Tuples vs arrays vs unions

| Need                                 | Use       |
| ------------------------------------ | --------- |
| Fixed-length positional, typed slots | `tuple`   |
| Variable-length, homogeneous items   | `array`   |
| One-of-N shapes, with detection      | `union`   |
| Variable-length, heterogeneous items | `union[]` |

A tuple is **not** the right shape for "two of the same thing"
(use `string[]` with `minLength: 2`, `maxLength: 2`) or for a
"struct with a fixed key set" (use an object).

## Next steps

- [Custom Components](/forms/custom-components) — the full Tier-2
  swap-target workflow.
- [Unions](/forms/unions) — the other variant-aware structural field.
- [Annotations](/forms/annotations) — the full reference, including
  `@expect.*` rules used here.


---
URL: "ui.atscript.dev/forms/unions"
LLMS_URL: "ui.atscript.dev/forms/unions.md"
outline: "deep"
---

# Unions

Discriminated unions in `.as` types map to a variant picker + dispatch
to the active variant's component. `AsUnion` detects which variant
matches the current data using a **required-prop fingerprint**, lets
the user switch variants, and stashes the previous variant's data so
flipping back restores the user's work.

## The canonical example

A `Customer.as` schema defines three contact-method types and unions
them on a `primaryContact` field:

```atscript
@meta.label 'Email contact'
type CustomerEmailContact = {
    @meta.label 'Email'
    @meta.required 'Email is required'
    email: string

    @meta.label 'HTML newsletter'
    htmlNewsletter?: boolean
}

@meta.label 'Phone contact'
type CustomerPhoneContact = {
    @meta.label 'Phone'
    @meta.required 'Phone is required'
    phone: string
}

@meta.label 'Postal contact'
type CustomerPostalContact = {
    @meta.label 'Street'
    @meta.required 'Street is required'
    street: string

    @meta.label 'City'
    @meta.required 'City is required'
    city: string
}

@db.table 'customers'
export interface CustomersTable {
    @meta.id
    @db.default.increment
    id: number

    name: string

    @meta.label 'Primary contact'
    @meta.description 'Optional fingerprint union — variant detected by required-prop set.'
    @db.json
    primaryContact?: CustomerEmailContact | CustomerPhoneContact | CustomerPostalContact
}
```

Mount the form, and the union renders with a variant picker (Email /
Phone / Postal) plus the selected variant's fields below:

```vue
<AsForm :def="def" :form-data="formData" :types="types" @submit="onSave" />
```

## Variant detection

`detectUnionVariant(value, unionVariants)` from `@atscript/ui` picks
the active variant by checking each variant's **required prop set**
against the current data shape. The first variant whose required props
all appear in the data wins. If the data is `null`/`undefined`,
detection returns index 0 (the first variant).

This is what "fingerprinting" means in the schema comment — variants
need a distinct required-prop set to be unambiguously detectable.
Avoid sibling variants that share their required-prop fingerprint.

::: tip Disambiguate by required props
Two variants that both require `{ email }` would collide. Add a
discriminant required field (`kind: 'email'` vs `kind: 'phone'`) or
make one variant's email property optional.
:::

## Switching variants

Picking a different variant calls `changeVariant(newIndex)` on
`useAsUnion` (`packages/vue-form/src/composables/use-as-union.ts`).
The composable:

1. **Stashes** the current variant's data into an in-memory map keyed
   by the previous index.
2. Updates `localUnionIndex` to the new variant.
3. **Restores** the new variant's stashed data if any, otherwise calls
   `createFormData(variant.type)` for fresh defaults.
4. Fires a `union-switch` change event so external errors and merged
   internal errors dismiss correctly.

The stash lives on the component instance — flipping Email → Phone →
Email returns the original Email data. Unmounting the form discards
the stash.

## `useAsUnion`

For custom variant pickers (cards, segmented control, dropdown menu),
call the composable directly. It returns:

```ts
const {
  unionField, // FormUnionFieldDef | undefined
  hasMultipleVariants, // ComputedRef<boolean>
  localUnionIndex, // Ref<number>
  innerField, // ComputedRef<FormFieldDef | undefined>
  changeVariant, // (newIndex: number) => void
  optionalEnabled, // ComputedRef<boolean>
} = useAsUnion(props);
```

`innerField` is a synthesized field for the active variant — handing
it to `<AsField>` dispatches the variant's component (`AsObject` for
object variants, `AsField` for primitive itemField variants). For
custom layouts you can also iterate the variant's nested fields
yourself.

## Custom union renderer

A `ContactCard.vue` custom union renderer — three icon cards across the
top, the active variant's fields below.

```vue
<script setup lang="ts">
import { computed } from "vue";
import { AsField, AsFieldShell, type TAsComponentProps, useAsUnion } from "@atscript/vue-form";
import { isObjectField } from "@atscript/ui";

const props = defineProps<TAsComponentProps>();
const { unionField, localUnionIndex, innerField, changeVariant } = useAsUnion(props);

const variants = computed(() => unionField.value?.unionVariants ?? []);
const activeFields = computed(() => {
  const inner = innerField.value;
  return inner && isObjectField(inner) ? inner.objectDef.fields : [];
});

function pick(index: number) {
  if (props.disabled) return;
  if (localUnionIndex.value === index) return;
  changeVariant(index);
}
</script>

<template>
  <AsFieldShell v-bind="$props">
    <template #default>
      <div role="radiogroup">
        <button
          v-for="(v, vi) in variants"
          :key="vi"
          type="button"
          :aria-checked="localUnionIndex === vi"
          @click="pick(vi)"
        >
          {{ v.label }}
        </button>
      </div>
      <AsField v-for="f of activeFields" :key="f.path ?? f.name" :field="f" />
    </template>
  </AsFieldShell>
</template>
```

Opt in per field with `@ui.form.component`:

```atscript
@ui.form.component 'contact-card'
contact: EmailContact | PhoneContact | PostalContact
```

Register the renderer in the components map:

```ts
const components = { "contact-card": ContactCard };
```

Wrap with `<AsFieldShell>` — `useAsUnion` does **not** itself provide
the union context that `AsFieldShell` would inject; only the default
`as-union.vue` does. That means the shell will render label /
description / error / required marker but **not** paint its own
variant picker on top of yours.

## Preserving variant data

The built-in stash handles "flip and come back" within one mount.
For longer-lived persistence (e.g. user navigates away and returns)
you have two options:

1. **External stash.** Keep the discarded variant data in your own
   reactive store and re-hydrate it on the next mount.
2. **Merge into one type.** If the variants genuinely share fields,
   collapse them into one type with optional fields per branch and use
   a discriminant tag.

The `ContactCard` pattern works for the in-mount case; persistence
across mounts is out-of-scope for vue-form.

::: warning Switching wipes by default
If the user picks Phone → Email, then Email → Phone, the Phone data
they originally typed is gone unless you implemented a stash. The
built-in stash covers the common case (toggling back inside one
form session).
:::

## Optional unions

`primaryContact?: A | B | C` renders a placeholder ("Add primary
contact") until the user enables it. Enabling instantiates variant 0
with its defaults; subsequent picks switch through the stash.

Closing the placeholder sets `primaryContact` back to `undefined` and
clears the stash.

## Union-item arrays

`events: EventA | EventB[]` renders the Add button as a multi-action
menu — one Add per variant. Each added item is its own union value
with its own variant state. See [Arrays](/forms/arrays).

## Next steps

- [Tuples](/forms/tuples) — fixed-length positional structures.
- [Custom Components](/forms/custom-components) — the full Tier-2
  swap-target workflow.
- [References](/forms/references) — FK pickers, another structural
  field with similar dispatch logic.


---
URL: "ui.atscript.dev/forms/validation"
LLMS_URL: "ui.atscript.dev/forms/validation.md"
outline: "deep"
---

# Validation

Forms in `vue-form` are validated end-to-end without writing a single
schema by hand. Every rule lives on the `.as` type as an annotation,
runs through the atscript validator, and surfaces in the UI through
`AsField`. This page covers the three rule layers, how live validation
fires, fresh-field behaviour and how to merge server-side errors.

## Three layers of rules

```text
@expect.*         (declarative constraints — runs through Validator)
   ▼
@meta.required    (non-empty check + label * marker)
   ▼
@ui.form.validate (custom JS expression — requires @atscript/ui-fns)
```

### Layer 1: `@expect.*`

Defined by atscript core. vue-form just hands them to
`getFormValidator(def)`
(`packages/vue-form/src/composables/use-as-form.ts:178-180`) and walks
the result.

```atscript
@meta.label 'Username'
@meta.required 'Username is required'
@expect.minLength 3, 'Must be at least 3 characters'
@expect.maxLength 20, 'Must be at most 20 characters'
username: string
```

`@expect.min` / `@expect.max` work for numbers and dates;
`@expect.minLength` / `@expect.maxLength` for strings and arrays;
`@expect.pattern` for regex.

### Layer 2: `@meta.required`

The validation message is a positional argument:

```atscript
@meta.required 'Email is required'
email: string.email
```

A required field with a non-string-format failure surfaces the
`required` message; a format failure (e.g. malformed email) surfaces
the validator's format-specific message.

::: tip Optional + required
`field?: string` with `@meta.required` means "if present, can't be
empty". vue-form does **not** paint the required marker on these —
see `as-field.vue:167-181`.
:::

### Layer 3: `@ui.form.validate`

Custom JS expression evaluated against `(value, data, context)`. Return
`true` for pass or a string for error. Requires `@atscript/ui-fns` to
parse the expression.

```atscript
@meta.label 'Password'
@meta.required 'Password is required'
@expect.minLength 8, 'Password must be at least 8 characters'
@ui.form.validate '(v) => /[A-Z]/.test(v) || "Must contain an uppercase letter"'
password: string

@meta.label 'I agree to terms'
@ui.form.validate '(v) => !!v || "You must agree to terms"'
agreeToTerms: ui.checkbox
```

Multiple custom validators on one field run in order — the first
failing one short-circuits.

#### Cross-field validators

The second argument is the full (unwrapped) form data — read sibling
fields to express constraints across the form. The same rule runs on
every keystroke (subject to the `firstValidation` strategy) and on
submit, so the field stays in sync as either side changes.

```atscript
@meta.label 'New password'
newPassword: string

@meta.label 'Confirm password'
@ui.form.validate '(v, data) => v === data.newPassword || "Passwords must match"'
confirmPassword: string
```

For a constraint that depends on multiple fields at once, prefer a
[form-level validator](#form-level-errors) — it runs once at submit
and reports through `__form`.

## A complete example

A `ValidationForm.as` schema that exercises all three layers in one type:

```atscript
@meta.label 'Validation Demo'
@ui.form.submit.text 'Validate & Submit'
export interface ValidationForm {
    @meta.label 'Username'
    @meta.required 'Username is required'
    @expect.minLength 3, 'Must be at least 3 characters'
    @expect.maxLength 20, 'Must be at most 20 characters'
    username: string

    @meta.label 'Email'
    @meta.required 'Email is required'
    email: string.email

    @meta.label 'Age'
    @ui.form.validate '(v) => !!v || "Age is required"'
    @expect.min 18, 'Must be 18 or older'
    @expect.max 120, 'Must be 120 or younger'
    age?: number

    @meta.label 'Password'
    @meta.required 'Password is required'
    @expect.minLength 8, 'Password must be at least 8 characters'
    @ui.form.validate '(v) => /[A-Z]/.test(v) || "Must contain an uppercase letter"'
    password: string

    @meta.label 'I agree to terms'
    @ui.form.validate '(v) => !!v || "You must agree to terms"'
    agreeToTerms: ui.checkbox

    @meta.label 'Tags'
    @expect.minLength 1, 'At least one tag required'
    @expect.maxLength 5, 'Maximum 5 tags'
    tags: string[]
}
```

Mount it the same way as any form:

```vue
<script setup lang="ts">
import { AsForm, createDefaultTypes, createAsFormDef } from "@atscript/vue-form";
import { ValidationForm } from "./ValidationForm.as";

const types = createDefaultTypes();
const { def, formData } = createAsFormDef(ValidationForm);
</script>

<template>
  <AsForm
    :def="def"
    :form-data="formData"
    :types="types"
    @submit="(data) => console.log('valid:', data)"
    @error="(errs) => console.warn('invalid:', errs)"
  />
</template>
```

## When does validation fire?

Each field decides per-keystroke whether it's "validation-active" based
on the form's `firstValidation` strategy
(`packages/vue-form/src/composables/use-as-field.ts:62-77`):

| Strategy          | Becomes active after…                  |
| ----------------- | -------------------------------------- |
| `on-change`       | first submit OR first edit (default)   |
| `touched-on-blur` | first submit OR (edited AND blurred)   |
| `on-blur`         | first submit OR first blur             |
| `on-submit`       | first submit only                      |
| `none`            | never (validation suppressed entirely) |

Pass it as a prop:

```vue
<AsForm :def="def" :form-data="formData" :types="types" first-validation="touched-on-blur" />
```

On **submit**, the entire form validates synchronously — every field
with a rule runs, errors collect, and either `@submit` (clean) or
`@error` (dirty) fires. Sections containing errors auto-expand so the
user can see what went wrong
(`use-as-form.ts:238-248`).

::: info Default is `on-change`
After the first edit on a leaf field, errors update on every
keystroke. Until the user types, validation is silent.
:::

## Fresh fields

Newly-mounted fields are marked **fresh** until the user edits them or
submits again
(`packages/vue-form/src/composables/use-as-state.ts:32-38`). This
prevents a freshly-added array item from lighting up every required
field red the moment it renders.

A field stops being fresh when:

- the user types into it,
- the user tabs through it (blur counts),
- the form submits.

You don't configure freshness — it's automatic for every leaf field.

## External errors

Server-side validation errors land in the form via the `:errors` prop.
The shape is `Record<absolutePath, message>`. Use `__form` as the key
for a form-level banner.

```vue
<AsForm :def="def" :form-data="formData" :types="types" :errors="serverErrors" />
```

```ts
const serverErrors = {
  "address.street": "Unknown address",
  "phones.0.number": "Invalid format",
  __form: "Could not save — please try again",
};
```

External errors **auto-dismiss** as the user edits the offending
field (`as-field.vue:677-683`). The form-level banner has its own
explicit dismiss button. Programmatic dismissal is available via
`useAsForm()`'s `dismissError(path)` and `dismissFormError()`.

For arrays / unions / structured fields the dismissal still works —
any descendant mutation drops the ancestor error from the internal
map too (`use-as-form.ts:302-323`).

## Form-level errors

A custom `@ui.form.validate` on the type itself becomes a form-level
rule (validated at submit and surfaced through `__form`):

```atscript
@ui.form.validate '(_, data) => data.password === data.confirm || "Passwords must match"'
export interface SignupForm { ... }
```

Or push it from your submit handler:

```ts
function onSubmit(data: SignupForm) {
  try {
    await api.signup(data);
  } catch (e) {
    serverErrors.value = { __form: e.message };
  }
}
```

## Programmatic control

The slots on `<AsForm>` expose imperative helpers (see
`use-as-form.ts:108-141`):

```vue
<AsForm :def="def" :form-data="formData" :types="types">
  <template #form.header="{ reset, clearErrors, setErrors }">
    <div class="form-toolbar">
      <button type="button" @click="reset">Reset</button>
      <button type="button" @click="clearErrors">Clear errors</button>
    </div>
  </template>
</AsForm>
```

- `reset()` — re-applies type defaults, clears all errors.
- `clearErrors()` — clears internal + external errors only.
- `setErrors({ path: msg })` — push errors from outside the form (e.g.
  after a server response).

## Action-vs-submit

Form actions (`AsAction` fields) fire `@action` instead of `@submit`
and do **not** validate the entire form by default. See
[Actions](/forms/actions) for action lifecycles and validation
opt-ins.

## Next steps

- [Annotations](/forms/annotations) — full `@expect.*` /
  `@ui.form.validate` reference.
- [Dynamic Fields](/forms/dynamic-fields) — the `@ui.form.fn.*`
  family, including dynamic disabled / hidden that participate in
  validation.
- [Arrays](/forms/arrays) — array-specific length constraints.


---
URL: "ui.atscript.dev/guide"
LLMS_URL: "ui.atscript.dev/guide.md"
---

# Atscript UI

**Your types are your UI.** Annotate a `.as` type once and atscript-ui renders the form, the table, the workflow, and the validation — all from the same schema. No hand-wired field lists, no manual column configs, no duplicated validation rules between client and server.

## What is atscript-ui?

A set of UI packages that read [`.as`](https://atscript.dev) annotated types and render forms, tables, and HTTP workflows on top of Vue 3. The packages share a framework-agnostic core, so the same metadata that drives a Vue table today can drive a React or Solid binding tomorrow without re-annotating a single field.

The split is deliberate:

- **`@atscript/ui`** — framework-agnostic core. `FormDef`, `TableDef`, `FieldResolver`, the `@ui.*` annotation plugin, value-help, validation, decimal helpers.
- **`@atscript/ui-fns`** — opt-in dynamic resolver. Adds `@ui.fn.*` (live computed properties) and `@ui.form.validate` (cross-field validation) via `new Function`. Trusted schemas only.
- **`@atscript/ui-table`** — table model. Filter conditions, sorters, presets, Uniquery conversion, draft mode, window mode.
- **`@atscript/ui-styles`** — UnoCSS preset, `as-*` shortcut tree, baked icon set, `AsResolver` for auto-imports, pre-built CSS for non-UnoCSS apps.
- **`@atscript/vue-form`** — Vue components: `<AsForm>`, `<AsField>`, `<AsIterator>`, plus default field components (`AsInput`, `AsSelect`, `AsCheckbox`, …).
- **`@atscript/vue-table`** — Vue components: `<AsTable>`, `<AsTableRoot>`, `<AsWindowTable>`, `<AsFilters>`, `<AsPresetPicker>`, plus default cells, dialogs, and controls.
- **`@atscript/vue-wf`** — `<AsWfForm>` and `useWfForm()`: a multi-step HTTP workflow form driven by a server-side flow.
- **`@atscript/moost-wf`** — server side of `vue-wf`. Decorators, interceptors, `AsWfStore`.
- **`@atscript/moost-ui-presets`** — server-side persistence for table presets.

## Three things it gives you

### Forms — `@atscript/vue-form`

You annotate fields. The form renders inputs, labels, descriptions, validators, error messages, the submit button, and any nested objects / arrays / unions in the schema. Swap a default field component for your own design system via the `:types` map.

```atscript
@meta.label 'Sign up'
export interface SignUp {
    @meta.label 'Email'
    @meta.required 'Email is required'
    email: string.email

    @meta.label 'Password'
    @ui.type 'password'
    @expect.minLength 8, 'At least 8 characters'
    password: string
}
```

```vue
<script setup lang="ts">
import { useForm } from "@atscript/vue-form";
import { SignUp } from "./sign-up.as";
const { def, formData } = useForm(SignUp);
</script>

<template>
  <AsForm :def="def" :form-data="formData" @submit="onSubmit" />
</template>
```

### Tables — `@atscript/vue-table`

You annotate fields once. The table renders columns, infers filter inputs from the field type (string → text filter, number → range, enum → multi-select), drives sort, pagination, and value-help dialogs. Hook up `:url=` to a `moost-db` REST endpoint and the table writes its filter/sort/page state as a [Uniquery](https://db.atscript.dev) URL.

### Workflows — `@atscript/vue-wf` + `@atscript/moost-wf`

A multi-step form whose steps live on the server. Each step is a Moost handler that defines an `@InputForm` (an `.as` type) and an `@OutputForm`. The client renders the current step with `<AsWfForm>`, submits, gets the next step back. State is persisted server-side via `AsWfStore` and resumable across sessions.

## The 30-second mental model

```
.as file
   │
   │  @meta.* / @expect.* / @ui.* / @db.* / @wf.*
   │
   ▼
asc / unplugin-atscript
   │
   ▼
.as.d.ts   (TypeScript types)
.as.js     (runtime field descriptors)
   │
   ▼
FieldResolver (in @atscript/ui)
   │
   ▼
<AsForm /> / <AsTable /> / <AsWfForm />
```

The component imports the type, asks the `FieldResolver` for every field's metadata (label, default, validators, ui type, grid span, …), and renders. That's the whole loop.

## Where to next

- [Quick Start](./quick-start) — install, configure Vite, and ship a working form + table in ten minutes.
- [Installation](./installation) — every config knob: vite plugin, UnoCSS preset, `AsResolver`, dynamic resolver, locale providers.
- [The `.as` file](./the-as-file) — the five annotation families you'll use and how they fit together.
- [Forms guide](/forms/) — the component tree, validation, arrays, nested objects, unions, dynamic fields.
- [Tables guide](/tables/) — annotations, filtering, sorting, cells, presets.
- [Workflows guide](/workflows/) — server authoring, client form, state persistence.
- [Ecosystem map](./ecosystem) — how the packages fit together and when to reach for which.
- [Bundle optimization](./bundle-optimization) — what you ship and what you don't: per-component subpaths, lazy dialogs, the usage-driven CSS safelist, `excludeComponents`.


---
URL: "ui.atscript.dev/guide/bundle-optimization"
LLMS_URL: "ui.atscript.dev/guide/bundle-optimization.md"
outline: "deep"
---

# Bundle Optimization

atscript-ui ships a lot of UI — form fields, table chrome, four dialogs, workflow forms — but your app should only pay for what it actually renders. The delivery contract is simple: **don't tag it and you don't ship its JS; don't open it and you don't download it; don't use it and its CSS is never generated.** This page explains the mechanics behind that promise and the knobs for trimming further.

## How JS is delivered

### Per-component subpaths

Every `@atscript/vue-*` package is published code-split per component, and every Tier-1 / Tier-2 component has its own subpath export:

```typescript
import AsTableRoot from "@atscript/vue-table/as-table-root";
import AsInput from "@atscript/vue-form/as-input";
import AsWfForm from "@atscript/vue-wf/as-wf-form";
```

`AsResolver()` from `@atscript/ui-styles/vite` resolves template tags to exactly these subpaths — tag `<AsTableRoot>` and only `as-table-root`'s chunk graph enters your bundle. Nothing else from the package rides along. See [Installation](/styling/installation) for the resolver setup.

Barrel imports (`import { AsInput } from "@atscript/vue-form"`) are also safe: every package declares `sideEffects` (`false`, or `["**/*.css"]` for the packages that ship styles), so named imports tree-shake on webpack-class bundlers as well as Rollup/Vite. Subpath imports and `AsResolver()` remain the recommended pattern — they don't depend on the bundler's tree-shaking quality at all.

### Lazy dialogs in `<AsTableRoot>`

`<AsTableRoot>` splits its dialogs by likelihood of use:

| Dialog               | Loading                                                  | Trigger                                   |
| -------------------- | -------------------------------------------------------- | ----------------------------------------- |
| `AsConfirmDialog`    | static — tiny, core to the `prompt()` / confirm path     | always mounted                            |
| `AsConfigDialog`     | lazy (`defineAsyncComponent` behind a first-open latch)  | first time the config dialog opens        |
| `AsFilterDialog`     | lazy, first-open latch                                   | first time a filter dialog opens          |
| `AsPresetDialog`     | lazy, first-open latch                                   | first time the preset dialog opens        |
| `AsActionFormDialog` | lazy, mounted only when an action declares an input form | table def contains an `@InputForm` action |

A user who never opens the config dialog never downloads its chunk. `AsActionFormDialog` matters most: it wraps `<AsForm>` and pulls in the whole `@atscript/vue-form` runtime, so this lazy boundary is what keeps vue-form out of table-only apps. It is deliberately **not** exported from the `@atscript/vue-table` main entry — eager-loading or overriding goes through the dedicated subpath (`@atscript/vue-table/as-action-form-dialog`).

Assigning a component to `controls.configDialog` / `controls.filterDialog` / `controls.presetDialog` / `controls.actionFormDialog` opts that dialog into **eager** mounting — your replacement (or the pre-seeded default) is in the static import graph and ships up front. That's the trade-off of overriding chrome; see [Customization](/tables/customization) for the controls map.

### Cell renderers ride behind `<AsTable>`, not `<AsTableRoot>`

`<AsTableRoot>` is renderless — an app that renders its own list or cards inside its slot ships **no** cell renderers, header chrome, or row-action menus. Those enter the graph through:

- `<AsTable>` / `<AsWindowTable>` — pull in the row-actions cell (`AsRowActions`), the fallback cell (`AsTableCellValue`), and the header cell.
- `createDefaultCellTypes()` — pulls in the typed renderers (`AsCellDate`, `AsCellNumber`, `AsCellArray`, `AsCellJson`, `AsCellUnion`).

## How CSS is emitted (UnoCSS path)

The UnoCSS path is the optimization path: the preset registers an extractor (`createAsExtractor`, wired automatically by `asPresetVunor()`) that scans **your** source and safelists only the classes of components you actually use. The pre-built CSS bundles are the compatibility path — per-branch granularity (`css/form`, `css/table`, …), lazy chrome always included, no per-component trimming. See [Pre-built CSS](/styling/prebuilt-css); the rest of this section applies to the UnoCSS path only.

### The four match channels

A component's classes enter the safelist when your source matches any of:

| Channel        | Example                                                                         |
| -------------- | ------------------------------------------------------------------------------- |
| Subpath import | `import AsTableRoot from "@atscript/vue-table/as-table-root"`                   |
| Barrel import  | `import { AsFilterDialog } from "@atscript/vue-table"`                          |
| Template tag   | `<AsTableRoot>` or `<as-table-root>`                                            |
| Helper call    | `createDefaultTypes()` / `createDefaultControls()` / `createDefaultCellTypes()` |

No match in any channel → the component's classes never reach the generated stylesheet.

### Companions: CSS is eager where JS is lazy

The generated class maps split a component's footprint in two: `componentClasses[name]` holds only the component's **own** classes; `componentCompanions[name]` lists the tracked components it renders or lazy-mounts. The extractor expands companions recursively — so matching `<AsTableRoot>` safelists the classes of all its companions, including the lazily loaded dialogs and the cell / header / filter chrome.

This asymmetry is deliberate: a lazy JS chunk arrives at runtime, long after the CSS build finished, so its classes must be in the stylesheet up front or the dialog would render unstyled on first open. The cost is dead CSS in apps that never open those dialogs — which is exactly what `excludeComponents` is for.

### `excludeComponents`

Pass kebab-case component names to `asPresetVunor()` (or `createAsExtractor()` directly) to veto components from the safelist. Each companion is vetoed independently, including through expansion chains:

```typescript
// uno.config.ts — app mounts <AsTableRoot> but never opens the built-in dialogs
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  presets: asPresetVunor({
    excludeComponents: [
      "as-config-dialog",
      "as-filter-dialog",
      "as-preset-dialog",
      "as-action-form-dialog",
    ],
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

Excluding a component also prunes everything reachable **only** through it — in a `<AsTableRoot>`-only app, excluding `as-filter-dialog` also drops the value-help window-table chrome that nothing else pulls in. A companion that's still reachable through another kept component stays in.

::: warning Exclusion is build-wide and absolute
`excludeComponents` wins over every match channel: tagging `<AsFilterDialog>` directly or importing it elsewhere in the app still emits nothing while it's excluded. Only exclude components that **no** screen in the app renders — otherwise that screen renders unstyled.
:::

### Mount only the shortcut branches you use

The shortcut tree is also split per branch: `commonShortcuts`, `formShortcuts`, `tableShortcuts`, `wfShortcuts`, `aoothShortcuts` — with `allShortcuts` as the merge. A forms-only app can register a narrower tree:

```typescript
import { commonShortcuts, formShortcuts, mergeVunorShortcuts } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(mergeVunorShortcuts([commonShortcuts, formShortcuts]))],
});
```

With the extractor in place this is belt-and-braces — unmatched shortcuts don't generate CSS anyway — but it bounds what _can_ be emitted and speeds up shortcut resolution.

## Recipes

### Custom list on `<AsTableRoot>`

You use `<AsTableRoot>` for querying, filtering state, and pagination, but render your own cards/list in the slot. JS is already minimal (renderless root, no cell renderers). For CSS, shed the dialog and table-chrome companions:

```typescript
asPresetVunor({
  excludeComponents: [
    // dialogs you never open
    "as-config-dialog",
    "as-filter-dialog",
    "as-preset-dialog",
    "as-action-form-dialog",
    // cell / header / row chrome you don't render
    "as-table-header-cell",
    "as-table-cell-value",
    "as-row-actions",
    "as-column-menu",
    "as-filter-field",
    "as-filter-input",
    "as-cell-array",
    "as-cell-date",
    "as-cell-json",
    "as-cell-number",
    "as-cell-union",
  ],
});
```

Keep `as-confirm-dialog` if you use `state.prompt()` / confirm-gated actions — it's always mounted.

### Forms-only app

Don't import `@atscript/vue-table` anywhere; `AsResolver()` only resolves what you tag, so nothing table-shaped enters the JS graph. Mount `commonShortcuts` + `formShortcuts` instead of `allShortcuts` (snippet above). No `excludeComponents` needed — the extractor never matches table components in the first place. On the no-UnoCSS path the equivalent is the `css/form` bundle — see [Pre-built CSS](/styling/prebuilt-css).

### Custom cells while keeping `<AsTable>`

You render `<AsTable>` but supply your own cell components via `:types` and never call `createDefaultCellTypes()`. **JS is automatic:** the typed default cells (`AsCellDate`, `AsCellNumber`, `AsCellJson`, `AsCellArray`, `AsCellUnion`) only enter the bundle through that helper — skip the call and they never ship. `AsTableCellValue` and `AsRowActions` still ride along: they're hard fallbacks inside the table renderers. **CSS is not automatic:** matching `as-table-root` safelists the default cells' classes as companions, so opt out explicitly — the prop is typed against the generated component-name union, so your editor autocompletes every name:

```typescript
asPresetVunor({
  excludeComponents: [
    "as-cell-array",
    "as-cell-date",
    "as-cell-json",
    "as-cell-number",
    "as-cell-union",
  ],
});
```

Add `as-table-cell-value` / `as-row-actions` to the list only if you've replaced those too — by default they still render.

### Replaced a default — shed its styles

You swapped the filter dialog for your own via `controls.filterDialog` (see [Customization](/tables/customization)). Your component now mounts eagerly and carries its own styles; the default's classes are dead weight:

```typescript
asPresetVunor({
  excludeComponents: ["as-filter-dialog"],
});
```

The same applies to any replaced Tier-2 default — `as-input` after swapping the form text field, `as-row-actions` after a design-system row menu, and so on.

## DOs and DON'Ts

- **DO** import via subpaths or tag via `AsResolver()` — **DON'T** deep-import `@atscript/vue-table/as-action-form-dialog` eagerly at the app entry "just in case"; it re-bundles the entire `@atscript/vue-form` runtime into table-only screens.
- **DO** let the dialogs lazy-load — **DON'T** seed `controls.X` with the default dialog component unless you deliberately want eager loading.
- **DO** pass only your actual overrides in `:controls` — **DON'T** pass `createDefaultControls()` wholesale; it statically imports the dialogs and flips them to eager. Every dispatch site falls back to its built-in internally.
- **DO** pass `excludeComponents` for replaced or never-used chrome — **DON'T** expect the pre-built CSS bundles to trim per component; they only split per branch.
- **DO** verify an exclusion app-wide before adding it — **DON'T** exclude a component any screen still renders; exclusion overrides direct matches and that screen will render unstyled.
- **DO** mount only the shortcut branches your app uses — **DON'T** hand-maintain a manual `safelist` for `as-*` classes; the extractor already covers every supported usage channel.

## See also

- [Styling — Installation](/styling/installation) — the UnoCSS + `AsResolver()` setup this page builds on.
- [Pre-built CSS](/styling/prebuilt-css) — the no-UnoCSS path and its trade-offs.
- [Tables — Customization](/tables/customization) — the `controls` map and lazy control entries.
- [API — @atscript/ui-styles](/api/ui-styles) — `asPresetVunor`, `createAsExtractor`, the class/companion maps, shortcut groups.


---
URL: "ui.atscript.dev/guide/ecosystem"
LLMS_URL: "ui.atscript.dev/guide/ecosystem.md"
outline: "deep"
---

# Ecosystem Map

atscript-ui sits inside a three-site family. They share one source-of-truth (the `.as` file) and split responsibility by layer: language at the bottom, database in the middle, UI on top.

## The three sibling sites

| Site                                           | What it covers                                                                                                                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [**atscript.dev**](https://atscript.dev)       | The `.as` language: `@meta.*`, `@expect.*`, primitives, `asc` codegen, `unplugin-atscript`, the `Validator`, JSON Schema export, VSCode LSP, plugin authoring.                 |
| [**db.atscript.dev**](https://db.atscript.dev) | The DB layer: `@db.*` annotations, adapters (sqlite / postgres / mysql / mongo), `DbSpace`, `BaseDbAdapter`, schema sync, relations, queries, `moost-db` REST, browser Client. |
| **ui.atscript.dev** (this site)                | The UI layer: forms, tables, workflows, styling. The `@ui.*` and `@wf.*` annotation families. Vue 3 today; framework-agnostic core ready for React / Solid bindings tomorrow.  |

The boundary is clean — atscript doesn't know about HTTP, atscript-db doesn't know about Vue, atscript-ui doesn't know about your SQL dialect. A `.as` file flows through all three.

::: tip Built on top: Aooth
[**Aooth**](https://aooth.moost.org) — auth + RBAC for the Moost / atscript ecosystem — ships login, password-recovery, and invite workflows whose `.as` form models are rendered client-side by `<AsWfForm>` from `@atscript/vue-wf`. A working example of the four-layer story: `.as` → DB → server workflow → rendered UI.
:::

## Package dependency graph

```
@atscript/ui                ← framework-agnostic core: FormDef, TableDef,
  │                          annotation keys, FieldResolver, validators
  │
  ├─ @atscript/ui-fns       ← opt-in: dynamic @ui.fn.* computed props
  │                          (uses new Function)
  │
  ├─ @atscript/ui-table     ← framework-agnostic: filter model,
  │                          filter→Uniquery, presets
  │
  ├─ @atscript/ui-styles    ← shared UnoCSS preset + as-* shortcuts +
  │                          icons + AsResolver (consumed by every vue-* pkg)
  │
  ├─ @atscript/vue-form     ← Vue 3 form components + composables
  │
  ├─ @atscript/vue-table    ← Vue 3 table components + composables
  │                          (depends on ui-table)
  │
  ├─ @atscript/vue-wf       ← Vue 3 workflow form: HTTP round-trip loop
  │                          driven by atscript metadata
  │
  ├─ @atscript/vue-aooth    ← Aooth-flavoured custom field components
  │                          (consent + password rules)
  │
  ├─ @atscript/moost-wf     ← Moost server-side workflow:
  │                          decorators, interceptors, AsWfStore
  │
  └─ @atscript/moost-ui-presets ← Moost controller + atscript schema
                              for table-preset persistence
```

External deps each package leans on:

- All client packages depend on Vue 3 and consume `@atscript/ui-styles`.
- `vue-wf` and `vue-table` also consume `@atscript/vue-form` (the form is how steps and value-help dialogs render).
- `vue-aooth` consumes `@atscript/vue-form` (its components implement `TAsComponentProps`) and `@atscript/ui-fns` (for evaluating policy rule strings via `compileFieldFn`).
- `moost-wf` and `moost-ui-presets` depend on [Moost](https://moost.org/) and live alongside any server adapter you already use.
- `vue-table`'s URL data path expects a [`moost-db`](https://db.atscript.dev/http/) compatible endpoint. Any `(params) => { data, total }` function works as an alternative — see [Tables: Query function](/tables/query-function).

## When to use which package

| I want…                                               | Install                                                                                                                                                                |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Just forms (no tables, no workflows)                  | `@atscript/ui` `@atscript/ui-styles` `@atscript/vue-form`                                                                                                              |
| Forms + tables                                        | + `@atscript/ui-table` `@atscript/vue-table`                                                                                                                           |
| Forms + tables + HTTP workflows                       | + `@atscript/vue-wf` (client), `@atscript/moost-wf` (server)                                                                                                           |
| Aooth consent + password-policy UI in those forms     | + `@atscript/vue-aooth`                                                                                                                                                |
| Server-side preset persistence (saved-views per user) | + `@atscript/moost-ui-presets`                                                                                                                                         |
| Dynamic, schema-defined computed props (`@ui.fn.*`)   | + `@atscript/ui-fns` (and call `installDynamicResolver()`)                                                                                                             |
| My own framework binding (React / Solid / Svelte)     | Port from `@atscript/ui` + `@atscript/ui-table`. Re-use `@atscript/ui-styles`' pre-built CSS (`@atscript/ui-styles/css/all`) or the UnoCSS preset.                     |
| To author a new annotation namespace                  | Read the plugin guide on [atscript.dev](https://atscript.dev). atscript-ui's plugins (`@atscript/ui/plugin`, `@atscript/ui-fns/plugin`) are reference implementations. |

The Vue split (`vue-form` / `vue-table` / `vue-wf`) intentionally mirrors the agnostic split (`ui` / `ui-table`). Every reactive primitive, default component, and resolver wrapper in a `vue-*` package has a corresponding pure-TS piece in the agnostic core. That's what makes the React / Solid port path realistic.

## Glossary

A one-line definition of every term that recurs in the docs. Click through for the full API.

- **FormDef** — the materialised form descriptor a `useForm()` call returns. Fields, validators, layout, submit action, all resolved from `.as` metadata. [API](/api/ui).
- **TableDef** — the materialised table descriptor `<AsTableRoot>` builds. Columns, filterable fields, sortable fields, default sort, value-help wiring. [API](/api/ui).
- **FieldResolver** — the indirection layer between annotations and rendered components. Reads `@ui.*` from the `.as` runtime descriptor; `ui-fns` swaps in a dynamic version that also evaluates `@ui.fn.*`. [API](/api/ui).
- **FilterCondition** — a single applied filter (`{ field, op, value }`). Mutated by filter chips / dialogs. [API](/api/ui-table).
- **FieldFilters** — the _display_ list of which filter inputs are visible. Independent of which filters are applied. [API](/api/ui-table).
- **PresetSnapshot** — a frozen `{ filters, sorters, columns, search, pagination }` blob users save as a "saved view". Persisted by `moost-ui-presets`. [API](/api/ui-table).
- **TFnScope** — the `{ formData, row, def, locale }` object `@ui.fn.*` function-strings run inside. [API](/api/ui-fns).
- **AsWfStore** — server-side workflow state container. Tracks current step, persisted form data, context, outlets. [API](/api/moost-wf).
- **`@InputForm` / `@OutputForm`** — Moost decorators on a workflow handler. The atscript types they reference are what `<AsWfForm>` renders. [API](/api/moost-wf).
- **AsResolver** — the `unplugin-vue-components` resolver that auto-imports Tier-1 atscript-ui components. Shipped from `@atscript/ui-styles/vite`. [API](/api/ui-styles).
- **`asPresetVunor`** — the UnoCSS preset that wires up the vunor shortcuts engine + the `as-*` shortcut tree + the baked icon set. [Styling](/styling/).
- **Uniquery** — the URL-encoded query format `moost-db` understands. `<AsTableRoot>` serialises filter/sort/page state into it. [db.atscript.dev](https://db.atscript.dev).

## What's next

- [Quick Start](./quick-start) — wire up Vite and render your first form + table.
- [The `.as` file](./the-as-file) — the five annotation families.
- [Forms](/forms/) — components and patterns.
- [Tables](/tables/) — query, filter, sort, presets.
- [Workflows](/workflows/) — multi-step HTTP forms.


---
URL: "ui.atscript.dev/guide/installation"
LLMS_URL: "ui.atscript.dev/guide/installation.md"
outline: "deep"
---

# Installation

A full reference for wiring atscript-ui into a Vue 3 + Vite project. The [Quick Start](./quick-start) gets you running in ten minutes; this page covers every knob.

## Pick your packages

You only need the packages whose components you actually render.

| Use case                       | Install                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Forms only                     | `@atscript/ui` `@atscript/ui-styles` `@atscript/vue-form`                                            |
| Forms + tables                 | `@atscript/ui` `@atscript/ui-table` `@atscript/ui-styles` `@atscript/vue-form` `@atscript/vue-table` |
| Forms + tables + workflows     | + `@atscript/vue-wf` on the client, `@atscript/moost-wf` on the server                               |
| Server-side preset persistence | + `@atscript/moost-ui-presets` on the server                                                         |
| Dynamic annotations            | + `@atscript/ui-fns` (opt-in: enables `@ui.fn.*` and `@ui.form.validate`)                            |

Every flavour also wants `vunor` (the internal shortcuts engine atscript-ui composes against), `unocss`, `unplugin-atscript`, `unplugin-vue-components`, and `@atscript/typescript` as dev deps:

```bash
pnpm add vunor
pnpm add -D unocss unplugin-atscript unplugin-vue-components @atscript/typescript
```

## Vite configuration

The Vite config has four moving pieces:

1. **`unplugin-atscript/vite`** — compiles `.as` files (`.as.d.ts` + `.as.js`).
2. **`unocss/vite`** — runs the atscript-ui UnoCSS preset.
3. **`@vitejs/plugin-vue`** — the usual Vue plugin.
4. **`unplugin-vue-components/vite`** with `AsResolver()` — auto-imports `<AsForm>`, `<AsTable>`, etc.

```ts
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import atscript from "unplugin-atscript/vite";
import UnoCSS from "unocss/vite";
import Components from "unplugin-vue-components/vite";
import { AsResolver } from "@atscript/ui-styles/vite";

export default defineConfig({
  plugins: [atscript(), UnoCSS(), vue(), Components({ resolvers: [AsResolver()] })],
});
```

::: warning SSR + native deps
If you SSR a moost-db / moost-wf server with native database drivers, mark them external. Example:

```ts
ssr: {
  external: ["@atscript/db", "@atscript/db-sqlite", "better-sqlite3"];
}
```

:::

## UnoCSS configuration

`asPresetVunor()` returns a `Preset[]` you pass straight to `presets:`. **Do not wrap it in a second array** — UnoCSS will flatten silently and you'll get inconsistent class output.

```ts
// uno.config.ts
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  content: {
    filesystem: ["src/**/*.{vue,ts,tsx}"],
  },
  presets: asPresetVunor({
    // The full vunor presetVunor() theme is accepted flat here. Omitted
    // fields fall back to atscript-ui's baked defaults. See
    // /styling/theme for the full option list.
    baseRadius: "8px",
    palette: { colors: { primary: "#a855f7" } }, // keeps grey/neutral/error defaults
    // fingertip: { m: "36px" },
    // Drop classes for defaults you've swapped out (post-match exclusion)
    excludeComponents: ["as-filter-dialog"],
    // Override one of the baked icons by name
    iconOverrides: {
      search: '<svg viewBox="0 0 24 24"><path d="..." fill="currentColor"/></svg>',
    },
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

What the preset does:

- Registers the vunor shortcuts engine atscript-ui depends on internally (scopes, layers, surfaces, `c8-*` clickables, `i8-*` inputs, fingertip-\* heights, spacing tokens `$xxs..$xxl`).
- Registers the `as-*` shortcut tree from `@atscript/ui-styles` (every component's styles live here, not in `.vue` templates).
- Registers a custom extractor that scans your sources for `<AsForm>` / `useForm` / `createDefaultTypes` / etc. and pulls in the matching pre-computed class lists. **You don't have to add `node_modules` to `content.filesystem`.**
- Bakes in an icon set under the `as` collection (`i-as-search`, `i-as-close`, `i-as-loading`, …).

For theme tuning, per-component safelist control, and pre-built CSS see [Styling](/styling/).

## `AsResolver` — auto-imports

`AsResolver()` from `@atscript/ui-styles/vite` plugs into `unplugin-vue-components` and routes every Tier-1 atscript-ui component to its per-component subpath.

```ts
import Components from "unplugin-vue-components/vite";
import { AsResolver } from "@atscript/ui-styles/vite";

Components({ resolvers: [AsResolver()] });
```

What auto-resolves:

| Auto-imported (Tier 1)                                                                                                                               | NOT auto-imported (Tier 2)                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `<AsForm>` `<AsField>` `<AsIterator>` `<AsTable>` `<AsTableRoot>` `<AsWindowTable>` `<AsTableActions>` `<AsFilters>` `<AsPresetPicker>` `<AsWfForm>` | Default field components (`AsInput`, `AsSelect`, `AsCheckbox`, …), default cells, default dialogs |

Tier-2 defaults are swap targets you compose through `:types` / `:components` prop maps, not template tags — so the resolver intentionally skips them. Composables (`useForm`, `useTable`, `useWfForm`) are not components and always need an explicit import. See [Styling: AsResolver](/styling/installation#asresolver-auto-import) for the full pattern.

## Atscript config

Create `atscript.config.js` (or `.ts`) at the project root so `asc` and `unplugin-atscript` can resolve the right plugins:

```js
// atscript.config.js
import ts from "@atscript/typescript";
import uiPlugin from "@atscript/ui/plugin";
import uiFnsPlugin from "@atscript/ui-fns/plugin";

export default {
  plugins: [ts(), uiPlugin(), uiFnsPlugin()],
};
```

If you use atscript-db tables or workflow forms, add their plugins:

```js
import dbPlugin from "@atscript/db/plugin";
import wfPlugin from "@atscript/moost-wf/plugin";

export default {
  plugins: [ts(), dbPlugin(), uiPlugin(), uiFnsPlugin(), wfPlugin()],
};
```

Each plugin teaches the compiler about its annotation namespace (`@ui.*`, `@db.*`, `@wf.*`, `@ui.fn.*`). Skip a plugin and the compiler will reject those annotations as unknown. The full atscript-config reference is at [atscript.dev/packages/typescript](https://atscript.dev/packages/typescript).

## Dynamic resolver (opt-in)

`@atscript/ui-fns` enables two things on top of static annotations:

- **`@ui.fn.*`** — any `@ui.*` value can be expressed as a function-string that gets compiled to a live computed property. Lets you say "this field is hidden when `formData.value.kind === 'guest'`" or "this column's title depends on the row".
- **`@ui.form.validate`** — cross-field validators expressed as function-strings; run after per-field `@expect.*` checks.

Activate by calling once in your entry-client:

```ts
import { installDynamicResolver } from "@atscript/ui-fns";
installDynamicResolver();
```

::: warning Security
Both features compile annotation strings into runtime functions via `new Function`. Only enable on builds where every `.as` file is trusted (i.e. your own source tree, vetted dependencies). Do not feed user-authored schemas through the dynamic resolver without sandboxing.
:::

Skip it entirely — don't install the package, don't call the function — if you only use static annotations. The static resolver in `@atscript/ui` handles `@meta.*`, `@expect.*`, and literal-valued `@ui.*` without any runtime compilation.

## Locale providers (optional)

The default field components ship with English labels for built-in affordances (placeholder hints, "Required", "Add row", "Show filters", error formatting). Override them at the root of your app:

```vue
<!-- App.vue -->
<script setup lang="ts">
import { provideAsLocale } from "@atscript/vue-form";
import { provideCellLocale } from "@atscript/vue-table";

provideAsLocale({
  required: "Обязательно",
  addRow: "Добавить",
});

provideCellLocale({
  noData: "Нет данных",
  rowsPerPage: "Строк на странице",
});
</script>
```

Both providers are shallow — pass only the keys you want to override. The forms locale ships from `@atscript/vue-form`, the cell/table locale from `@atscript/vue-table`. Their full key lists are at [Forms: Locale](/forms/locale).

## Pre-built CSS without UnoCSS

If your app doesn't run UnoCSS at all, import a pre-baked stylesheet at the entry:

```ts
import "@atscript/ui-styles/css/all";
```

Per-package files (`form.css`, `table.css`, `wf.css`) exist too but **don't combine them** — they overlap on shared shortcuts. Use `all.css` for any multi-package consumer. The pre-built CSS uses the default theme + default icons; for theme tuning or icon overrides, switch back to the UnoCSS path. Full details at [Styling: Pre-built CSS](/styling/prebuilt-css).

## What's next

- [The `.as` file](./the-as-file) — annotation families you'll use here.
- [Forms](/forms/) — components, validation, custom field types.
- [Tables](/tables/) — query function, filtering, sorters, presets.
- [Styling](/styling/) — theme, icons, pre-built CSS, shortcut tree.


---
URL: "ui.atscript.dev/guide/quick-start"
LLMS_URL: "ui.atscript.dev/guide/quick-start.md"
outline: "deep"
---

# Quick Start

Build a working form and a working table from `.as` schemas in about ten minutes. By the end you'll have:

- A Vue 3 + Vite app with `unplugin-atscript`, UnoCSS, and `AsResolver` wired up.
- A `Contact.as` schema rendering as `<AsForm>` with labels, validation, and a submit button.
- A `Product.as` schema rendering as `<AsTable>` against a `moost-db` REST endpoint with filtering, sort, and pagination.

::: info Prerequisites
This guide assumes you already have a Vue 3 + Vite project and you're comfortable installing the atscript toolchain. If `asc` and `.as.d.ts` are new concepts, run through the [atscript Quick Start](https://atscript.dev/packages/typescript/quick-start) first — it takes five minutes and explains the compilation model that drives every page below.
:::

## 1. Install

```bash
pnpm add @atscript/ui @atscript/ui-fns @atscript/ui-styles @atscript/vue-form @atscript/vue-table vunor
pnpm add -D @atscript/typescript unplugin-atscript unplugin-vue-components unocss
```

What each package does:

- **`@atscript/ui`** — framework-agnostic core (FieldResolver, FormDef, TableDef, validators).
- **`@atscript/ui-styles`** — UnoCSS preset, `AsResolver`, baked icon set.
- **`@atscript/vue-form` / `@atscript/vue-table`** — Vue 3 components.
- **`vunor`** — the internal shortcuts/styling engine atscript-ui composes its `as-*` classes on top of.
- **`@atscript/typescript`** + **`unplugin-atscript`** — compile `.as` files to `.as.d.ts` and `.as.js` (the bundler does this in-memory at dev time).
- **`@atscript/ui-fns`** — opt-in dynamic resolver (we'll use it for `@ui.fn.*` and `@ui.form.validate`).
- **`unplugin-vue-components`** — auto-imports `<AsForm>` / `<AsTable>` etc. via `AsResolver()`.

## 2. Configure atscript

Create `atscript.config.js` at the project root. Register the TypeScript plugin (so `.as` codegen runs) plus the `ui` plugin (so `@ui.*` annotation keys are recognised by the compiler):

```js
// atscript.config.js
import ts from "@atscript/typescript";
import uiPlugin from "@atscript/ui/plugin";
import uiFnsPlugin from "@atscript/ui-fns/plugin";

export default {
  plugins: [ts(), uiPlugin(), uiFnsPlugin()],
};
```

If you'll also use [atscript-db](https://db.atscript.dev) tables or workflow forms, add `dbPlugin()` and `wfPlugin()` here.

## 3. Wire up Vite

The Vite config does three things: compile `.as` files (`unplugin-atscript`), auto-import primary atscript-ui components (`AsResolver`), and process UnoCSS (`UnoCSS`).

```ts
// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import atscript from "unplugin-atscript/vite";
import UnoCSS from "unocss/vite";
import Components from "unplugin-vue-components/vite";
import { AsResolver } from "@atscript/ui-styles/vite";

export default defineConfig({
  plugins: [atscript(), UnoCSS(), vue(), Components({ resolvers: [AsResolver()] })],
});
```

`AsResolver()` only auto-imports Tier-1 components — the ones you write as tags: `<AsForm>`, `<AsField>`, `<AsIterator>`, `<AsTable>`, `<AsTableRoot>`, `<AsWindowTable>`, `<AsFilters>`, `<AsPresetPicker>`, `<AsWfForm>`. Default field components (`AsInput`, `AsSelect`, …) and composables (`useForm`, `useTable`, …) are always explicit imports — see [Installation](./installation#dynamic-resolver-opt-in) for the rationale.

## 4. Wire up UnoCSS

Add `asPresetVunor()` to `uno.config.ts`:

```ts
// uno.config.ts
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  content: {
    filesystem: ["src/**/*.{vue,ts,tsx}"],
  },
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

`asPresetVunor()` returns a `Preset[]` — **do not wrap it in another array**. The preset bundles the vunor shortcuts engine + an extractor that scans your sources for atscript-ui imports and pulls in the matching per-component class lists from the safelist. See [Styling](/styling/installation) for theme tuning, icon overrides, and `excludeComponents`.

## 5. App entry

```ts
// src/main.ts
import { createApp } from "vue";
import { installDynamicResolver } from "@atscript/ui-fns";
import App from "./App.vue";
import "@unocss/reset/tailwind.css";
import "virtual:uno.css";

installDynamicResolver();
createApp(App).mount("#app");
```

::: warning installDynamicResolver
`installDynamicResolver()` activates `@ui.fn.*` and `@ui.form.validate` — both compile annotation strings into runtime functions via `new Function`. Only call it if you trust every `.as` file in your build. Skip the call (and the import) if you only use static annotations.

**SSR**: call this from the **client entry only** (e.g. `entry-client.ts`). Forms render on the client; the dynamic resolver has nothing to do on the server, and `new Function` in the Node entry widens the schema-injection surface for no upside.
:::

## 6. Your first form

Create `src/forms/contact.as`:

```atscript
@meta.label 'Contact'
@ui.form.submit.text 'Send'
export interface Contact {
    @meta.label 'Name'
    @ui.form.placeholder 'Jane Doe'
    @meta.required 'Name is required'
    @ui.form.order 1
    name: string

    @meta.label 'Email'
    @ui.form.placeholder 'jane@example.com'
    @meta.required 'Email is required'
    @ui.form.order 2
    email: string.email

    @meta.label 'Message'
    @ui.type 'textarea'
    @expect.minLength 10, 'At least 10 characters'
    @ui.form.order 3
    message: string
}
```

Render it:

```vue
<!-- src/views/Contact.vue -->
<script setup lang="ts">
import { useForm } from "@atscript/vue-form";
import { Contact } from "../forms/contact.as";

const { def, formData, validate } = useForm(Contact);

function onSubmit() {
  if (!validate()) return;
  console.log("Submitted:", formData.value);
}
</script>

<template>
  <AsForm :def="def" :form-data="formData" @submit="onSubmit" />
</template>
```

What you get out of the box:

- Labels and placeholders from `@meta.label` / `@ui.form.placeholder`.
- Required + length validation from `@meta.required` / `@expect.minLength`.
- A textarea instead of a single-line input on `message` because `@ui.type 'textarea'`.
- A submit button labeled `Send` (from `@ui.form.submit.text`).
- Field ordering from `@ui.form.order`.

::: details Where to look next for more form patterns
The full forms guide at [/forms/](/forms/) covers arrays, nested objects, unions, refs, dynamic fields, and validation with runnable examples.
:::

## 7. Your first table

Annotate a `.as` schema. If you're using [atscript-db](https://db.atscript.dev) the same file doubles as your DB table; otherwise omit the `@db.*` lines.

```atscript
// src/schemas/Product.as
@db.table 'products'
export interface Product {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Name'
    @db.index.fulltext 'products_search'
    name: string

    @meta.label 'SKU'
    @db.index.unique 'products_sku_idx'
    sku: string

    @meta.label 'Price'
    @db.amount.currency 'USD'
    @db.column.precision 10, 2
    @db.index.plain 'products_price_idx'
    price: decimal

    @meta.label 'Tags'
    tags: string[]

    @meta.label 'Created'
    @db.default.now
    createdAt: number.timestamp
}
```

Render the table. `<AsTableRoot>` owns query state (filters, sort, pagination); `<AsTable>` renders the rows:

```vue
<!-- src/views/Products.vue -->
<script setup lang="ts">
import { Product } from "../schemas/Product.as";
</script>

<template>
  <AsTableRoot :type="Product" url="/api/products">
    <AsFilters />
    <AsTable />
  </AsTableRoot>
</template>
```

What this does:

- `AsTableRoot` derives a `TableDef` from `Product`. Every annotated field becomes a column candidate.
- `AsFilters` renders inline filter chips. The filter input for each field is inferred from its type — string → text, number → range, enum → multi-select.
- `AsTable` renders the body. Sort is one click on the header; the page bar at the bottom is automatic.
- The `url="/api/products"` is a [`moost-db`](https://db.atscript.dev/http/) REST endpoint. The table writes its filter/sort/page state as a [Uniquery](https://db.atscript.dev) query string and reads `{ data, total }` back.

::: tip Don't have a server yet?
You can also pass a `:query` function — any `(params) => Promise<{ data, total }>` works. See [Query function](/tables/query-function) for the contract.
:::

## 8. Build the schemas

When you change a `.as` file at dev time, `unplugin-atscript` regenerates the runtime descriptor in-memory and HMR picks it up. For production builds, run `asc` to emit `.as.d.ts` files alongside your sources so TypeScript can resolve the imports:

```bash
npx asc
```

You only need to run this when types change. The vite plugin handles the rest.

## What's next

- [The `.as` file](./the-as-file) — the five annotation families (`@meta.*`, `@expect.*`, `@ui.*`, `@db.*`, `@wf.*`) and how they compose.
- [Forms](/forms/) — field types, arrays, nested objects, unions, dynamic fields, custom components.
- [Tables](/tables/) — filtering, sorting, custom cells, presets, URL state, value-help.
- [Workflows](/workflows/) — multi-step HTTP forms with server-driven state.
- [Styling](/styling/) — theme, icons, pre-built CSS, `as-*` shortcuts.


---
URL: "ui.atscript.dev/guide/the-as-file"
LLMS_URL: "ui.atscript.dev/guide/the-as-file.md"
outline: "deep"
---

# The `.as` File

A `.as` file is the single source of truth in the atscript ecosystem: types, validation rules, UI configuration, database schema, and workflow metadata all live next to each other on the same interface. Everything atscript-ui renders is read out of these files.

This page is a primer for the annotation families you'll touch most when building UIs. The full language reference is at [atscript.dev](https://atscript.dev).

## What is a `.as` file?

`.as` is the atscript file extension. The language is a strict subset of TypeScript-style type declarations (`interface`, `type`, primitives, unions, arrays, tuples) annotated with `@*.*` decorators that carry metadata.

When you save a `.as` file, the compiler (`asc` from the CLI, or `unplugin-atscript` from a bundler) emits two artefacts next to it:

- **`<name>.as.d.ts`** — pure TypeScript types. Importing from `.as` resolves through these in the IDE.
- **`<name>.as.js`** — runtime field descriptors. This is the object atscript-ui's `FieldResolver` reads to know which UI to render, which validators to run, what the label says, which database table backs it, etc.

```text
contact.as
   │
   │  asc / unplugin-atscript
   ▼
contact.as.d.ts   ← TypeScript sees this when you `import { Contact } from './contact.as'`
contact.as.js     ← Vue components read this at runtime via the FieldResolver
```

You import from `'./contact.as'` and both halves are wired up. See the [atscript Build Setup guide](https://atscript.dev/packages/typescript/build-setup) for the full compilation model.

## The five annotation families

`.as` annotations are namespaced by family. The compiler plugins you register in `atscript.config.js` decide which namespaces are valid. For atscript-ui you'll use five.

### `@meta.*` — atscript core

The portable, framework-agnostic metadata. Every atscript-aware tool understands these.

| Key                 | Purpose                                                               |
| ------------------- | --------------------------------------------------------------------- |
| `@meta.label`       | Human-readable label for a type or field.                             |
| `@meta.description` | Long-form description (used as form hint / column tooltip).           |
| `@meta.required`    | Mark a field as required, with the error message as the argument.     |
| `@meta.default`     | Static default value (typed as a string literal; coerced at runtime). |
| `@meta.id`          | Mark the primary-id field of a record.                                |
| `@meta.readonly`    | Field is read-only at the metadata level (forms render disabled).     |
| `@meta.sensitive`   | Field should be redacted in logs / dev tools.                         |

Full reference: [atscript.dev/api/meta](https://atscript.dev).

### `@expect.*` — atscript core

Validation rules. Run by the `Validator` in `@atscript/ui` and reused server-side by [`@atscript/moost-validator`](https://atscript.dev).

| Key                             | Purpose                        |
| ------------------------------- | ------------------------------ |
| `@expect.minLength n, 'msg'`    | Minimum string / array length. |
| `@expect.maxLength n, 'msg'`    | Maximum string / array length. |
| `@expect.min n, 'msg'`          | Minimum numeric value.         |
| `@expect.max n, 'msg'`          | Maximum numeric value.         |
| `@expect.pattern '/re/', 'msg'` | Regex pattern.                 |
| `@expect.email 'msg'`           | Email format.                  |
| `@expect.url 'msg'`             | URL format.                    |

Full list: [atscript.dev](https://atscript.dev).

### `@ui.*` — this repo

UI-specific configuration. The `@atscript/ui/plugin` registers the namespace; every component in atscript-ui reads its values through the `FieldResolver`.

Three sub-namespaces show up most:

| Sub-namespace | Used by                        | Common keys                                                                                           |
| ------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `@ui.form.*`  | `<AsForm>`, `<AsField>`        | `placeholder`, `hint`, `order`, `hidden`, `disabled`, `grid.colSpan`, `submit.text`, `label.singular` |
| `@ui.table.*` | `<AsTable>`, `<AsFilters>`     | `hidden`, `order`, `width`, `align`, `cell`, `headerCell`                                             |
| `@ui.type`    | both                           | The UI type id: `text`, `password`, `number`, `textarea`, `select`, `radio`, `checkbox`, …            |
| `@ui.fn.*`    | both (with `ui-fns` installed) | Dynamic computed properties: function-string body that reads `{ formData, row, … }`.                  |

The full list per-component lives in the [Forms annotations](/forms/annotations) and [Tables annotations](/tables/annotations) guides.

### `@db.*` — atscript-db

Database semantics. The `dbPlugin()` registers the namespace; `DbSpace` and `moost-db` read these. atscript-ui doesn't read `@db.*` directly, but the same `.as` file is what your form / table renders against.

| Key                            | Purpose                                                    |
| ------------------------------ | ---------------------------------------------------------- |
| `@db.table 'name'`             | This interface backs a database table.                     |
| `@db.json`                     | Field is stored as a JSON column (nested objects, unions). |
| `@db.index.fulltext 'idxName'` | Add field to a fulltext index.                             |
| `@db.index.unique 'idxName'`   | Add field to a unique index.                               |
| `@db.default.increment`        | Auto-increment (primary key).                              |
| `@db.default.now`              | Default to "now" timestamp.                                |
| `@db.default.uuid`             | Default to a UUID.                                         |
| `@db.rel.FK`                   | Foreign-key field (typed as `OtherTable.id`).              |
| `@db.column.precision p, s`    | Decimal precision/scale.                                   |
| `@db.amount.currency 'USD'`    | Treat as currency.                                         |
| `@db.http.path '/api/things'`  | The REST path `moost-db` exposes this table at.            |

Full reference: [db.atscript.dev](https://db.atscript.dev/api/tables).

### `@wf.*` — workflow forms

The `@atscript/moost-wf/plugin` registers this namespace. You'll use it when building HTTP workflows (see the [Workflows guide](/workflows/)).

| Key                     | Purpose                                                            |
| ----------------------- | ------------------------------------------------------------------ |
| `@wf.context.pass`      | Pass this field's value to the next step via the workflow context. |
| `@wf.action.withData`   | The action submits with form data.                                 |
| `@wf.store.fromContext` | Hydrate this field from the workflow's persisted store.            |

Full reference: [Workflows: Server authoring](/workflows/server-authoring).

## A complete annotated example

A realistic `.as` file uses all five families on one interface. This `Product.as` example is both the database table and the form/table schema:

```atscript
@db.table 'products'
@db.table.preferredId.uniqueIndex 'products_sku_idx'
@meta.label 'Product'
export interface ProductsTable {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Name'
    @meta.required 'Name is required'
    @db.index.fulltext 'products_search'
    @ui.form.grid.colSpan 'half'
    @expect.maxLength 120, 'Keep it under 120 characters'
    name: string

    @meta.label 'SKU'
    @meta.required 'SKU is required'
    @db.index.unique 'products_sku_idx'
    @ui.form.grid.colSpan 'half'
    @expect.pattern '/^[A-Z0-9-]+$/', 'Uppercase letters, digits and dashes only'
    sku: string

    @meta.label 'Description'
    @ui.type 'textarea'
    @db.index.fulltext 'products_search'
    description?: string

    @meta.label 'Price'
    @db.amount.currency 'USD'
    @db.column.precision 10, 2
    @db.index.plain 'products_price_idx'
    @ui.form.grid.colSpan 'half'
    @expect.min 0, 'Price must be non-negative'
    price: decimal

    @meta.label 'Tags'
    @ui.form.label.singular 'tag'
    tags: string[]

    @meta.label 'Created'
    @db.default.now
    createdAt: number.timestamp
}
```

One file gives you:

- A SQLite/Postgres/MySQL `products` table with the right indexes (via [atscript-db](https://db.atscript.dev)).
- A REST endpoint at `/api/products` (via [`moost-db`](https://db.atscript.dev/http/)).
- A two-column form in atscript-ui (`name` and `sku` side-by-side via `@ui.form.grid.colSpan 'half'`, `description` full-width as a textarea).
- Validation that runs identically on the client (via `@atscript/ui`'s `Validator`) and on the server (via [`@atscript/moost-validator`](https://atscript.dev)).
- A table with sortable columns, automatic filter inputs (text on `name`/`sku`/`description`, range on `price`, multi-select chips on `tags`), and a default created-at column.

That's the payoff of the model: annotate once, render everywhere.

::: tip Run-able schemas
The dedicated guides below cover the same shapes in focused examples:

- [Forms](/forms/) — focused one-page form examples (arrays, nested, unions, refs, dynamic, validation).
- [Tables](/tables/) — filters, sorters, custom cells, presets, value-help.
  :::

## Codegen quick reference

Two ways to compile `.as` files:

```bash
# CLI — emits .as.d.ts (and optionally .as.js) next to each .as file.
# Run on CI, before publishing a package, or whenever IDE types drift.
npx asc
```

```ts
// vite — compiles on the fly at dev time, regenerates on HMR.
import atscript from "unplugin-atscript/vite";

export default defineConfig({
  plugins: [atscript()],
});
```

In a typical dev workflow you only run `asc` manually when types stop resolving in the IDE (after pulling teammates' changes, for example) or when building for production CI. The plugin handles the rest.

Full atscript syntax + tooling reference: [atscript.dev](https://atscript.dev).

## What's next

- [Ecosystem map](./ecosystem) — how `.as` ties the three sibling sites (atscript / atscript-db / atscript-ui) together.
- [Forms: Annotations](/forms/annotations) — every `@ui.form.*` key.
- [Tables: Annotations](/tables/annotations) — every `@ui.table.*` key.
- [Workflows: Server authoring](/workflows/server-authoring) — `@wf.*` keys in context.


---
URL: "ui.atscript.dev/styling"
LLMS_URL: "ui.atscript.dev/styling.md"
---

# Styling

`@atscript/ui-styles` is the styling layer that powers every `@atscript/vue-*` package. It ships a UnoCSS preset, a Vite component resolver, a tree of `as-*` shortcut classes, baked icons, and pre-built CSS bundles. Forms, tables, and workflow forms all emit `as-*` class names and inherit the same theme from a single source of truth.

## How styling is layered

atscript-ui ships generic on purpose. The UI components emit semantic `as-*` class names like `as-form`, `as-cell-decimal`, `as-filter-dialog` — never colors, pixel values, or design-system specifics. The translation from `as-*` to actual CSS rules happens inside `@atscript/ui-styles`, which composes those classes from the `vunor` shortcuts engine it depends on internally (`scope-*`, `layer-*`, `surface-*`, `c8-*`, `i8-*`, spacing tokens, fingertip heights, typography).

Because `as-*` shortcuts resolve through vunor's primitives, tuning vunor's palette/tokens at preset registration time restyles every atscript-ui component without touching component source. From there you can layer your own `as-*` shortcuts on top of `allShortcuts` to extend or repaint individual concepts.

The supported customization path: **components emit `as-*` class names; tune the vunor primitives or merge your own `as-*` shortcuts on top of `allShortcuts` and your brand color set in `asPresetVunor({ palette })` propagates into every form input, table cell, filter pill, and dialog.** You can also write app-level CSS that targets `as-*` selectors directly — see the trade-offs below.

## Two ways to use it

There are two integration paths. Pick one based on whether you already use UnoCSS.

### a) UnoCSS preset (recommended)

Install `unocss` and `@atscript/ui-styles`, then call `asPresetVunor()` in `uno.config.ts`. You get:

- Full theme control (palette, radius, fingertip heights).
- A class extractor that walks your sources and safelists exactly what each form / table actually renders.
- Dynamic icon overrides via `iconOverrides`.
- The freedom to merge your own `as-*` shortcuts on top of `allShortcuts`.

Walk through it on the [Installation](/styling/installation) page.

### b) Pre-built CSS bundles (no build step)

If your app doesn't use UnoCSS, import a pre-baked stylesheet at your entry:

```ts
import "@atscript/ui-styles/css/all";
```

The bundle ships every shortcut for every package, baked against the default vunor theme. No build-time customization is possible — you trade theming for zero setup. See [Pre-built CSS](/styling/prebuilt-css) for details and per-package bundles.

## The `as-*` shortcut model

Components in `vue-form`, `vue-table`, and `vue-wf` render only `as-*` class names on their elements. The rules behind those classes live in `@atscript/ui-styles/src/shortcuts/{form,table,wf,common}/` and are composed from vunor primitives.

You have two ways to customize the look:

1. **Tune through vunor / merge `as-*` shortcuts** (recommended). Brand changes happen once, at the vunor layer, and the rest of the UI follows. Trade-off: you learn the shortcut tree.
2. **Write app-level CSS that targets `as-*` selectors directly.** Works fine, especially for one-off tweaks. Trade-off: hand-rolled overrides need to keep up if the shortcut body later gains a `hover:` or `focus-within:` variant, and the rule won't follow palette changes.

The first-class customization vectors are:

- **Theme:** `asPresetVunor({ baseRadius, palette })` — see [Theme & Palette](/styling/theme).
- **Icons:** `asPresetVunor({ iconOverrides })` — see [Icons](/styling/icons).
- **New shortcuts (additive):** `mergeVunorShortcuts([allShortcuts, defineShortcuts({ 'as-foo-extra': '...' })])` — see [The as-\* Shortcut System](/styling/shortcuts).
- **Removing default-component styles:** `asPresetVunor({ excludeComponents })` when you swap a default for your own component.

## Next steps

- [Installation](/styling/installation) — wire UnoCSS, the resolver, and CSS into a Vite app.
- [Theme & Palette](/styling/theme) — set brand colors, radius, and dark mode.
- [Icons](/styling/icons) — swap baked icons, add brand glyphs.
- [The as-\* Shortcut System](/styling/shortcuts) — extend or compose shortcuts.
- [Pre-built CSS](/styling/prebuilt-css) — no-UnoCSS integration.
- [Bundle Optimization](/guide/bundle-optimization) — how the extractor safelists only what you use, companion expansion, `excludeComponents`, per-branch shortcut mounting.


---
URL: "ui.atscript.dev/styling/icons"
LLMS_URL: "ui.atscript.dev/styling/icons.md"
---

# Icons

`@atscript/ui-styles` ships a sealed set of semantic icons under the `i-as-*` namespace. Forms, tables, and workflow forms reference these by alias (`i-as-search`, `i-as-loading`, `i-as-close`) — never by Iconify ID — so a single `iconOverrides` map rebrands every glyph across the UI.

## What ships out of the box

The default set covers everything the built-in components render: dialog close buttons, table filter/sort/columns triggers, refresh, value-help affixes, in-flight overlays, optional-field toggles, chevrons, drag handles, trash, plus / minus, pin, star, theme toggle, validation warning.

The SVGs are baked at our publish time — no Iconify API calls happen during your build, no `.icons/` folder appears in your project, no extra dependency. The full alias map is also re-exported as a read-only constant:

```typescript
import { bakedIcons } from "@atscript/ui-styles";

console.log(Object.keys(bakedIcons).sort());
// ['arrow-down', 'arrow-up', 'check', 'check-square', 'chevron-down', ...]
```

You typically don't need to read `bakedIcons` — it's there for tooling and debugging.

## Overriding an icon

Pass `iconOverrides` to `asPresetVunor()`. Keys are the alias names (`search`, `close`, `loading`, …); values are full `<svg>...</svg>` strings.

```typescript
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  presets: asPresetVunor({
    iconOverrides: {
      search:
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M21 21l-4.35-4.35M11 19a8 8 0 1 1 0-16 8 8 0 0 1 0 16z" stroke="currentColor" stroke-width="2"/></svg>',
      loading:
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="9" stroke="currentColor" stroke-width="2" fill="none"/></svg>',
    },
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

Two recommendations for override SVGs if you want them to behave like the built-in icons:

1. **Use `currentColor` for fill / stroke.** Icons inherit color from the surrounding text via vunor's scope / layer system. A hardcoded `fill="#000"` keeps that color in dark mode and inside `scope-error` rather than tinting with context — fine if that's the look you want.
2. **Set `viewBox` and let `width` / `height` default to `1em`.** The `i-as-*` class system sizes via `em`, so SVGs without pinned pixel dimensions scale with surrounding text.

Unknown keys are ignored, so `iconOverrides: { brandSomething: ... }` won't break anything — it just won't paint anywhere.

## Adding brand-new icons

`iconOverrides` only replaces existing aliases. For new icons — your brand glyphs, an entire Iconify collection, etc. — compose your own `presetIcons` alongside ours under a different collection prefix:

```typescript
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";
import presetIcons from "@unocss/preset-icons";

export default defineConfig({
  presets: [
    ...asPresetVunor(),
    presetIcons({
      collections: {
        // Bring in an official Iconify package (pnpm add -D @iconify-json/lucide)
        lucide: () => import("@iconify-json/lucide/icons.json").then((i) => i.default),
        // Or a custom inline set
        brand: {
          logo: '<svg xmlns="..." viewBox="0 0 100 100">...</svg>',
        },
      },
    }),
  ],
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

`i-lucide-search` and `i-brand-logo` now resolve alongside `i-as-search` — different prefixes, zero coordination needed. See the [UnoCSS `presetIcons` docs](https://unocss.dev/presets/icons) for the full API.

## Em-based sizing

Every `as-*` shortcut that renders an icon sizes it with `em`, not pixels:

```typescript
"as-overlay-icon": "i-as-loading text-[3em]",
"as-cell-json-trigger-glyph": "font-700",
"as-field-remove-btn-icon": "i-as-close text-[1em]",
```

Icons scale with the surrounding text. Inside a `text-callout` row, `text-[1em]` is `0.85em`; inside a `text-body-l` row, `text-[1em]` is `1.15em`. If you add your own `as-*` shortcut that renders an icon and want it to follow the same rhythm, use `text-[1em]` for inline glyphs, `text-[1.25em]` for slightly larger control glyphs (close buttons), `text-[3em]` for overlay spinners. Pinning a fixed `w-[16px] h-[16px]` is also fine — it just won't scale with the surrounding typography.

## Next steps

- [The as-\* Shortcut System](/styling/shortcuts) — how shortcut bodies reference icons via `i-as-*`.
- [Theme & Palette](/styling/theme) — palette tuning that feeds icon colors via `currentColor`.


---
URL: "ui.atscript.dev/styling/installation"
LLMS_URL: "ui.atscript.dev/styling/installation.md"
---

# Installation

This page wires `@atscript/ui-styles` into a fresh Vite + Vue 3 app: the UnoCSS preset, the component auto-resolver, and the CSS hookup.

## Install dependencies

```bash
pnpm add @atscript/ui-styles vunor unocss unplugin-vue-components
```

You also need the `@atscript/vue-*` packages whose components you actually use:

```bash
pnpm add @atscript/vue-form @atscript/vue-table @atscript/vue-wf
```

`vunor` is a peer dependency of `@atscript/ui-styles`. Installing it explicitly keeps your lockfile aligned with the version atscript-ui was tested against.

## `vite.config.ts`

Register UnoCSS and `unplugin-vue-components` with `AsResolver()` from `@atscript/ui-styles/vite`.

```typescript
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import UnoCSS from "unocss/vite";
import Components from "unplugin-vue-components/vite";
import { AsResolver } from "@atscript/ui-styles/vite";

export default defineConfig({
  plugins: [
    vue(),
    UnoCSS(),
    Components({
      resolvers: [AsResolver()],
    }),
  ],
});
```

`AsResolver()` auto-imports Tier-1 components — the ones you tag directly in templates: `<AsForm>`, `<AsField>`, `<AsIterator>`, `<AsTable>`, `<AsTableRoot>`, `<AsWindowTable>`, `<AsFilters>`, `<AsPresetPicker>`, `<AsTableActions>`, `<AsWfForm>`. Tier-2 default implementations (`AsInput`, `AsSelect`, `AsFilterDialog`, …) are public and importable but **not** auto-resolved — you import them explicitly when you compose custom `:types` / `:components` maps. Composables (`useTable`, `useFormState`, …) always require an explicit `import`.

## `uno.config.ts`

Add `asPresetVunor()` to the preset list. Merge `allShortcuts` (the full atscript-ui shortcut tree) through `vunorShortcuts()` so vunor can expand its primitives inside our shortcut bodies.

```typescript
import { defineConfig } from "unocss";
import {
  allShortcuts,
  asPresetVunor,
  defineShortcuts,
  mergeVunorShortcuts,
} from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  content: {
    filesystem: ["src/**/*.{vue,ts,tsx}"],
  },
  presets: asPresetVunor({
    baseRadius: "6px",
    // Brand colors, fingertip ladder, typography, animation, etc. all sit
    // flat at this level — `asPresetVunor` accepts the full presetVunor()
    // theme. See [Theme & Palette](/styling/theme) for the full option list.
    // palette: { colors: { primary: '#a855f7' } },
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

A few notes:

- **`asPresetVunor()` already returns `Preset[]`** — pass it directly. Don't wrap it in another array, or UnoCSS will flatten silently and lose the extractor.
- **`vunorShortcuts(allShortcuts)`** — the wrapper that compiles vunor shortcut objects into UnoCSS-compatible `[selector, body]` tuples. Required when you pass our shortcuts to UnoCSS's `shortcuts` option.
- **`content.filesystem`** scans your own source files. You don't need to add `node_modules/@atscript/**` — the preset registers a custom extractor that walks `@atscript/vue-*` imports / `<AsX>` tags / helper calls (`createDefaultTypes()`, `createDefaultControls()`, `createDefaultCellTypes()`) in your code and pulls in pre-computed safelists.

### Adding your own shortcuts

`mergeVunorShortcuts` is associative — feel free to layer in app-specific shortcuts on top of the library's:

```typescript
const appShortcuts = defineShortcuts({
  "page-shell": "flex flex-col min-h-screen layer-0",
  "page-header": "flex items-center gap-$m px-$l py-$s border-b-1",
});

export default defineConfig({
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(mergeVunorShortcuts([allShortcuts, appShortcuts]))],
});
```

### SSR

For SSR setups, UnoCSS still works the same way, but make sure `unocss/vite` runs in both client and server passes so the safelist matches. You may also want to add an extra `presetIcons()` for icons referenced from `.as` schemas (annotation values that emit `i-as-*` class names statically). You only need that escape hatch when `@ui.form.prefix.icon` or similar paints a class name our extractor can't see in `.vue` / `.ts` sources:

```typescript
safelist: ["i-as-star-filled", "i-as-search"];
```

## CSS hookup

Import UnoCSS's virtual stylesheet exactly once, at your app entry:

```typescript
// src/main.ts
import "virtual:uno.css";
import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");
```

That's all the CSS plumbing needed for the UnoCSS path. UnoCSS generates utility CSS on-demand, scoped to the safelist (your source + atscript-ui's component classes).

Typography is intentionally **not** baked into `@atscript/ui-styles` — real consumers bring their own font stack.

## Verify

Mount any primary component and inspect the network panel.

```vue
<script setup lang="ts">
import { User } from "./types/user.as";
import { ref } from "vue";

const data = ref<User>({ name: "", email: "" });
</script>

<template>
  <AsForm :type="User" v-model="data" />
</template>
```

In your browser's network panel, look for the UnoCSS-generated stylesheet (`/@unocss-devtools/...` in dev, hashed `.css` in build). You should see `as-form`, `as-field-label`, `as-default-field`, and the underlying `scope-*` / `layer-*` rules. If you don't see them, the extractor isn't reaching your source — double-check `content.filesystem` covers your files and that `<AsForm>` is actually being rendered.

## Next steps

- [Theme & Palette](/styling/theme) — set your brand color and radius.
- [Icons](/styling/icons) — swap baked icons or add brand glyphs.
- [The as-\* Shortcut System](/styling/shortcuts) — how the shortcut tree is organized and how to extend it.


---
URL: "ui.atscript.dev/styling/prebuilt-css"
LLMS_URL: "ui.atscript.dev/styling/prebuilt-css.md"
---

# Pre-built CSS

For apps that don't run UnoCSS, `@atscript/ui-styles` ships pre-baked stylesheets. Drop one `<link>` (or `import`) and `<AsForm>` / `<AsTable>` / `<AsWfForm>` paint correctly. No build step on your side, no UnoCSS in your dep tree.

## When to use it

- You're embedding atscript-ui into an existing app that already uses Tailwind / Bootstrap / handwritten CSS / another design system, and you don't want UnoCSS fighting with it.
- You're shipping a quick prototype or admin tool where you don't care about brand-color customization.
- You're not using a bundler at all (CDN-style integration).

If none of the above apply, go with the [UnoCSS path](/styling/installation) — it gives you theming, dynamic icon overrides, and an automatic safelist.

## Trade-offs

The pre-built bundles are sealed at our publish time. You give up:

- **Theming.** `baseRadius`, palette overrides, `iconOverrides`, and `excludeComponents` all happen at preset registration time. The pre-built CSS is generated against the library's default theme — your brand color can't propagate.
- **Auto-safelist.** The bundle ships every class for every default component, whether you use it or not. Bundle is larger by design.
- **Per-component splitting.** You can split by package (`form` / `table` / `wf` / `aooth`) but not by component.

In return: zero build-time integration. You can paste the stylesheet `<link>` into a static HTML page and it just works.

## Subpath imports

The package exposes five CSS subpaths:

| Subpath                         | Contents                                                                    |
| ------------------------------- | --------------------------------------------------------------------------- |
| `@atscript/ui-styles/css/all`   | Every shortcut from every package — pick this if you use more than one.     |
| `@atscript/ui-styles/css/form`  | `commonShortcuts` + `formShortcuts` only — for `@atscript/vue-form` apps.   |
| `@atscript/ui-styles/css/table` | `commonShortcuts` + `tableShortcuts` only — for `@atscript/vue-table` apps. |
| `@atscript/ui-styles/css/wf`    | `commonShortcuts` + `wfShortcuts` only — for `@atscript/vue-wf` apps.       |
| `@atscript/ui-styles/css/aooth` | `commonShortcuts` + `aoothShortcuts` only — for `@atscript/vue-aooth` apps. |

The per-package bundles are **independently complete** — each one ships its own copy of `commonShortcuts` and vunor primitives so it stands alone. That means they overlap on shared rules: **don't combine `form.css` + `table.css`** in the same app, use `all.css` instead.

## Vite / webpack / Rollup

Import once at your app entry:

```typescript
// src/main.ts
import "@atscript/ui-styles/css/all";

import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");
```

For finer-grained loading, e.g. a forms-only product:

```typescript
import "@atscript/ui-styles/css/form";
```

## HTML `<link>`

For non-bundled setups, copy the file from `node_modules` into your `public/` dir (or serve it from a CDN) and link it directly:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="stylesheet" href="/atscript-ui.css" />
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>
```

A minimal Vue mount looks identical to the UnoCSS path — the only thing that changes is the CSS source:

```typescript
// main.ts
import { createApp } from "vue";
import { AsForm } from "@atscript/vue-form";
import { User } from "./types/user.as";

const app = createApp({
  components: { AsForm },
  data: () => ({ User, model: { name: "", email: "" } }),
  template: `<AsForm :type="User" v-model="model" />`,
});

app.mount("#app");
```

## Brand-color overrides without UnoCSS

The vunor shortcuts engine atscript-ui uses internally emits CSS custom properties (the `--current-*`, `--surface-*`, `--scope-*` ladder) into the cascade. Even with the pre-built CSS, you can shift the brand color by overriding those custom properties on `:root` or on a scoped ancestor:

```css
:root {
  /* Adjust primary scope */
  --vunor-primary-h: 270;
  --vunor-primary-s: 80%;
  --vunor-primary-l: 55%;
}
```

This works at runtime — flip a class on `<html>` to pivot the whole palette without rebuilding CSS.

This trick lets you keep the pre-built workflow while still shipping a few brand tones. For anything deeper than primary-color tuning, switch to the UnoCSS path.

## Dark mode

The pre-built CSS includes the dark-mode rules for every shortcut. Add a `.dark` class to `<html>` (or any ancestor of the components) and the tree switches:

```html
<html class="dark">
  ...
</html>
```

Wire the toggle however your app does state. The shortcut tree already includes the `dark:` variants — no extra config required.

## Bundle size

Rough numbers for the published bundles (post-gzip, varies by version):

- `css/all` — ~32 KB.
- `css/form` — ~22 KB.
- `css/table` — ~24 KB.
- `css/wf` — ~16 KB.
- `css/aooth` — ~12 KB.

Compare this against an equivalent UnoCSS-generated bundle, which typically lands around 12–18 KB because the extractor strips unused classes. The pre-built path costs you bundle size for the convenience of skipping the build.

## Next steps

- [Installation](/styling/installation) — the UnoCSS path, recommended when you want theming.
- [Theme & Palette](/styling/theme) — what theming buys you over the pre-built bundle.


---
URL: "ui.atscript.dev/styling/shortcuts"
LLMS_URL: "ui.atscript.dev/styling/shortcuts.md"
---

# The as-\* Shortcut System

Every visual rule in `@atscript/vue-form`, `@atscript/vue-table`, and `@atscript/vue-wf` lives in a single shortcut tree under [`packages/ui-styles/src/shortcuts/`](https://github.com/moostjs/atscript-ui/tree/main/packages/ui-styles/src/shortcuts). Components emit `as-*` class names; the shortcuts turn those into vunor-primitive compositions. Once you know the tree, theming and per-state tweaks happen in one place instead of scattered across your stylesheet.

## Naming convention

Two rules cover the entire tree:

1. **`as-<concept>`** is the base shortcut. Single source of truth for that concept's visual signature.
2. **`as-<case>-<concept>`** is a case-specific variant that extends the base.

For example, descriptive helper text:

```typescript
// shortcuts/common/index.ts
"as-description": "text-callout text-current/60 m-0",
```

```typescript
// shortcuts/form/as-field.ts
"as-field-description": "as-description -mt-[0.2em]",
```

```typescript
// shortcuts/form/as-form.ts
"as-form-description": "as-description",
```

Consumers can repaint every description in the UI by overriding `as-description` alone — and every variant inherits the change. Same idea for `as-overlay` / `as-form-overlay` / `as-table-query-overlay`, `as-close-btn` / `as-dialog-close`, `as-cell-*` row in tables.

## Shortcut groups

Shortcuts are split into five logical groups. They merge into `allShortcuts` (what `asPresetVunor` registers by default), but you can mount them individually if you only use one package.

| Export            | What it covers                                                                                                                                                                                                                                                                                 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commonShortcuts` | Cross-package primitives: `as-description`, `as-overlay`, `as-kbd`, `as-close-btn`, `as-dialog-close`.                                                                                                                                                                                         |
| `formShortcuts`   | Form chrome: `as-form*`, `as-field*`, `as-default-field`, `as-checkbox-radio*`, `as-array*`, `as-object*`, `as-collapsible*`, `as-decimal-number*`, `as-dropdown*`, `as-ref*`, `as-action*`, `as-no-data*`, `as-form-grid*`.                                                                   |
| `tableShortcuts`  | Table chrome: `as-table*`, `as-cell-*`, `as-column-menu*`, `as-filter-dialog*`, `as-config-dialog*`, `as-filter-field*`, `as-fpill*`, `as-orderable-list*`, `as-preset-picker*`, `as-window-table*`, `as-window-skeleton*`, `as-row-actions*`, `as-sorter*`, `as-page*`, `as-confirm-dialog*`. |
| `wfShortcuts`     | Workflow form chrome: `as-wf-form*`.                                                                                                                                                                                                                                                           |
| `aoothShortcuts`  | Aooth auth-flow field chrome (`@atscript/vue-aooth`): `as-consent-array*`, `as-copy*`, `as-password-rules*`, `as-qr-code*`, `as-sso-provider*`.                                                                                                                                                |

Import them directly when you only need one:

```typescript
import { defineConfig } from "unocss";
import { commonShortcuts, formShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { mergeVunorShortcuts, vunorShortcuts } from "vunor/theme";

export default defineConfig({
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(mergeVunorShortcuts([commonShortcuts, formShortcuts]))],
});
```

Mostly you'll just use `allShortcuts`.

## Extending the tree

`mergeVunorShortcuts` accepts an array of shortcut objects and folds them into a single merged map — later entries can extend earlier ones with hover / focus / nested selectors. The standard recipe:

```typescript
import {
  allShortcuts,
  asPresetVunor,
  defineShortcuts,
  mergeVunorShortcuts,
} from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

const appShortcuts = defineShortcuts({
  // New concept — sibling of the existing `as-*` tree
  "as-foo-extra": "scope-primary border-1 layer-0 px-$m py-$s rounded-r2 text-body",

  // Existing concept — paint over a state without forking the body
  "as-form": {
    "[&_.as-field-label]:": "uppercase tracking-wide",
  },
});

export default defineConfig({
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(mergeVunorShortcuts([allShortcuts, appShortcuts]))],
});
```

Two patterns and when to reach for each:

- **Add a sibling shortcut** when introducing a new piece of UI. Pick a name that fits the `as-<case>-<concept>` convention if it extends an existing concept, or `as-<new-concept>` if it stands alone.
- **Extend an existing shortcut's variant map** when painting over a state (`hover:`, `focus-within:`, `[&_child]:`, `[&.error]:`). Copying the whole body and tweaking it works, but it fragments the source of truth — future palette / dark-mode updates to the original won't reach your fork.

`mergeVunorShortcuts` is associative, so `[allShortcuts, appShortcuts]` and `[appShortcuts, allShortcuts]` produce different results. Order matters: **put your overrides last** so they win.

## Overriding a built-in `as-*` shortcut

Extending adds a _new_ class. Overriding repaints an _existing_ one — change the form title's weight, drop the required-field asterisk, retint a section heading — without forking the whole shortcut body. This is the most common customization once the brand palette is set.

### Wiring

Same merged-shortcuts recipe as extending. The override object goes **last** in the `mergeVunorShortcuts` array so it wins:

```ts
import {
  allShortcuts,
  asPresetVunor,
  defineShortcuts,
  mergeVunorShortcuts,
} from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";
import { defineConfig } from "unocss";

const shortcutOverrides = defineShortcuts({
  // Append a weight onto vunor's baked `btn`.
  btn: { "": "fw-400" },
  // `as-collapsible-title` bakes `text-body-l font-600`; remap to your h3 scale.
  // `!` is needed because UnoCSS emits `font-<n>` in numeric order, so a plain
  // `font-100` would lose to the baked `font-600`.
  "as-collapsible-title": { "": "text-h3 !font-100" },
  // Form root title bakes `text-[1.54em] font-700`; map to your h2, force weight 100.
  "as-form-title": { "": "text-h2 !font-100" },
  // Remove the required-field red asterisk. `as-default-field` renders it via
  // `[&.required .as-field-label]::after { content: " *" }`; blank the content on
  // that exact variant. `!` beats the baked content declaration (merge = append).
  "as-default-field": { "[&.required_.as-field-label]:after:": "!content-['']" },
});

export default defineConfig({
  presets: asPresetVunor(),
  shortcuts: [vunorShortcuts(mergeVunorShortcuts([allShortcuts, shortcutOverrides]))],
});
```

The import paths are the same as everywhere else on this page: `allShortcuts`, `asPresetVunor`, `defineShortcuts`, and `mergeVunorShortcuts` come from `@atscript/ui-styles`; `vunorShortcuts` comes from `vunor/theme` (ui-styles re-exports the other three vunor helpers but **not** `vunorShortcuts`). `defineShortcuts` is an identity/typing helper — it returns its input unchanged and only gives your editor the `TVunorShortcut` type.

### The key mechanic — merge is APPEND, not replace

When `allShortcuts` (the base) and your override both define the same `as-*` name, `mergeVunorShortcuts` does **not** swap the base body for yours. It flattens each shortcut to a utility string and **concatenates** them — `base + " " + override` — per variant key. Two consequences you must internalize:

1. **You only write the one variant key you want to change.** The shortcut's other keys stay in the base string untouched — no need to copy the whole body. In the example above, `as-form-title` keeps its baked `tracking-[-0.02em]`; you only restated `text-*`/`font-*`.
2. **Both the baked utility AND your override land on the same element**, so your override must _win the CSS cascade_. Specificity is equal (both are plain utilities), so reach for `!` (important) on the property you're replacing.

#### Font-weight gotcha

UnoCSS emits `font-<n>` rules in **numeric order**, not source order. A plain `font-100` appended after a baked `font-600` still loses — `font-600` sorts later in the stylesheet. Force it with `!font-100`.

#### Blanking a pseudo-element

To clear `::before` / `::after` content (e.g. the required-field asterisk), set the content to an _empty string literal_ — `content-['']` — not an empty value string `""`. An empty value produces a selector with no utility attached, which UnoCSS silently drops (no-op), leaving the baked content in place. Pair it with `!` so it beats the base `content-["_*"]` declaration.

### When to override a shortcut vs. tune the theme vs. swap a component

Three levers, smallest first:

| Goal                                                           | Lever                                               | Where                                         |
| -------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------- |
| Brand colors, radius, spacing, fingertip ladder                | `asPresetVunor({ palette, baseRadius, fingertip })` | [Theme & Palette](/styling/theme)             |
| Restyle a specific `as-*` hook (weight, asterisk, one variant) | Shortcut override (this section)                    | here                                          |
| Replace a field renderer entirely (custom widget)              | `:types` / `:components` prop map                   | [Forms — Customization](/forms/customization) |

Theme tuning is the broadest brush — it repaints everything at once and needs no shortcut knowledge. Override a shortcut when the palette is right but one visual rule isn't. Swap a component when no amount of CSS gets you there and you need different markup.

### DOs and DON'Ts

- **DO** put `!` (important) on the property you're replacing — merge appends, so a plain utility ties on specificity and may lose. **DON'T** expect `font-100` to beat a baked `font-600`.
- **DO** blank pseudo-content with `content-['']`. **DON'T** use `""` (an empty value string) — it compiles to nothing and the baked content survives.
- **DO** override just the one variant key you're changing. **DON'T** re-declare the whole shortcut body — you'd fork it and stop inheriting future palette / dark-mode fixes to the base.

### Overridable label / field hooks

The handful you'll reach for most when restyling form chrome:

| Shortcut               | Bakes                                | Override to…                                       |
| ---------------------- | ------------------------------------ | -------------------------------------------------- |
| `as-form-title`        | `text-[1.54em] font-700`             | remap the form header to your type scale           |
| `as-collapsible-title` | `text-body-l font-600`               | retint section headings                            |
| `as-default-field`     | layout + label/input/error variants  | repaint the required asterisk, label, or any input |
| `as-field-label`       | (via `as-default-field` `[&_label]`) | label weight / casing                              |
| `as-field-description` | `as-description` + offset            | description text styling                           |

`as-field-label`, `as-field-description`, `as-error-slot`, and `as-field-header-row` are reachable the same way. For the complete catalog of every `as-*` shortcut name, see the [`@atscript/ui-styles` API reference](/api/ui-styles#shortcuts) and the [source shortcut tree](https://github.com/moostjs/atscript-ui/tree/main/packages/ui-styles/src/shortcuts).

## Composing with vunor primitives

When you add a new `as-*` shortcut and want it to inherit palette, dark mode, and scope tinting, compose its body from vunor primitives instead of pixel literals or hex colors. The library's own shortcut tree follows the same approach — that's what lets a single `palette.colors.primary` change in `presetVunor()` repaint everything downstream. If you'd rather hardcode values in a particular shortcut, that's fine too; just know that shortcut won't follow palette changes.

| Intent                          | vunor primitive                                                     | Hardcoded equivalent                                   |
| ------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------ |
| Gap / padding / margin          | spacing tokens `$xxs..$xxl`                                         | `gap-[8px]`, `px-[12px]`                               |
| Control heights / touch targets | `h-fingertip-xs/s/m/l/xl`                                           | `h-[32px]`                                             |
| Body / secondary / title text   | `text-body`, `text-callout`, `text-body-l`                          | `text-[length:13px]`                                   |
| Icon-glyph sizing               | em-based `text-[1em]`, `text-[1.25em]`                              | `w-[16px] h-[16px]`                                    |
| Elevated surfaces               | `shadow-popup`, `popup-card`                                        | custom box-shadow                                      |
| Borders (default)               | `border-1` alone — color comes from active surface/layer            | `border-grey-200 dark:border-grey-800`                 |
| Focus rings                     | `current-outline-hl outline i8-apply-outline`                       | `[box-shadow:0_0_0_3px_...]`                           |
| Button / clickable surfaces     | `c8-filled / c8-flat / c8-outlined / c8-light / c8-chrome`          | custom hover/active rules                              |
| Inputs (bordered)               | `border-1 layer-0 current-outline-hl` + `i8-apply-outline` on focus | `i8-input i8-apply-border` (leaks scope color as fill) |

The benefit of routing through these primitives is that a single `palette.colors.primary` change in `presetVunor()` repaints everything downstream. Pick whichever side of the table fits the level of theme-awareness you want for that particular shortcut.

## Example shortcut bodies

A few real entries from the source so the patterns are concrete.

### Form error banner

```typescript
// shortcuts/form/as-form.ts
"as-form-error":
  "scope-error surface-50 border-1 rounded-r2 px-$m py-$s mb-$s text-callout text-current-hl flex items-center gap-$s",
```

- `scope-error` activates the error palette branch — every `current-*` / `surface-*` / `border-*` resolves through error scope.
- `surface-50` paints the banner background in a tinted scope variant.
- `border-1` alone — vunor pulls the border color from the active surface.
- `text-current-hl` uses the highlighted variant of the active text color (error red).

### Table number cell

```typescript
// shortcuts/table/as-cell.ts
"as-cell-decimal": "text-right tabular-nums font-mono",
```

A minimal shortcut. Right-alignment plus tabular-numerals so numbers in a column align by decimal. No color, no spacing — those come from the row's parent `as-window-table` chrome.

### Close button with state map

```typescript
// shortcuts/common/index.ts
"as-close-btn": {
  "":
    "inline-grid place-items-center size-fingertip-s p-0 border-0 " +
    "bg-transparent text-current/80 cursor-pointer leading-none rounded-base " +
    "flex-shrink-0 transition-colors duration-120 text-[1.25em]",
  "hover:": "layer-2 text-current",
},
"as-dialog-close": "as-close-btn ml-auto",
```

The object-form syntax lets a shortcut declare its base body under `""` and then add variant bodies (`"hover:"`, `"focus-visible:"`, `"[&_.icon]:"`). Consumers paint over a single state without forking the body.

### Progress button — `c8-progress`

```typescript
// shortcuts/common/c8-progress.ts
"c8-progress": "relative overflow-hidden",
"c8-progress-fill":
  "absolute inset-y-0 left-0 w-0 bg-black/20 animate-[progress-fill_var(--progress-duration,4s)_linear_forwards]",
"c8-progress-label": "relative",
```

`c8-progress` turns any `c8-*` clickable surface into a self-filling
progress button — the kind of "I'll fire when the bar reaches the
end, but click me to fire now" control used by auto-redirect skip
buttons, hold-to-confirm CTAs, and timed confirmations. The 3-class
API:

```html
<button
  class="c8-filled scope-primary c8-progress h-fingertip-m px-$m"
  :style="{ '--progress-duration': '4000ms' }"
>
  <span class="c8-progress-fill" />
  <span class="c8-progress-label">Confirm</span>
</button>
```

- `c8-progress` composes on top of any `c8-*` base (`c8-filled`,
  `c8-flat`, `c8-light`, …). It adds `relative overflow-hidden` so
  the fill clips to the button's rounded corners.
- `c8-progress-fill` is absolutely positioned out of flow and
  animates `width 0% → 100%` over `--progress-duration` (set as an
  inline style on the host). `bg-black/20` is a uniform darken
  overlay that works on any underlying surface in both light and
  dark themes.
- `c8-progress-label` is in-flow `relative` — it sits above the
  absolute fill via source order. Required (not optional): without
  an in-flow child the button collapses to its padding box.

The animation is driven by `@keyframes progress-fill`, registered
once as a UnoCSS preflight by `asPresetVunor`. Consumers don't have
to register anything beyond installing the preset.

### Default form field, deep selectors

```typescript
// shortcuts/form/as-field.ts
"as-default-field": {
  "": "as-grid-item flex flex-col gap-$xs relative",
  "[&_label]:": "font-600",
  "[&.required_.as-field-label]:after:":
    'content-["_*"] scope-error text-current-hl font-700 ml-[0.1em]',
  "[&_:is(input:not([type=checkbox]):not([type=radio]),select,textarea)]:": inputBase,
  "[&_:is(input:not([type=checkbox]):not([type=radio]),select,textarea):focus]:":
    "current-border-hl outline i8-apply-outline",
  "[&.error_:is(input:not([type=checkbox]):not([type=radio]),select,textarea)]:":
    "scope-error current-border-hl border-current",
},
```

This is what makes form fields styleable through one shortcut. The base body lays out the field; the variant map styles every input element inside it (`:is(input, select, textarea)`) with consistent focus and error states. To restyle every input in your forms uniformly, override the relevant variant key in your merged shortcuts — that's typically less work than passing `:class` per-field.

::: warning Comma-separated arbitrary variants
Comma-separated selector lists silently break the `dark:` qualifier — UnoCSS only prefixes `.dark ` onto the first selector. Wrap the inner list in `:is(...)` so the variant resolves to a single selector and theme-aware rules apply uniformly.

Same pitfall with nested attribute selectors: `[&_tr[data-state=checked]]:` silently fails. Wrap the inner attribute selector in `:is(...)`:

```typescript
"[&_tbody_tr:is([data-state=checked])]:": "scope-primary bg-current-hl/15",
```

:::

## Class extractor & safelisting

Two pieces handle "which `as-*` classes ship in the consumer's CSS":

- **`componentClasses`** — pre-computed `Record<kebab-name, string[]>` mapping each component (e.g. `as-form`, `as-filter-dialog`) to every class its template emits. Generated at our build time from the source.
- **`helperAliases`** — pre-computed `Record<helperName, kebab-name[]>` for the default-bundle helpers (`createDefaultTypes`, `createDefaultControls`, `createDefaultCellTypes`). A call to `createDefaultControls()` in your code pulls in classes for every default it wires up.

The custom extractor that `asPresetVunor()` registers walks your source for three signals:

1. Subpath imports — `from "@atscript/vue-form/as-input"`.
2. Barrel imports — `import { AsInput } from "@atscript/vue-form"`.
3. Tags — `<AsInput>`, `<as-input>`.
4. Helper calls — `createDefaultControls()`, `createDefaultTypes()`.

For each match it adds the corresponding kebab name to the safelist and pulls in `componentClasses[name]`. You don't have to safelist anything manually unless you reference a class via a string that the extractor can't see (e.g. `@ui.form.prefix.icon: 'i-as-star'` in a `.as` file).

For full manual control:

```typescript
import { getComponentClasses, getHelperClasses, asPresetVunor } from "@atscript/ui-styles";

export default defineConfig({
  presets: asPresetVunor({}),
  safelist: [
    ...getComponentClasses(["as-form", "as-input", "as-select"]),
    ...getHelperClasses("createDefaultTypes"),
  ],
});
```

`getComponentClasses(kebabNames, exclude?)` returns a deduped class array for the named components (companions included; an optional `ReadonlySet` of names to exclude prunes them and everything reachable only through them). `getHelperClasses(...helperNames)` does the same for the helper aliases.

### Excluding defaults you swapped out

If you replaced one of our default components with your own, the default's classes still ship by default — the extractor sees `createDefaultControls(` in your source and assumes you want the whole bundle. Drop them with `excludeComponents`:

```typescript
asPresetVunor({
  excludeComponents: ["as-filter-dialog", "as-config-dialog"],
});
```

After this, your custom `MyFilterDialog` renders normally, but the unused `as-filter-dialog-*` styles never make it into the bundle.

## Next steps

- [Pre-built CSS](/styling/prebuilt-css) — opt out of UnoCSS entirely (loses dynamic theming).
- [Theme & Palette](/styling/theme) — change colors and radius so the tree restyles itself.


---
URL: "ui.atscript.dev/styling/theme"
LLMS_URL: "ui.atscript.dev/styling/theme.md"
---

# Theme & Palette

`asPresetVunor()` accepts vunor's full `presetVunor` theme directly at the top level. Tuning a single brand color regenerates the entire `layer-*`, `surface-*`, `c8-*`, and `current-*` ladder — and every `as-*` shortcut that consumes them picks up the change automatically.

## Options

`asPresetVunor()`'s input is vunor's `presetVunor()` option type plus two atscript-specific extras (`excludeComponents`, `iconOverrides`). Every vunor field — `baseRadius`, `palette`, `fingertip`, `typography`, `animation`, … — is flat at the top level:

```typescript
interface AsPresetVunorOptions extends /* vunor's presetVunor options */ {
  excludeComponents?: AsComponentName[];
  iconOverrides?: Record<string, string>;
}
```

Omitted fields fall back to atscript-ui's baked defaults. Two of them merge per-key so you can override one entry without redeclaring the whole map:

- **`palette.colors`** — `{ primary: "#ff0000" }` keeps `grey` / `neutral` / `error` defaults.
- **`fingertip`** — `{ m: "36px" }` keeps the other four sizes.

Every other field (`baseRadius`, `palette.lightest`, `typography`, `animation`, …) replaces the default wholesale — provide the full shape if you set it. The baked defaults are exported as `defaultAsVunorOptions` if you want to read or spread them.

| Option              | Type                                    | Default        | Effect                                                                                                                                       |
| ------------------- | --------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseRadius`        | `string`                                | `"4px"`        | Drives `rounded-base` and vunor's `r0..r4` ladder used across forms, table cells, dialogs, and chips.                                        |
| `palette`           | vunor `TVunorPaletteOptions`            | see below      | Brand palette — `colors.primary`, `colors.grey`, `colors.error`, plus `lightest` / `darkest` / `layersDepth`. `colors` is per-key merged.    |
| `fingertip`         | `{ xs/s/m/l/xl?: string }`              | see below      | Touch-target ladder driving `h-fingertip-*` / `size-fingertip-*`. Per-key merged.                                                            |
| `typography`        | vunor typography map                    | vunor defaults | Override individual entries in the typography ladder (`body`, `callout`, `h1`, …). Wholesale replacement of the whole map.                   |
| `animation`         | `{ durations / animation / keyframes }` | vunor defaults | Animation tokens. Wholesale replacement.                                                                                                     |
| `excludeComponents` | `AsComponentName[]`                     | `[]`           | Kebab-case component names to drop from the safelist. Use when you swap a default for your own implementation and want to shed unused rules. |
| `iconOverrides`     | `Record<string, string>`                | `{}`           | Replace baked icons with custom SVG strings or Iconify IDs. See [Icons](/styling/icons).                                                     |

## Baked-in defaults

For reference (so you can see what changes when you override). Source: `defaultAsVunorOptions` in `@atscript/ui-styles`.

```typescript
const defaultAsVunorOptions = {
  baseRadius: "4px",
  fingertip: { xs: "20px", s: "28px", m: "32px", l: "36px", xl: "40px" },
  palette: {
    colors: {
      primary: "#2563eb", // blue accent
      grey: "#64748b", // slate neutrals
      neutral: "#475569", // slate (darker)
      error: "#dc2626", // red-600
    },
    lightest: 0.97,
    darkest: 0.22,
    layersDepth: 0.08,
  },
};
```

## Brand palette swap

The cleanest place to set brand colors is `asPresetVunor()` itself — no hand-composed preset list required:

```typescript
// uno.config.ts
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  content: { filesystem: ["src/**/*.{vue,ts,tsx}"] },
  presets: asPresetVunor({
    baseRadius: "8px",
    palette: {
      colors: {
        primary: "#a855f7", // your brand
        grey: "#71717a",
        neutral: "#52525b",
        error: "#ef4444",
        good: "#22c55e",
        warn: "#eab308",
      },
      lightest: 0.98,
      darkest: 0.18,
      layersDepth: 0.06,
    },
    fingertip: {
      xs: "18px",
      s: "26px",
      m: "32px",
      l: "38px",
      xl: "44px",
    },
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

You don't need to provide every key — anything omitted keeps the baked default. The smallest possible brand swap:

```typescript
presets: asPresetVunor({
  palette: { colors: { primary: "#a855f7" } },
}),
```

`grey`, `neutral`, and `error` keep their defaults; `lightest` / `darkest` / `layersDepth` keep theirs; `fingertip` and `baseRadius` keep theirs.

## Brand color propagation

The point of the palette story is that **a single brand color set in one place repaints every form and table.** Vunor's palette generator derives the full lightness ladder from your `primary`:

- `scope-primary` — the active scope. Every `as-*` shortcut that uses `scope-primary` (filter dialogs, focus rings, primary submit buttons) follows.
- `layer-0`, `layer-1`, `layer-2` — surface fill stacked by depth. Form inputs, table cells, dialog backdrops use these.
- `current-*` — text/border/outline color of the active scope. Drives `text-current/70`, `border-current/30`, `current-outline-hl`, etc.
- `c8-filled`, `c8-flat`, `c8-outlined`, `c8-light`, `c8-chrome` — the five button chromiums. Primary submit buttons, dialog actions, action menus all consume one of these.

You don't have to memorize the cascade. Set `palette.colors.primary` and inspect any form's submit button or any table's filter dialog — the brand color is there.

## Border radius

`baseRadius` drives the `r0..r4` ladder:

- `r0` — sharpest (e.g. dense data rows, `as-kbd` keyboard hint).
- `r1` — small buttons, pills, chips.
- `r2` — default for inputs, table cells, error banners.
- `r3` — dialogs, popup cards.
- `r4` — modal containers, prominent surfaces.

If you set `baseRadius: "0"`, every container goes sharp. If you set `baseRadius: "12px"`, the ladder scales up proportionally. The default is `4px`.

## Dark mode

`@atscript/ui-styles` ships dark-aware shortcuts. UnoCSS's default `dark:` variant is configured by `presetWind`-style presets vunor brings in; the active strategy is `class` mode — toggle a `dark` class on `<html>` (or the closest ancestor) and the entire tree switches.

```html
<html class="dark">
  ...
</html>
```

Vunor's `layer-*` / `surface-*` / `c8-*` primitives already include `dark:` rules internally, so most `as-*` shortcuts don't need to spell them out. Where a shortcut does need explicit dark handling (e.g. an input's explicit text color or a hand-painted scrollbar), it uses paired `text-scope-dark-0 dark:text-scope-light-0` / `dark:` variant keys — see `as-decimal-number.ts` (`innerInputReset` constant) and `as-window-scrollbar.ts` under `packages/ui-styles/src/shortcuts/{form,table}/` for examples.

To wire up a toggle, drive the class with VueUse:

```vue
<script setup lang="ts">
import { useDark, useToggle } from "@vueuse/core";

const isDark = useDark();
const toggleDark = useToggle(isDark);
</script>

<template>
  <button @click="toggleDark()">
    <span :class="isDark ? 'i-as-sun' : 'i-as-moon'" />
  </button>
</template>
```

## Reference: full config

```typescript
import { defineConfig } from "unocss";
import { allShortcuts, asPresetVunor } from "@atscript/ui-styles";
import { vunorShortcuts } from "vunor/theme";

export default defineConfig({
  content: { filesystem: ["src/**/*.{vue,ts,tsx}"] },
  presets: asPresetVunor({
    baseRadius: "8px",
    iconOverrides: {
      search:
        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="..."/></svg>',
    },
    excludeComponents: ["as-filter-dialog", "as-config-dialog"],
  }),
  shortcuts: [vunorShortcuts(allShortcuts)],
});
```

For deeper palette/typography tweaks (advanced palette config — `mainPalette`, `layerPalette`, `surfaces`), pass them as `palette` keys to `asPresetVunor` directly. The full vunor option shape is documented in the [vunor](https://github.com/mav-rik/vunor) docs.

## Next steps

- [Icons](/styling/icons) — bake-in defaults, overrides, and adding brand glyphs.
- [The as-\* Shortcut System](/styling/shortcuts) — how the shortcut tree is organized and how to extend it.


---
URL: "ui.atscript.dev/tables"
LLMS_URL: "ui.atscript.dev/tables.md"
outline: "deep"
---

# Tables

`@atscript/vue-table` renders smart, server-driven tables straight from an
annotated `.as` type. Sorting, filtering, pagination, virtual scrolling,
column resize/reorder, row selection and contextual actions all flow from
the same metadata you already wrote for your DB layer — no schema
duplication, no hand-wired column definitions, no per-cell glue.

## Mental model

The pipeline is three short steps:

```text
.as type + /meta  →  TableDef  →  <AsTable> / <AsWindowTable>
   (source)          (parsed)        (rendered)
```

1. **`.as` type.** A normal atscript interface, usually the same one that
   describes your DB table — decorated with `@db.*` (for the server),
   `@meta.*`, `@expect.*`, `@ui.table.*` and `@ui.dict.*`. Optional
   dynamic annotations come from `@atscript/ui-fns`.

2. **`createTableDef(meta, type)`** in `@atscript/ui` combines the server's
   `/meta` response (capabilities, CRUD permissions, actions, search
   indexes) with the deserialised type to produce a framework-agnostic
   `TableDef` — a list of `ColumnDef`s plus action and CRUD descriptors.
   `<AsTableRoot>` calls this for you; consumers rarely invoke it
   directly.

3. **`<AsTableRoot url=".." :types :controls>`** owns state. It fetches
   `/meta`, builds `TableDef`, manages reactive query state
   (`filters`, `sorters`, `searchTerm`, `pagination`, `columnNames`),
   dispatches queries and exposes everything via a `v-slot`. A child
   `<AsTable>` (paginated) or `<AsWindowTable>` (virtualised) consumes
   that context and renders rows.

## Component tiers

Every `vue-table` component lives in one of three tiers (see
`CLAUDE.md`):

- **Tier 1 — Primary.** What users tag in templates: `AsTableRoot`,
  `AsTable`, `AsWindowTable`, `AsTableActions`, `AsFilters`,
  `AsPresetPicker`. Auto-resolved by `AsResolver()`.
- **Tier 2 — Defaults.** Swappable cells and dialogs: `AsCellArray`,
  `AsCellDate`, `AsCellJson`, `AsCellNumber`, `AsCellUnion`,
  `AsTableCellValue`, `AsConfigDialog`, `AsFilterDialog`,
  `AsPresetDialog`, `AsConfirmDialog`, `AsActionFormDialog`,
  `AsTableHeaderCell`, `AsRowActions`, `AsColumnMenu`,
  `AsFilterField`, `AsFilterInput`. Composed via `:types` /
  `:controls` / `:components` prop maps.
- **Tier 3 — Internals.** `AsTableBase`, `AsTableVirtualizer`,
  `AsFilterValueHelp`, `AsOrderableList`, … — not exported.

## Paginated vs windowed

Two renderers consume the same root context:

- **`<AsTable>`** — classic paginated table. Pair with a pagination
  control bound to `state.pagination`. Best for stable, smaller
  result sets and CRUD-heavy admin screens.
- **`<AsWindowTable>`** — virtualised, block-aligned fetcher. Renders
  only the visible window of rows and streams blocks of size `:limit`
  as the user scrolls. Best for 10k+ row datasets or infinite-scroll
  feels.

See [Pagination & Virtualization](/tables/pagination) for the trade-offs
and tuning knobs.

## Model-driven state

Table state is the contract. Call sites — dialogs, toolbars, external
`v-model`, devtools, custom toolbars — only mutate the model arrays
(`filterFields`, `filters`, `columnNames`, `sorters`, `searchTerm`,
`pagination`). Reactions (re-query, pagination reset, `mustRefresh`)
live in a single root-level watcher, so any writer triggers identical
behaviour. **Mutators are pure** — each touches exactly one entity. In
particular, `filterFields` (which filter inputs are shown) and `filters`
(applied conditions) are independent: hiding an input does not clear
its value, clearing a value does not hide its input.

`state.query()` is reserved for user-initiated refreshes (refresh
button, pull-to-refresh). Never call it to "apply" a state change —
that path is the watcher's job.

## Where to go next

- [Hello World](/tables/hello-world) — a full working table in 25 lines.
- [Annotations Reference](/tables/annotations) — every `@ui.table.*`,
  `@ui.dict.*`, `@meta.*`, `@expect.*` and `@db.*` key the table reads.
- [Query Function](/tables/query-function) — moost-db wiring AND the
  custom `queryFn` escape hatch.
- [Filtering](/tables/filtering) — the filter model, value-help, and
  how UI state translates to Uniquery.
- [Sorting](/tables/sorting) — multi-sort, force sorters, header
  interactions.
- [Pagination & Virtualization](/tables/pagination) — choosing between
  `<AsTable>` and `<AsWindowTable>`, tuning block size.

::: tip Related ecosystem docs
The `.as` language, `asc` CLI and the core `@meta.*` / `@expect.*`
families live in the [atscript core docs](https://atscript.dev). The
`@db.*` annotations and the moost-db HTTP surface (`/meta`, `/q`,
relations, search indexes) are documented in the
[atscript-db docs](https://db.atscript.dev).
:::


---
URL: "ui.atscript.dev/tables/actions"
LLMS_URL: "ui.atscript.dev/tables/actions.md"
outline: "deep"
---

# Actions & Selection

Actions are server-callable operations on a row, on a set of rows,
or on the table itself. They're declared on the server next to the
table's controller and the table renders them in the right place — a
dropdown in the row, a button on the toolbar, or a bulk button that
lights up only when rows are selected. Each action can declare an
`@InputForm` so the table opens a form dialog before submitting.

## Action levels

Three scopes:

| Scope   | Where it renders      | Operates on      |
| ------- | --------------------- | ---------------- |
| `row`   | per-row dropdown      | one row          |
| `rows`  | toolbar (bulk button) | selected rows    |
| `table` | toolbar               | the table itself |

Row actions render through `<AsRowActions>` — a single button when
the row has exactly one action, a `…` dropdown when it has more.
Table and bulk actions render through `<AsTableActions>` in the
toolbar.

Declaration lives on the server — `@atscript/moost-db`'s `@DbAction`
decorator on the table's controller. The level is **inferred** from
the handler's parameter decorators (`@DbActionID()` → `row`,
`@DbActionIDs()` → `rows`, neither → `table`), and the table receives
the finished list — name, label, level, icon, intent — from the
`/meta` response's `actions` array:

```typescript
import {
  AsDbController,
  TableController,
  DbAction,
  DbActionID,
  DbActionIDs,
} from "@atscript/moost-db";
import { Post } from "@moostjs/event-http";
import { Order } from "./schema/order.as";
import { ordersTable } from "./db";

@TableController(ordersTable)
export class OrdersController extends AsDbController<typeof Order> {
  @Post("actions/ship")
  @DbAction("ship", { label: "Ship" })
  async ship(@DbActionID() id: { id: string }) {
    // one identifier → level: 'row'
  }

  @Post("actions/export")
  @DbAction("export", { label: "Export" })
  async exportOrders(@DbActionIDs() ids: { id: string }[]) {
    // identifier array → level: 'rows'
  }
}
```

`@DbAction` carries the full server-side wiring — handler, input
form, intent, gating, and the level itself. See the
[db.atscript.dev annotations reference](https://db.atscript.dev)
for the full surface. The table just renders what `/meta` reports.

## Input forms

An action with `@InputForm` declares a `.as` type as its input
schema:

```atscript
export interface RefundInput {
    @meta.label 'Amount'
    amount: number

    @meta.label 'Reason'
    reason: string
}
```

```typescript
@Post("actions/refund")
@DbAction("refund", { label: "Refund" })
async refund(@DbActionID() id: { id: string }, @InputForm(RefundInput) input: RefundInput) {
  // ...
}
```

When the user invokes `refund`, the table opens
`<AsActionFormDialog>`. The dialog fetches the form schema, renders
it through `<AsForm>` (from `@atscript/vue-form`), and submits with
the form data wrapped as `{ input: ... }`. The dialog is mounted
lazily — only when an action with `@InputForm` is detected on the
table.

To customise the dialog body, use `<AsTableRoot>`'s `#actionForm`
slot — it forwards through to the dialog. To replace the dialog
entirely, swap `controls.actionFormDialog` (Tier 2).

## Selection

`state.selectedRows` is a `ShallowRef<unknown[]>` — the primary
keys (or composite-PK objects) of selected rows. The selection
mode is set on `<AsTable :select="...">`:

- `"none"` (default) — no checkboxes; row clicks fire the default action.
- `"single"` — radio-style: row clicks replace the selection with that row's PK.
- `"multi"` — checkbox column; clicks toggle selection.

```vue
<AsTable :select="select" :row-delete="canDeleteRows" />
```

`canDeleteRows` is a boolean (or `RowDeleteOpt`) — when true, the
table synthesises a `__remove` row action with a confirm prompt.

`state.selectedCount` is a computed for badge counts.
`state.isPkSelected(pk)` is the O(1) "is this row selected"
predicate used internally by the checkbox cell.

## Programmatic invocation

`state.actions.invoke(action, pk?, opts?)` invokes any action
without going through the UI:

```ts
import { useTableActions } from "@atscript/vue-table";

const actions = useTableActions();

// Per-row
const result = await actions.invoke(action, { id: "order-123" });

// Bulk
const result = await actions.invoke(action, [{ id: "order-1" }, { id: "order-2" }]);

if (result.ok) {
  // result.kind: 'backend' | 'navigate' | 'custom' | 'remove'
} else {
  // result.kind === 'error', result.error: ClientError | Error
}
```

`pk` is always an identifier **object** (or array of objects),
never a bare scalar. This is per `@atscript/db-client`'s invariant
#11 — even a single-PK table sends `{ id: "..." }`.

`InvokeOpts.input` carries the `@InputForm` payload for actions
that have one; `InvokeOpts.suppressRefresh` skips the post-success
re-query for this one call; `InvokeOpts.event` bridges to the
`<AsTableRoot @action>` emit.

The result is a discriminated union — it never throws. Toast / log
based on `result.ok` and `result.kind`.

## The `@action` emit

`<AsTableRoot @action="onAction">` fires after every action result.
This is where apps wire **custom processors** — actions whose
`processor === 'custom'` skip the server entirely and dispatch to
client code:

```ts
function onAction(action: TVueTableActionInfo, ids: unknown[], result: ActionResult) {
  if (action.processor === "custom" && action.name === "export-csv") {
    void downloadCsv(apiPath, ids);
    return;
  }
  if (!result.ok) {
    pushToast(false, `${action.label} failed: ${result.error.message}`);
    return;
  }
  if (result.kind === "remove") {
    const removed = (result.data as { deletedCount?: number })?.deletedCount ?? 1;
    pushToast(true, `Deleted ${removed} row(s).`);
  }
  // ...
}
```

The CSV export pattern is straightforward: declare the action as
`processor: 'custom'` on the `.as`, then match it by name in the
`@action` handler.

## Row-level default action

A row action can be marked default. The framework's **main-action**
path invokes it on `dblclick` or **Enter** when the table is in
`select="none"` mode. Single-click is always reserved for cursor
placement / selection — never the default action. The current
default is exposed as `state.actions.default.row`.

The selection state is reactive end-to-end: a `multi → none`
transition auto-clears `selectedRows`; the actions column
appears / disappears live without a remount; bulk action buttons
disable when nothing is selected.

## Toggling action-column visibility

`state.includeActions` is a writable ref controlled by the
renderer. The `<AsTable :row-actions-column="...">` prop (or
`<AsWindowTable>`'s equivalent) flips it on when the table has at
least one row-level action. When on, `buildTableQuery` requests
per-row `$actions: string[]` from the server so the dropdown can
hide actions that are server-disabled for this specific row.

## Next steps

- [Customization](/tables/customization) — swap dialogs and row
  action chrome.
- [Server-Side Presets](/tables/server-presets) — wire up the
  Moost backend.


---
URL: "ui.atscript.dev/tables/annotations"
LLMS_URL: "ui.atscript.dev/tables/annotations.md"
outline: "deep"
---

# Annotations Reference

Every visual, behavioural and capability decision the table makes is
driven by an annotation on the underlying `.as` type. This page is the
authoritative list of what each one does, where to put it, and which
component reads it.

Annotations cluster into five namespaces:

- **`@ui.table.*`** — static, table-only.
- **`@ui.table.fn.*`** — dynamic (runtime JS expressions) — requires
  `@atscript/ui-fns`.
- **`@ui.dict.*`** — value-help / dictionary display + capabilities.
  Read both by the table (FK target columns) and by the value-help
  picker UI.
- **`@ui.type`** — cross-cutting renderer override (applies wherever
  there's no surface-specific override).
- **`@meta.*`** / **`@expect.*`** — generic atscript metadata read by
  the table (labels, IDs, max length, nullability).
- **`@db.*`** — DB-layer annotations read indirectly via the moost-db
  `/meta` response (relations, search indexes, currency/units) or
  directly off the type (FK info, JSON, precision).

## `@ui.table.*` — static column annotations

| Annotation                       | Arg(s)                     | Where                       | Controls                                                                                                                                                                                                                                           |
| -------------------------------- | -------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@ui.table.type "type"`          | built-in renderer id       | `prop`, `type`              | Flips the built-in cell renderer. Built-in ids: `text`, `number`, `boolean`, `date`, `datetime`, `relative`, `array`, `object`, `union`, `enum`, `ref`. Reserved for built-ins — for custom cells use `@ui.table.component`. Wins over `@ui.type`. |
| `@ui.table.component "name"`     | component name             | `prop`, `type`, `interface` | Named component override for custom cells — looked up in the `:components` map passed to `<AsTableRoot>`. The dedicated mechanism for hand-rolled renderers. Wins over `@ui.table.type` when both resolve.                                         |
| `@ui.table.selectWith "field"`   | sibling leaf field path    | `prop`, `type`              | Extra sibling leaf field a custom cell needs, fetched into `$select` whenever this column is visible. Never a column itself. Repeatable; see [Custom Cells](/tables/custom-cells).                                                                 |
| `@ui.table.width "240px"`        | CSS width string           | `prop`, `type`              | Default column width. Double-clicking the resize handle auto-fits to content; the column menu's _Reset width_ entry restores this value.                                                                                                           |
| `@ui.table.hidden`               | —                          | `prop`, `type`              | Column hidden by default. User can re-enable via _Columns_ in the config dialog (it still appears in `state.allColumns`).                                                                                                                          |
| `@ui.table.order N`              | `number`                   | `prop`, `type`              | Initial column ordering. Lower values appear first. User-driven reorder still mutates `state.columnNames` and is preserved per-preset / per-URL-state.                                                                                             |
| `@ui.table.attr "name", "value"` | name, value                | `prop`, `type`              | Custom attribute or component prop applied to the rendered `<td>`. Repeatable.                                                                                                                                                                     |
| `@ui.table.classes "names"`      | space-separated class list | `prop`, `type`, `interface` | CSS classes appended to every `<td>` in this column. Repeatable. Use `as-*` shortcuts or vunor primitives — see [Customization](/tables/customization).                                                                                            |
| `@ui.table.styles "css"`         | inline CSS                 | `prop`, `type`, `interface` | Inline styles appended to the rendered `<td>`. Repeatable.                                                                                                                                                                                         |

```atscript
@ui.table.width "12em"
@ui.table.order 1
@ui.table.classes "font-mono"
sku: string

@ui.table.component 'identity'
@ui.table.selectWith 'firstName'
@ui.table.selectWith 'lastName'
username: string
```

## `@ui.table.fn.*` — dynamic column annotations

These require `@atscript/ui-fns` (installed alongside `@atscript/ui`).
The argument is a JavaScript expression evaluated per-row with the row
data in scope — use sparingly, this opts into `new Function()`.

| Annotation                         | Arg(s)              | Controls                                                                        |
| ---------------------------------- | ------------------- | ------------------------------------------------------------------------------- |
| `@ui.table.fn.attr "name", "expr"` | name, JS expression | Per-row attribute/prop on the `<td>`. Repeatable; each evaluated for every row. |
| `@ui.table.fn.classes "expr"`      | JS expression       | Per-row class list on the `<td>`. Repeatable.                                   |
| `@ui.table.fn.styles "expr"`       | JS expression       | Per-row inline style on the `<td>`. Repeatable.                                 |

```atscript
@ui.table.fn.classes "inStock ? 'text-success' : 'text-error'"
inStock: boolean
```

::: warning Dynamic expressions
`@ui.table.fn.*` expressions are JS evaluated at runtime — keep them
short, side-effect free, and never let untrusted content flow into the
`.as` source.
:::

## `@ui.dict.*` — value-help (FK target) annotations

When a table column is a foreign-key reference (`@db.rel.FK`), the
table doesn't show the raw ID — it shows a label resolved from the
referenced row. The referenced interface declares which fields play
which role with the `@ui.dict.*` family:

| Annotation            | Node                | Purpose                                                                                                           |
| --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `@ui.dict.label`      | `prop`              | Primary display field for value-help and `ref`-type cells.                                                        |
| `@ui.dict.descr`      | `prop`              | Secondary description in the value-help picker.                                                                   |
| `@ui.dict.attr`       | `prop`              | Additional attribute column in table-mode value-help. Repeatable.                                                 |
| `@ui.dict.filterable` | `prop`              | Filterable in the picker UI (surfaced via `meta.fields[name].filterable`).                                        |
| `@ui.dict.sortable`   | `prop`              | Sortable in the picker UI.                                                                                        |
| `@ui.dict.searchable` | `prop`, `interface` | Participates in `$search` inside the value-help picker. On an interface, marks every `string` prop as searchable. |

```atscript
@db.table 'categories'
export interface Category {
    @meta.id
    @db.default.increment
    id: number

    @ui.dict.label
    name: string

    @ui.dict.descr
    description?: string
}
```

When the parent table references `Category`, its `categoryId` column
renders the category's `name`, and the filter dialog's value-help
typeahead searches against `name` / `description`.

::: tip Read server-side
`@ui.dict.filterable` / `@ui.dict.sortable` / `@ui.dict.searchable` are
parsed by moost-db's `AsValueHelpController` and emitted into the
`/meta` response. No additional client wiring is needed.
:::

## `@ui.type` — shared renderer override

`@ui.type "name"` flips the renderer type wherever the surface-specific
override (`@ui.form.type` / `@ui.table.type`) is missing. The value
must be one of the **built-in** type ids the form/cell type maps know
how to dispatch — `@ui.type` and `@ui.{form,table}.type` are reserved
for built-in renderers.

```atscript
@ui.type 'textarea'
notes: string                  // form renders textarea; table cell stays text
```

For **custom** renderers shared between forms and tables (currency,
status badge, rating, …), use `@ui.form.component` on the form side
and `@ui.table.component` on the table side. Both annotations look up
in their own `:components` map and are the dedicated mechanism for
hand-rolled widgets.

## `@meta.*` and `@expect.*` — read by the table

These come from atscript core; the table reads a small subset.

| Annotation                        | Effect on the table                                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `@meta.id`                        | Marks the primary key. Surfaces in `tableDef.primaryKeys`; drives action POSTs, `__remove` and row addressing.            |
| `@meta.label "..."`               | Column header text. Falls back to a humanised path when absent.                                                           |
| `@meta.description "..."`         | Tooltip text on the header cell.                                                                                          |
| `@expect.maxLength N`             | Used to derive the default column width when `@ui.table.width` is absent. The longer the max, the wider the column.       |
| `optional` (atscript syntax `?:`) | Sets `ColumnDef.nullable = true`. The filter dialog's operator picker shows `null` / `notNull` only for nullable columns. |

```atscript
@meta.id
@db.default.increment
id: number

@meta.label 'Product Name'
@expect.maxLength 80
name: string

description?: string
```

See [atscript.dev annotations](https://atscript.dev/packages/typescript/annotations)
for the full `@meta.*` / `@expect.*` reference.

## `@db.*` — read indirectly (and a couple directly)

Most `@db.*` annotations belong to the [atscript-db skill](https://db.atscript.dev),
but several flow back into the table either through the `/meta`
response or by direct introspection of the column's atscript type.

| Annotation                      | Read by                       | What it does for the table                                                                                                                           |
| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@db.table 'name'`              | server (`/meta`)              | Makes the interface a DB table; required for moost-db to serve it.                                                                                   |
| `@db.http.path '/...'`          | server                        | Mounts the moost-db controllers under a custom HTTP path — `<AsTableRoot url="..."`> points here.                                                    |
| `@db.index.fulltext 'name'`     | server (`/meta`)              | Adds a full-text search index. `tableDef.searchable` becomes `true`; the search box drives `controls.$search`.                                       |
| `@db.index.plain 'name'`        | server (`/meta`)              | Surfaces the column as filterable / sortable (in combination with `@db.column.*` / `@db.table.*` flags). Powers the column menu's _Sort_ / _Filter_. |
| `@db.index.unique 'name'`       | server (`/meta`)              | Same as above; also flagged in relation metadata.                                                                                                    |
| `@db.rel.FK`                    | client (`extractValueHelp`)   | Marks a column as a foreign key. Cell type becomes `ref`; the filter dialog opens a value-help picker against the referenced table.                  |
| `@db.json`                      | server                        | Stores the field as opaque JSON. Sub-paths are NOT auto-flattened into columns — the cell shows the JSON via `AsCellJson`.                           |
| `@db.amount.currency 'EUR'`     | client (`extractMeasurement`) | Literal currency code; `AsCellNumber` formats with `Intl.NumberFormat` for that currency.                                                            |
| `@db.amount.currency.ref 'fld'` | client                        | Sibling-field reference — currency comes from another column on the same row.                                                                        |
| `@db.unit 'kg'`                 | client                        | Literal unit-of-measure suffix on numeric cells.                                                                                                     |
| `@db.unit.ref 'fld'`            | client                        | Sibling-field unit reference.                                                                                                                        |
| `@db.column.precision p, s`     | client                        | Decimal precision/scale — `AsCellNumber` honours the second arg as fraction-digit count.                                                             |

::: info Where to learn more

- The DB / table / column / index / relation annotations:
  [db.atscript.dev/api/tables](https://db.atscript.dev/api/tables) and
  [db.atscript.dev/relations](https://db.atscript.dev/relations).
- The `/meta` HTTP response shape:
  [db.atscript.dev/http/crud](https://db.atscript.dev/http/crud).
  :::

## Putting it together

A realistic column annotated for the table:

```atscript
@db.table 'invoices'
export interface InvoicesTable {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Invoice #'
    @ui.table.order 1
    @ui.table.width "8em"
    @db.index.unique 'invoice_no_idx'
    number: string

    @meta.label 'Customer'
    @ui.table.order 2
    @db.rel.FK
    customerId: Customer.id

    @meta.label 'Status'
    @ui.table.order 3
    @ui.table.fn.classes "status === 'paid' ? 'text-success' : ''"
    status: 'draft' | 'sent' | 'paid' | 'overdue'

    @meta.label 'Amount'
    @ui.table.order 4
    @db.column.precision 12, 2
    @db.amount.currency.ref 'currency'
    amount: number

    currency: 'USD' | 'EUR' | 'GBP'

    @meta.label 'Issued'
    @ui.table.type 'date'
    @db.default.now
    issuedAt: number
}
```

That single declaration drives:

- Column order (`@ui.table.order`), labels (`@meta.label`).
- A fixed-width `Invoice #` column (`@ui.table.width`).
- A FK lookup against `Customer` rendering the customer's
  `@ui.dict.label` (`@db.rel.FK`).
- A coloured status badge per row (`@ui.table.fn.classes`).
- A currency-formatted amount that reads the currency from a sibling
  cell (`@db.amount.currency.ref` + `@db.column.precision`).
- A date renderer for `issuedAt` (`@ui.table.type 'date'`).

## Next steps

- [Query Function](/tables/query-function) — how `/meta` and CRUD wire
  up, and how to bring your own data fetcher.
- [Filtering](/tables/filtering) — the filter model that consumes
  `filterable` / `nullable` / `options` / `valueHelpInfo`.
- [Cells](/tables/cells) — the default cell components and how to plug
  in your own.


---
URL: "ui.atscript.dev/tables/cells"
LLMS_URL: "ui.atscript.dev/tables/cells.md"
outline: "deep"
---

# Cells

Every visible column in `<AsTable>` resolves to a Vue component. The
resolver picks one of the built-in cells based on the column's
`.as`-derived metadata, or honours an explicit named override. Apps
override individual cells without forking the table.

## Default cell-type map

`createDefaultCellTypes()` returns a fresh, mutable map seeded with
every built-in. Spread it to add or replace entries:

```ts
import { createDefaultCellTypes } from "@atscript/vue-table";

const types = {
  ...createDefaultCellTypes(),
  rating: MyRatingCell,
};
```

The seeded entries:

| Column type                      | Component          |
| -------------------------------- | ------------------ |
| `text`, `boolean`, `enum`, `ref` | `AsTableCellValue` |
| `number`                         | `AsCellNumber`     |
| `date`, `datetime`, `relative`   | `AsCellDate`       |
| `array`                          | `AsCellArray`      |
| `object`                         | `AsCellJson`       |
| `union`                          | `AsCellUnion`      |
| `__actions` (synthesised pseudo) | `AsRowActions`     |

Every built-in cell is also importable individually via its kebab
subpath (e.g. `import AsCellDate from "@atscript/vue-table/as-cell-date"`)
when you'd rather hand-pick entries than spread the full default map.

Pass the map to the table root:

```vue
<AsTableRoot url="/db/products" :types="types" />
```

## Resolution rules

`useCellComponents()` runs once per column on mount and on every
TableDef change. The order matches `<AsField>` in vue-form:

1. `@ui.table.component "name"` on the field → `ctx.components[name]`.
2. Column `type` (`text`, `number`, …) → `ctx.types[type]`.
3. Fallback → `AsTableCellValue`.

The lookup happens per-column, not per-row — a 50×10 table avoids
about 500 redundant resolutions per render. Named overrides win
because they're explicit; type-map overrides cover whole categories
(every `date` column or every `number` column) without touching the
`.as`.

## Built-in cells

Every cell receives the same two props:

```ts
defineProps<{
  row: Record<string, unknown>;
  column: ColumnDef;
}>();
```

The cell uses `getCellValue(row, column.path)` to walk the dotted
path. Per-cell class / style / attribute annotations are applied by
the resolver before the cell mounts — your cell doesn't read them.

### `AsTableCellValue`

The default for scalar types (`text`, `boolean`, `enum`, `ref`).
Renders the raw value through `formatCellValue(value, type)`:
booleans become `Yes` / `No`, nullish values render as empty. Adds
`as-cell-number` when the column happens to be numeric so right
alignment kicks in.

### `AsCellNumber`

Locale-formatted, right-aligned, tabular-nums. Reads four pieces of
`.as` metadata off `column`:

- `@db.amount.currency 'USD'` → `column.currencyCode`. Wins over
  precision; `Intl.NumberFormat` derives the fraction digits from
  CLDR.
- `@db.amount.currency.ref 'currency'` → `column.currencyRefField`.
  Per-row currency code; the cell reads `row[refField]`.
- `@db.column.precision 4` → `column.precisionScale`. Static fraction
  digits when no currency is set.
- `@db.unit 'kg'` / `@db.unit.ref 'unit'` → `column.unitCode` /
  `column.unitRefField`. Renders as `Intl.NumberFormat({ style:
"unit", unit })`.

Shares `formatDecimalForDisplay` with `<AsNumber>` so form input and
table cell render identically.

### `AsCellDate`

Locale-and-timezone aware. The column type picks the format:

- `date` → `{ year, month: 'short', day: '2-digit' }`
- `datetime` → adds `{ hour: '2-digit', minute: '2-digit' }`
- `relative` → `formatTimeAgoIntl(value)` (e.g. `3 hours ago`).

Null-like values (`null` / `undefined` / `""`) and the Unix-epoch
sentinel (timestamp `0`) render as blank cells.

The cell always stamps `title` with the absolute ISO string so e2e
tests can assert the canonical timestamp regardless of locale.

### `AsCellArray`

Comma-separated chips when every element is primitive; a popover
button with a JSON tree when at least one element is a non-primitive.
Empty arrays render as blank.

### `AsCellJson`

Button glyph (`{}`) opens a popover that pretty-prints the object as
a JSON tree. Used for free-form `@db.json` columns.

### `AsCellUnion`

Dispatches by runtime shape — primitive → text, object → JSON
popover, array of primitives → chips, array of objects → JSON
popover. Useful for tagged-union columns where each variant renders
differently per row.

## App-wide locale

The cell suite reads two values via provide / inject: a BCP-47
language tag and an IANA timezone. Pipe them in once at the app root
and every cell picks them up:

```vue
<script setup lang="ts">
import { provideCellLocale, useAppPrefs } from "@atscript/vue-table";
const { prefs } = useAppPrefs({ url: "/api/db/_presets" });
provideCellLocale(() => ({
  language: prefs.value.language,
  timezone: prefs.value.timezone,
}));
</script>
```

`provideCellLocale` accepts a `MaybeRefOrGetter<CellLocale>`, so a
getter closing over reactive state recomputes on every change.
Without a provider, `useCellLocale` falls back to `navigator.language`
and the browser's resolved timezone.

## Adding a custom cell renderer

Two-step: tag the field with `@ui.table.component`, then register the
component in the `:components` map. `@ui.table.component` is the
dedicated mechanism for hand-rolled cells — `@ui.table.type` (and the
cross-cutting `@ui.type`) is reserved for the built-in renderer ids
above.

```atscript
@meta.label 'Rating'
@ui.table.component 'rating'
rating: number
```

```ts
import MyRatingCell from "./cells/rating.vue";

const components = { rating: MyRatingCell };
```

Pass it through `<AsTableRoot :components="components">` (or the
controls/options object that consumes it).

:::tip Convention

- `:types` map — **built-in** cell renderer ids (`text`, `number`,
  `date`, `array`, …). Touched by `@ui.table.type` / `@ui.type`.
- `:components` map — your custom cells. Touched by
  `@ui.table.component`.

The TS type for the cells map is `TAsCellTypeComponents`, exported
from `@atscript/vue-table`. It declares every built-in slot plus an
open `Record<string, Component>` index — but reserve that open slot
for renderers you genuinely want to dispatch by _type id_ across many
fields (e.g. a project-wide `currency` cell). One-off cells belong in
`:components`.
:::

## Next steps

- [Custom Cells](/tables/custom-cells) — write your own cell, or use
  a per-column slot.
- [Customization](/tables/customization) — swap dialogs, header
  cells, row actions, the column menu.


---
URL: "ui.atscript.dev/tables/config-dialog"
LLMS_URL: "ui.atscript.dev/tables/config-dialog.md"
outline: "deep"
---

# Config Dialog

`AsConfigDialog` is the table's settings panel. Three tabs:
**Columns**, **Sorters**, **Filters**. The dialog mutates state
arrays only — the root watcher reacts and re-queries. There is no
"Apply" button that calls the server; "Apply" is a synchronous state
write.

## Opening it

The dialog is mounted once by `<AsTableRoot>`. It binds its `open`
state to `state.configDialogOpen`. Three triggers ship out of the
box:

- The toolbar **Settings** button in `<AsTableActions>`.
- Each column header's dropdown menu (`<AsColumnMenu>`) — opens the
  dialog directly on the matching tab.
- Programmatic: `state.showConfigDialog(tab?)` from any composable
  with access to `useTableContext()`.

```ts
import { useTableContext } from "@atscript/vue-table";

const { state } = useTableContext();

function openFilters() {
  state.showConfigDialog("filters");
}
```

The tab argument is typed as `ConfigTab = 'columns' | 'sorters' | 'filters'`.
Omit it to reopen on the last-used tab (the dialog persists
`state.configTab` across opens).

## The three tabs

The dialog copies state into local refs on open and writes back to
state on **Apply**. Cancel discards the local copy. This makes the
dialog feel snappy — you can drag rows around without firing
queries on every keystroke.

### Columns

Controls **visibility** and **order** of the column list. The user
checks columns on and off, drags rows to reorder, and the dialog
writes the merged `string[]` back to `state.columnNames` on Apply.
Width controls live on the column header (resize handle, "Reset
width" entry in the column menu) — the dialog doesn't duplicate
them.

### Sorters

Reorder, add, or remove `SortControl[]`. Drag rows to set priority.
The dialog shows only fields where `column.sortable === true` (see
the `sortableColumns` filter in `<AsConfigDialog>`).

The Sorters tab is also where you'd hit **Clear all** to drop every
sorter in one click.

### Filters

This is the **display list**, not the applied conditions. Checking a
field makes its filter input appear in the filter bar; unchecking
hides the input. **Hiding an input does not clear its value** — the
applied filter on `state.filters[path]` stays put until you clear
it explicitly. The tab shows a small count badge for fields that
have an applied condition.

The two concerns are independent on purpose: a user can hide a
filter input to clean up the bar without losing the condition they
already typed.

## Mutation model

The dialog's **Apply** button is three writes:

```ts
state.columnNames.value = columnsModel.value;
state.filterFields.value = filtersModel.value;
state.sorters.value = sortersModel.value;
state.configDialogOpen.value = false;
```

That's the entire flow. The root watcher in `use-table-query.ts`
observes these arrays and fires a re-query when needed. The dialog
does **not** call `state.query()`. This is part of the broader
model-driven contract — every writer (this dialog, the column
header menu, programmatic callers, URL hydration) triggers the same
reaction through the same watcher.

## Swapping the dialog

`AsConfigDialog` is a Tier-2 default. Replace it via the `controls`
map on the root:

```ts
import MyConfigDialog from "./MyConfigDialog.vue";

const controls = { configDialog: MyConfigDialog };
```

```vue
<AsTableRoot url="/db/products" :controls="controls" />
```

Your replacement reads `state.configDialogOpen`, `state.configTab`,
and the same state arrays as the default. Anchor your dialog to
`v-model:open="state.configDialogOpen"` and write the same three
arrays on Apply — every other reaction (re-query, URL sync, preset
dirty-check) flows automatically from those writes.

If you only want a different look on one tab, keep the swap at the
dialog level: your replacement reads the same state arrays
(`columnNames`, `filterFields`, `sorters`) and writes them back —
build the inner tab UI however your design system prefers. The
default's per-tab building blocks are package internals and not part
of the public surface.

## Next steps

- [URL State](/tables/url-state) — share table state via the address
  bar.
- [Presets](/tables/presets) — save and restore named configurations.
- [Customization](/tables/customization) — full list of swappable
  controls.


---
URL: "ui.atscript.dev/tables/custom-cells"
LLMS_URL: "ui.atscript.dev/tables/custom-cells.md"
outline: "deep"
---

# Custom Cells

Three ways to render a column differently from the default:

1. **Slot** — quick per-table override via `<template #cell-{path}>`.
2. **Type swap** — replace every cell of one `type` for one table.
3. **Named component** — opt-in per column with
   `@ui.table.component`, swap it via the `:components` map.

The first is template-local. The second and third reuse a component
across every table that opts in.

## The cell contract

Every cell component receives exactly two props:

```ts
import type { ColumnDef } from "@atscript/ui";

defineProps<{
  row: Record<string, unknown>;
  column: ColumnDef;
}>();
```

`row` is the raw row object from the server. `column` is the
runtime column descriptor — type, label, path, precision, currency
ref, etc.

The cell uses `getCellValue(row, column.path)` to walk the dotted
path:

```vue
<script setup lang="ts">
import { computed } from "vue";
import { getCellValue } from "@atscript/vue-table";
import type { ColumnDef } from "@atscript/ui";

const props = defineProps<{
  row: Record<string, unknown>;
  column: ColumnDef;
}>();

const value = computed(() => getCellValue(props.row, props.column.path));
</script>

<template>
  <td>{{ value }}</td>
</template>
```

Render a `<td>`. The cell sits inside a `<tr>` rendered by `<AsTable>`
— it owns the row, not the cell. Set classes / styles directly on
the `<td>` you emit.

::: warning Annotation-driven bindings
`@ui.table.classes`, `@ui.table.styles`, `@ui.table.attr`, and their
`fn.*` variants are applied automatically by the per-cell resolver
(`useCellResolver`) before the cell mounts. Your custom cell doesn't
need to read them — they v-bind onto the cell's `<td>` outer element
via the parent's `<component :is="..." v-bind="cellBindings">`.
:::

The type for cell-type maps is `TAsCellTypeComponents`:

```ts
import type { TAsCellTypeComponents } from "@atscript/vue-table";

const types: TAsCellTypeComponents = {
  ...createDefaultCellTypes(),
  rating: MyRatingCell,
};
```

## Pattern A — type swap

Replace every cell of one type for one table. Useful when an entire
project standardises on a richer renderer (your own date picker,
your own currency formatter).

```ts
import { createDefaultCellTypes } from "@atscript/vue-table";
import MyDateCell from "./cells/MyDateCell.vue";

const types = { ...createDefaultCellTypes(), date: MyDateCell, datetime: MyDateCell };
```

```vue
<AsTableRoot url="/db/orders" :types="types" />
```

Every `date` and `datetime` column on this table renders through
`MyDateCell`.

## Pattern B — named per-column override

`@ui.table.component` tags a single field; the table looks it up in
the `:components` map. Other columns of the same type stay on the
default.

```atscript
@db.table 'products'
export interface Product {
    @meta.id id: string

    @meta.label 'Status'
    @ui.table.component 'statusBadge'
    status: 'active' | 'archived' | 'pending'
}
```

```ts
import StatusBadgeCell from "./cells/StatusBadgeCell.vue";

const components = { statusBadge: StatusBadgeCell };
```

```vue
<AsTableRoot url="/db/products" :components="components" />
```

The resolver tries named lookup first, falls back to type lookup,
then `AsTableCellValue`. Tagging more fields with
`@ui.table.component 'statusBadge'` reuses the same renderer.

## Pattern C — slot

The fastest override is a slot on the table. No `.as` change, no
component file — just inline template per column:

```vue
<AsTable>
  <template #cell-price="{ value }">
    <td class="text-right tabular-nums">${{ Number(value).toFixed(2) }}</td>
  </template>

  <template #cell-inStock="{ value }">
    <td>
      <span :class="['as-status-badge', value ? 'scope-good' : 'scope-error']">
        {{ value ? "In Stock" : "Out of Stock" }}
      </span>
    </td>
  </template>
</AsTable>
```

`<AsTable>` exposes one slot per column path plus four global slots:

- `#header-<path>` — replace the `<th>`.
- `#cell-<path>` — replace the `<td>`.
- `#empty` — body when results are empty.
- `#query-loading` — overlay while a fetch is in flight.
- `#error` — body when the last query failed (receives `{ error }`).

Pick a slot when the override is one-off and template-local. Pick a
component swap (Pattern A or B) when the cell repeats across tables.

## Worked example: status badge

A reusable cell that paints a coloured pill using the `scope-good` /
`scope-error` tokens from vunor's shortcuts engine. Works on any
column whose value is a discriminator string.

```vue
<!-- cells/StatusBadgeCell.vue -->
<script setup lang="ts">
import { computed } from "vue";
import { getCellValue } from "@atscript/vue-table";
import type { ColumnDef } from "@atscript/ui";

const props = defineProps<{
  row: Record<string, unknown>;
  column: ColumnDef;
}>();

const value = computed(() => getCellValue(props.row, props.column.path));

const scope = computed(() => {
  switch (value.value) {
    case "active":
    case "shipped":
      return "scope-good";
    case "archived":
    case "cancelled":
      return "scope-error";
    case "pending":
      return "scope-attention";
    default:
      return "scope-neutral";
  }
});
</script>

<template>
  <td>
    <span class="as-status-badge" :class="scope">{{ value }}</span>
  </td>
</template>
```

Add the matching shortcut to ui-styles (or your own UnoCSS preset)
so the class compiles:

```ts
defineShortcuts({
  "as-status-badge": "inline-flex items-center px-$s py-$xxs text-callout rounded-base c8-light",
});
```

Wire it on the `.as`:

```atscript
@db.table 'orders'
export interface Order {
    @meta.id id: string

    @meta.label 'Status'
    @ui.table.component 'statusBadge'
    status: 'pending' | 'shipped' | 'cancelled'
}
```

And on the Vue mount:

```ts
import StatusBadgeCell from "./cells/StatusBadgeCell.vue";

const components = { statusBadge: StatusBadgeCell };
```

```vue
<AsTableRoot url="/db/orders" :components="components" />
```

Every order row now shows a coloured status pill; the rest of the
table stays on the default renderers.

## Fetching sibling fields a cell needs

A custom cell can only read fields that are present in the row object —
and that object is exactly the **visible** columns. The table projects
just the displayed columns into `$select`, so if your cell tries to
composite a sibling field that isn't its own column, that field is
absent from `row` and the cell renders blank.

The classic case is an **identity cell**: a single `username` column
that paints an avatar plus a formatted "First Last". The `avatar`,
`firstName`, and `lastName` fields are never columns of their own — but
the cell needs all three to render.

### Per-column deps — `@ui.table.selectWith`

Co-locate `@ui.table.selectWith 'field'` on the field your cell
renders. Each annotation names one sibling **leaf** field path to also
fetch whenever the owning column is displayed; repeat it once per extra
field. The extra fields ride along in the row payload but are never
rendered as columns, never toggleable, and never appear in the config
dialog.

```atscript
@db.table 'users'
export interface UsersTable {
    @meta.id id: string

    @meta.label 'User'
    @ui.table.component 'identity'
    @ui.table.selectWith 'avatar'
    @ui.table.selectWith 'firstName'
    @ui.table.selectWith 'lastName'
    username: string

    @ui.table.hidden
    avatar: string

    @ui.table.hidden
    firstName: string

    @ui.table.hidden
    lastName: string
}
```

The `identity` cell now reads `avatar` / `firstName` / `lastName`
straight off `row`:

```vue
<!-- cells/IdentityCell.vue -->
<script setup lang="ts">
import { computed } from "vue";
import { getCellValue } from "@atscript/vue-table";
import type { ColumnDef } from "@atscript/ui";

const props = defineProps<{
  row: Record<string, unknown>;
  column: ColumnDef;
}>();

const avatar = computed(() => getCellValue(props.row, "avatar"));
const name = computed(
  () => `${getCellValue(props.row, "firstName")} ${getCellValue(props.row, "lastName")}`,
);
</script>

<template>
  <td>
    <img :src="String(avatar)" class="as-identity-avatar" alt="" />
    <span>{{ name }}</span>
  </td>
</template>
```

The deps are harvested from the visible columns: they ride **only**
while `username` is displayed, and disappear if the user toggles that
column off. The `@ui.table.hidden` keeps `avatar` / `firstName` /
`lastName` from showing as their own columns — `@ui.table.selectWith`
is what makes them ride in the payload.

### Headless renderers — `alwaysSelected`

When you skip `ColumnDef` entirely — a fully custom renderer built on
`<AsTableRoot>`'s default slot — there's no column to hang
`@ui.table.selectWith` on. Use the table-level `alwaysSelected` prop to
add leaf paths to `$select` unconditionally, regardless of which
columns are visible:

```vue
<AsTableRoot url="/db/users" :always-selected="['avatar', 'firstName', 'lastName']">
  <template #default="{ results }">
    <article v-for="row in results" :key="String(row.id)" class="as-user-card">
      <img :src="String(row.avatar)" alt="" />
      <span>{{ row.firstName }} {{ row.lastName }}</span>
    </article>
  </template>
</AsTableRoot>
```

`alwaysSelected` is additive — it only unions extra paths into the
projection; it never restricts or removes anything. (Same option is
available on `useTable()`'s query options.)

### DOs and DON'Ts

- **DO** co-locate per-column deps with `@ui.table.selectWith` — they
  ride exactly when the owning column is visible.
- **DO** reach for `alwaysSelected` when a headless / default-slot
  renderer needs fields unconditionally, with no column to attach deps
  to.
- **DON'T** use either for a number cell's currency or unit sibling
  (`@db.amount.currency.ref` / `@db.unit.ref`). moost-db already
  includes those server-side whenever the amount is projected — they
  ride for free.
- **DON'T** expect the extra fields to surface as columns, appear in the
  config dialog, or ride while the owning column is hidden. Need them
  unconditionally? Use `alwaysSelected`.

Both sources degrade gracefully: a declared dep that the (possibly
access-narrowed) metadata doesn't expose — e.g. a field removed by
server-side access control for the current user — is silently dropped
rather than requested, so projecting a field the user can't see never
errors.

See the [Annotations Reference](/tables/annotations) for the
`@ui.table.selectWith` row and [@atscript/vue-table](/api/vue-table)
for the `alwaysSelected` prop signature.

## Next steps

- [Cells](/tables/cells) — the built-in cell library and locale
  provider.
- [Customization](/tables/customization) — swap dialogs, headers,
  row actions, the column menu.


---
URL: "ui.atscript.dev/tables/customization"
LLMS_URL: "ui.atscript.dev/tables/customization.md"
outline: "deep"
---

# Customization

Three layers of override, from coarse to fine:

1. **Slot** — replace one cell or one header on one table.
2. **`:types`** — replace every cell of one cell type for one
   table.
3. **`:components`** + `@ui.table.component` — replace one named
   cell, reusable across tables.
4. **`:controls`** — replace dialogs, header chrome, row-action
   menu, column menu, preset picker.

Slots are fast and local. Maps are reusable and apply per-table.
Pick the smallest layer that does the job.

## Slots

`<AsTable>` exposes per-column slots plus a handful of globals:

| Slot                | Payload                  | Renders                            |
| ------------------- | ------------------------ | ---------------------------------- |
| `#header-<colPath>` | `{ column }`             | The `<th>` for that column         |
| `#cell-<colPath>`   | `{ value, row, column }` | The `<td>` for that column         |
| `#empty`            | —                        | Body when results are empty        |
| `#query-loading`    | —                        | Overlay while a query is in flight |
| `#error`            | `{ error }`              | Body when the last query failed    |
| `#last-row`         | —                        | Pseudo-row after the last data row |

```vue
<AsTable>
  <template #header-name="{ column }">
    <th class="min-w-[15em]">
      <span class="scope-primary font-700 text-current-hl">{{ column.label }}</span>
    </th>
  </template>

  <template #cell-price="{ value }">
    <td class="text-right tabular-nums">${{ Number(value).toFixed(2) }}</td>
  </template>

  <template #empty>
    <div class="p-$xxl text-center text-current/60">
      <p class="text-body-l mb-$s">No rows</p>
      <p class="text-body">Try adjusting your filters</p>
    </div>
  </template>

  <template #error="{ error }">
    <div class="scope-error p-$xxl text-center text-current-hl">
      <p class="font-600">Something went wrong</p>
      <p class="mt-$xs">{{ error.message }}</p>
    </div>
  </template>
</AsTable>
```

`<AsTableRoot>` exposes additional top-level slots — its default
`v-slot` receives the full table-state surface so the page chrome
(toolbar, pagination, filter bar) reads from one source: `tableDef`,
`loadingMetadata`, `metadataError`, `allColumns`, `columnNames`,
`columnWidths`, `columns`, `filterFields`, `filters`, `sorters`,
`results`, `querying`, `queryingNext`, `totalCount`, `loadedCount`,
`pagination`, `queryError`, `mustRefresh`, `searchTerm`, `selectedRows`,
`selectedCount`, `navBridge`, `query`, `queryNext`, `resetFilters`,
`showConfigDialog`, `openFilterDialog`, `closeFilterDialog`,
`setFieldFilter`, `removeFieldFilter`, `addFilterField`,
`removeFilterField`, `actions`, `prompt`.

## Cell-type map (`:types`)

Replace whole categories per table. The map is keyed by column
`type` (`text`, `number`, `date`, …). Use
`createDefaultCellTypes()` for a fresh seeded map and spread to
override:

```ts
import { createDefaultCellTypes } from "@atscript/vue-table";
import MyDateCell from "./cells/MyDateCell.vue";

const types = {
  ...createDefaultCellTypes(),
  date: MyDateCell,
  datetime: MyDateCell,
};
```

```vue
<AsTableRoot :types="types" url="/db/orders" />
```

The TS type is `TAsCellTypeComponents`. See [Custom Cells](/tables/custom-cells)
for the per-cell contract.

## Named cell (`:components`)

Tag a column with `@ui.table.component "name"` and pass the
component in the `:components` map:

```atscript
@ui.table.component 'statusBadge'
status: 'open' | 'shipped' | 'cancelled'
```

```ts
const components = { statusBadge: StatusBadgeCell };
```

Named wins over type-map; useful when only one column wants a
different renderer.

## Controls map (`:controls`)

The chrome map. Replace any of the table's Tier-2 dialogs / header
parts / row action menu. Pass **only the entries you replace** — every
slot falls back to its built-in internally, so spreading
`createDefaultControls()` is redundant and statically bundles (and
eager-mounts) the dialogs you didn't touch:

```ts
import MyConfigDialog from "./MyConfigDialog.vue";
import MyRowActions from "./MyRowActions.vue";

const controls = {
  configDialog: MyConfigDialog,
  rowActions: MyRowActions,
};
```

```vue
<AsTableRoot :controls="controls" url="/db/orders" />
```

The full `TAsTableControls` shape:

| Key                | Default             | Purpose                                    |
| ------------------ | ------------------- | ------------------------------------------ |
| `headerCell`       | `AsTableHeaderCell` | One `<th>` per column                      |
| `columnMenu`       | `AsColumnMenu`      | Dropdown menu on column headers            |
| `rowActions`       | `AsRowActions`      | Per-row action button / dropdown           |
| `filterInput`      | `AsFilterInput`     | Editable filter pill in the filter bar     |
| `filterDialog`     | `AsFilterDialog`    | Per-column filter dialog                   |
| `filterField`      | `AsFilterField`     | One filter field row inside the filter bar |
| `filterValueHelp`  | (lazy)              | Value-help dialog (`?` lookups)            |
| `configDialog`     | `AsConfigDialog`    | Three-tab settings dialog                  |
| `fieldsSelector`   | (lazy)              | Inner column / filter list                 |
| `sortersConfig`    | (lazy)              | Inner sorters list                         |
| `confirmDialog`    | `AsConfirmDialog`   | In-app `state.prompt()` dialog             |
| `actionFormDialog` | (lazy)              | Wraps `<AsForm>` for `@InputForm` actions  |
| `presetDialog`     | `AsPresetDialog`    | Rename / delete / publish / favorite       |

The preset **picker** is not a control — `<AsPresetPicker>` is a
Tier-1 component you mount (or don't) in your own toolbar markup.

The table root bundles and mounts the dialogs lazily — only when
needed (the dialog first opens, an action declares an `@InputForm`, a
filter input opens a value-help, etc.). Supplying a dialog in
`controls` opts it into **eager** bundling and mounting, so pass only
the dialogs you actually replace. The same applies if you want to
eager-load a built-in dialog deliberately:

```ts
import AsActionFormDialog from "@atscript/vue-table/as-action-form-dialog";

const controls = { actionFormDialog: AsActionFormDialog };
```

`AsActionFormDialog` pulls in the full `@atscript/vue-form` runtime,
so the main entry doesn't export it — import the dedicated subpath
above when you need to override or eager-load.

::: tip Bundle impact
Lazy controls download on first open; assigning any `controls.X` makes
that dialog eager. After replacing a default, shed its now-unused styles
with `excludeComponents` — see [Bundle Optimization](/guide/bundle-optimization).
:::

## Worked example: design-system row actions

A common need: the project's design system has its own buttons,
icons, and dropdown menu chrome. We swap `rowActions` while letting
the table own the action invocation.

```vue
<!-- DesignSystemRowActions.vue -->
<script setup lang="ts">
import { computed } from "vue";
import { useTableContext } from "@atscript/vue-table";
import type { TVueTableActionInfo } from "@atscript/vue-table";
import { DsButton, DsMenu, DsMenuItem } from "@my-org/design-system";

const props = defineProps<{
  row: Record<string, unknown>;
  column: { type: "__actions" };
}>();

const { state } = useTableContext();
const actions = computed(() => state.actions.cellRow);

function onClick(action: TVueTableActionInfo) {
  void state.actions.invoke(action, { id: props.row.id });
}
</script>

<template>
  <td>
    <DsButton
      v-if="actions.length === 1"
      :icon="actions[0].icon"
      :label="actions[0].label"
      @click="onClick(actions[0])"
    />
    <DsMenu v-else trigger-icon="more-vertical">
      <DsMenuItem
        v-for="action in actions"
        :key="action.name"
        :icon="action.icon"
        :label="action.label"
        :destructive="action.intent === 'destructive'"
        @select="onClick(action)"
      />
    </DsMenu>
  </td>
</template>
```

```ts
const controls = { rowActions: DesignSystemRowActions };
```

`state.actions.cellRow` is the pre-flattened, per-row action list
(`[default?, ...others.row, ...rows]`) — every row reads the same
array, so the composable does the slicing once per table-def
change. `state.actions.invoke()` returns the discriminated
`ActionResult`; the table's `@action` emit fires after invoke
resolves so the page chrome can toast.

The default `AsRowActions` does the same thing with vunor's
`c8-*` button primitives and reka-ui's dropdown. The swap above replaces only the
chrome — the table's reactivity, confirm dialog, input form
dialog, and `@action` emit all keep working.

## Next steps

- [Cells](/tables/cells) — the built-in cell library.
- [Config Dialog](/tables/config-dialog) — anatomy of the
  three-tab settings dialog.
- [Actions & Selection](/tables/actions) — the underlying action
  model.


---
URL: "ui.atscript.dev/tables/edit-form-occ"
LLMS_URL: "ui.atscript.dev/tables/edit-form-occ.md"
outline: "deep"
---

# Edit forms with optimistic concurrency

When a row can be edited from more than one place at the same time, a naive
"load, edit, save" flow is unsafe: whoever saves second silently overwrites
the first writer's changes. Atscript-ui integrates with `@atscript/db`'s
optimistic concurrency control (OCC) so this surfaces as a clear UX prompt
instead of a silent data loss.

The whole flow is three pieces:

1. Your `.as` schema opts the table into OCC.
2. Your form passes `meta.versionColumn` to `createFormDef` so the version
   field doesn't render as an editable input.
3. Your submit handler catches `VersionMismatchError` from
   `@atscript/db-client` and shows the user a friendly "row changed,
   reload" message.

## 1. Opt the table into OCC

Annotate one `number.int` field with `@db.column.version`:

```atscript
@db.table 'products'
export interface ProductsTable {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Name'
    name: string

    /// other fields…

    @meta.label 'Version'
    @db.column.version
    version: number.int
}
```

The SQL adapter auto-creates the column with `NOT NULL DEFAULT 0` on schema
sync, so existing rows backfill to version `0` automatically — no migration
script needed. Every successful update increments it.

Your `/meta` response now carries:

```json
{
  "versionColumn": "version",
  "fields": { "id": {}, "name": {}, "version": {} }
}
```

The version field still appears in `meta.fields` like any other column — the
server doesn't add a hidden/readonly flag. Hiding it is the UI's job, which
is exactly what `createFormDef`'s opt is for.

## 2. Hide the version field from the form

Pass `meta.versionColumn` to `createFormDef`:

```ts
import { createFormDef } from "@atscript/ui";
import { deserializeAnnotatedType } from "@atscript/typescript/utils";

const meta = await client.meta();
const formDef = createFormDef(deserializeAnnotatedType(meta.type), {
  versionColumn: meta.versionColumn,
});
```

`AsForm` iterates `def.fields[]` and the version prop is no longer there,
so no input is painted. But the version value still lives on the loaded
row (`formData.value.version`), so when the user hits submit the PATCH
body still carries it — exactly what the server needs to lift into
`$cas`.

`createTableDef` does the same thing on the table side: the version
column never appears in column-picker dialogs, filter dialogs, or sort
dialogs — nothing to configure.

## 3. Handle the 409 on submit

`@atscript/db-client` exports `VersionMismatchError` (a subclass of
`ClientError`). When the server detects a stale write, the client
auto-throws this typed marker with a `currentVersion` accessor:

```ts
import { VersionMismatchError } from "@atscript/db-client";

async function onSubmit(data: unknown) {
  try {
    await client.update(data as never);
    showToast("Saved");
  } catch (e) {
    if (e instanceof VersionMismatchError) {
      showError(
        `Row changed since you opened the form (current version: ` +
          `${e.currentVersion}). Reload the page to continue.`,
      );
    } else {
      throw e;
    }
  }
}
```

The simplest UX is the one shown here: tell the user the row changed and
let them reload. More sophisticated flows (auto-refresh + diff prompt,
retry with re-applied user edits) are possible but easy to get wrong —
pick the plain "reload" path unless you have a specific reason to do
more.

## Putting it together

A complete edit-page wiring loads a row, builds the form def with
`versionColumn`, and discriminates on `VersionMismatchError` at submit:

```vue
<script setup lang="ts">
import { ref, watch } from "vue";
import { AsForm } from "@atscript/vue-form";
import { createFormDef, type FormDef } from "@atscript/ui";
import { deserializeAnnotatedType } from "@atscript/typescript/utils";
import { VersionMismatchError, Client } from "@atscript/db-client";

const props = defineProps<{ url: string; id: string | number }>();

const client = new Client(props.url);
const formDef = ref<FormDef | null>(null);
const record = ref<Record<string, unknown> | null>(null);
const error = ref<string | null>(null);

async function load() {
  const meta = await client.meta();
  formDef.value = createFormDef(deserializeAnnotatedType(meta.type), {
    versionColumn: meta.versionColumn,
  });
  record.value = (await client.one(props.id as never)) as Record<string, unknown>;
}
watch(() => [props.url, props.id], load, { immediate: true });

async function onSubmit(data: unknown) {
  try {
    await client.update(data as never);
  } catch (e) {
    if (e instanceof VersionMismatchError) {
      error.value =
        `Row changed since you opened the form ` +
        `(current version: ${e.currentVersion}). Reload to continue.`;
    } else {
      throw e;
    }
  }
}
</script>

<template>
  <p v-if="error" class="scope-error">{{ error }}</p>
  <AsForm
    v-if="formDef && record"
    :def="formDef"
    :form-data="{ value: record }"
    :types="types"
    @submit="onSubmit"
  />
</template>
```

## Related

- atscript-db's optimistic concurrency reference — the database-side
  mechanics (`$cas`, version column, schema sync, adapter notes).
- [Tables: Config Dialog](/tables/config-dialog) — confirms version
  columns never appear in column/filter/sort dialogs.
- [API: `@atscript/ui` core](/api/ui) — `MetaResponse.versionColumn`,
  `TableDef.versionColumn`, `createFormDef(type, opts)` signatures.


---
URL: "ui.atscript.dev/tables/filtering"
LLMS_URL: "ui.atscript.dev/tables/filtering.md"
outline: "deep"
---

# Filtering

The filter model is plain data. Mutators are pure — they touch exactly
one entity — and the watcher at the table root translates state changes
into a fresh query. This means dialogs, custom toolbars, external
`v-model`s and devtools all use the same surface.

## The filter model

The model lives at `state.filters`:

```typescript
type FieldFilters = Record<string, FilterCondition[]>;

interface FilterCondition {
  type: FilterConditionType;
  value: (string | number | boolean)[];
}

type FilterConditionType =
  | "eq"
  | "ne"
  | "gt"
  | "gte"
  | "lt"
  | "lte"
  | "contains"
  | "starts"
  | "ends"
  | "bw" // between (value[0]..value[1])
  | "null"
  | "notNull"
  | "regex";
```

A `FieldFilters` map can hold multiple conditions per field. Most
condition types use `value[0]`; `bw` uses `value[0]` (low) and
`value[1]` (high); `null` and `notNull` ignore the value.

### Combination rules

`filtersToUniqueryFilter` (in `@atscript/ui-table`) is the authoritative
translation:

- **Per field — inclusion conditions are OR-ed.** `eq`, `gt`, `gte`,
  `lt`, `lte`, `contains`, `starts`, `ends`, `bw`, `null`, `regex` are
  inclusive: any one matching counts.
- **Per field — exclusion conditions are AND-ed.** `ne` and `notNull`
  are exclusive: every one must hold.
- **Across fields — AND.** Every field group is AND-ed at the top
  level.

```typescript
// state.filters
{
  status: [
    { type: "eq", value: ["paid"] },
    { type: "eq", value: ["draft"] },
  ],
  amount: [
    { type: "gt", value: [100] },
  ],
}

// → Uniquery filter
{
  $and: [
    { $or: [{ status: "paid" }, { status: "draft" }] },
    { amount: { $gt: 100 } },
  ]
}
```

::: details Condition types and their Uniquery shape
| UI condition | Uniquery emission |
| ------------ | ----------------- |
| `eq` | `{ field: value }` |
| `ne` | `{ field: { $ne: value } }` |
| `gt`/`gte`/`lt`/`lte` | `{ field: { $gt: value } }` (etc.) |
| `contains` | `{ field: { $regex: "/<value>/i" } }` (escaped) |
| `starts` | `{ field: { $regex: "/^<value>/i" } }` |
| `ends` | `{ field: { $regex: "/<value>$/i" } }` |
| `bw` | `{ field: { $gte: lo, $lte: hi } }` |
| `null` | `{ field: { $exists: false } }` |
| `notNull` | `{ field: { $exists: true } }` |
| `regex` | `{ field: { $regex: <value> } }` |
:::

## Display state vs applied state

Two independent arrays drive filtering:

- **`state.filterFields: string[]`** — display state. Which filter
  inputs are currently shown in the filter bar.
- **`state.filters: FieldFilters`** — applied state. The actual
  conditions sent to the server.

They are independent on purpose:

- Hiding an input (`removeFilterField(path)`) does **not** clear its
  value. The next time you re-show it, the previous filter is still
  applied.
- Clearing a value (`removeFieldFilter(path)`) does **not** hide the
  input. The empty filter row stays in the bar so the user can re-type.

This is a hard rule of the model contract — see the Mutators-are-pure
section in `CLAUDE.md`. Apply it to anything you add downstream.

## Components

### `<AsFilters>` — the filter bar

`<AsFilters>` reads `state.filterFields` and renders one
`<AsFilterField>` per entry. It accepts an optional `:filter-fields`
prop if you want to render a static subset; otherwise it tracks the
state.

```vue
<AsTableRoot url="/db/tables/products" v-slot="slot">
  <AsFilters />
  <AsTable />
</AsTableRoot>
```

### `<AsFilterField>` — one inline filter

The Tier-2 default for a single inline filter chip / input. Reads
`column.type` and `column.options` to pick the right input shape
(text, number, date range, value-help typeahead, …). Calls
`state.setFieldFilter(path, conditions)` on change.

### `<AsFilterDialog>` — per-column condition builder

Mounted automatically by `<AsTableRoot>`. Opens when the user picks
_Filter_ from a column-menu, or when you call
`state.openFilterDialog(column)` directly. Lets the user compose
multiple conditions per column (e.g. `> 100` AND `<= 1000`) and pick
operators from the full `FilterConditionType` palette. The dialog
respects `column.nullable` — `null` / `notNull` are hidden for
non-nullable columns.

Override it via `:controls.filterDialog` (pass only the override —
other slots fall back to their built-ins):

```ts
import MyFilterDialog from "./MyFilterDialog.vue";

const controls = { filterDialog: MyFilterDialog };
```

### Value-help filters

When a column has `valueHelpInfo` (because the field carries
`@db.rel.FK`), the filter dialog mounts `AsFilterValueHelp` — a mini
table or typeahead that lets the user pick FK targets by their
`@ui.dict.label`. The picker queries the referenced table's value-help
endpoint with the columns flagged `@ui.dict.filterable` /
`@ui.dict.sortable` / `@ui.dict.searchable`.

The resulting filter is a plain `eq` (or `OR` of `eq`s) on the FK
column — no special wire shape; the value-help is purely a UI affordance.

## Programmatic filters

### Set an initial filter

Initial filters flow through whichever channel makes sense:

- **`v-model:filter-fields`** — control which filter inputs are
  displayed.
- **`v-model:url-query`** — let users bookmark filter state via the
  URL bridge.
- **`:force-filters`** — a `FilterExpr` that's AND-merged on top of the
  user's filters (and survives `state.resetFilters()`).

For one-off programmatic application from the parent component:

```vue
<AsTableRoot url="/db/tables/orders" ref="root" v-slot="{ setFieldFilter }">
  <button @click="setFieldFilter('status', [{ type: 'eq', value: ['open'] }])">
    Show open orders
  </button>
  <AsTable />
</AsTableRoot>
```

`setFieldFilter` writes to `state.filters` only. If you also want the
chip visible in `<AsFilters>`, call `addFilterField('status')`.

### Read current filters

The slot props on `<AsTableRoot>` expose `filters` directly. Inside the
default slot's scope they're already unwrapped from the ref. From
outside the slot, use the exposed `state`:

```ts
const root = ref<InstanceType<typeof AsTableRoot> | null>(null);
// ...
const currentFilters = root.value?.state.filters.value;
```

### `state.resetFilters()`

Clears every entry from `state.filters`. Does NOT touch
`state.filterFields` — the empty input rows remain visible, ready for
the next keystroke.

## `filtersToUniqueryFilter` directly

The translation is a pure function, exported from `@atscript/ui-table`:

```ts
import { filtersToUniqueryFilter } from "@atscript/ui-table";

const filter = filtersToUniqueryFilter({
  status: [{ type: "eq", value: ["paid"] }],
  amount: [{ type: "gt", value: [100] }],
});
// → { $and: [{ status: "paid" }, { amount: { $gt: 100 } }] }
```

Useful when you're piping filters into a non-table query (e.g. an
export endpoint) or wiring `forceFilters` from elsewhere in your app.

The inverse — `uniqueryFilterToFieldFilters` — is also exported, and
powers the URL-state bridge's hydration step. See
[URL State](/tables/url-state).

## Next steps

- [Sorting](/tables/sorting) — multi-sort and force-sort semantics.
- [URL State](/tables/url-state) — shareable filter URLs.
- [Annotations Reference](/tables/annotations) — how `@db.index.*`
  drives `meta.fields[*].filterable` and what flips operator
  availability.


---
URL: "ui.atscript.dev/tables/hello-world"
LLMS_URL: "ui.atscript.dev/tables/hello-world.md"
outline: "deep"
---

# Hello World

The shortest path from a `.as` type to a working, server-driven table.
You write the schema once; the server exposes it; the client mounts two
components. No column definitions, no row mappers, no AJAX glue.

::: info Prerequisites
This guide assumes you have a moost-db backend serving the `/meta` +
CRUD HTTP surface for an `.as` table. If you don't, jump to
[Query Function](/tables/query-function) for the custom `queryFn`
escape hatch — it lets you skip moost-db entirely.
:::

## 1. Define the schema

```atscript
// src/schemas/Product.as
@db.table 'products'
export interface ProductsTable {
    @meta.id
    @db.default.increment
    id: number

    @meta.label 'Product Name'
    @db.index.fulltext 'products_search'
    name: string

    @meta.label 'Description'
    @db.index.fulltext 'products_search'
    description?: string

    @meta.label 'Price'
    price: number

    @meta.label 'In Stock'
    @db.default 'true'
    inStock: boolean

    @meta.label 'Category'
    @db.index.plain 'category_idx'
    category: 'electronics' | 'clothing' | 'food' | 'books' | 'toys' | 'other'

    @meta.label 'SKU'
    @db.index.unique 'sku_idx'
    sku: string

    @meta.label 'Created'
    @db.default.now
    createdAt: number
}
```

A handful of annotations carry a lot of weight here:

- `@meta.id` — primary key. Surfaces in `/meta.primaryKeys`, drives row
  addressing for actions and `__remove`.
- `@meta.label` — column header text. Falls back to a humanised path
  when omitted.
- `@db.index.fulltext` — server-side `$search` index. Makes the table
  searchable (`tableDef.searchable === true`); the search box wires up
  automatically.
- `@db.index.plain` / `@db.index.unique` — flag the column as
  `filterable` / `sortable` in `/meta.fields[*]`, which in turn enables
  the column menu's filter and sort entries.
- The `'electronics' | 'clothing' | …` literal union becomes a
  preset list of options for the filter dialog without any extra
  wiring.

See [Annotations Reference](/tables/annotations) for the complete list.

## 2. Expose it

With moost-db wired up, the same `.as` file becomes a REST endpoint via
`@db.http.path` (or via your moost-db routing). For the example below
we assume `/db/tables/products` resolves to the standard
`AsDbReadableController` (`/meta`, `/q`, CRUD, actions, value-help).

::: tip
moost-db is documented in detail at
[db.atscript.dev — HTTP CRUD](https://db.atscript.dev/http/crud).
:::

If you don't run moost-db, see
[Query Function — Path B](/tables/query-function#path-b-custom-queryfn).

## 3. Mount the table

```vue
<script setup lang="ts">
import { AsTableRoot, AsTable, createDefaultCellTypes } from "@atscript/vue-table";
import TableToolbar from "../../components/TableToolbar.vue";
import TableFilterBar from "../../components/TableFilterBar.vue";
import TablePagination from "../../components/TablePagination.vue";

const types = createDefaultCellTypes();
</script>

<template>
  <div class="table-page">
    <AsTableRoot
      url="/db/tables/products"
      :types="types"
      :limit="10"
      v-slot="{ tableDef, loadedCount, totalCount, loadingMetadata }"
    >
      <TableToolbar
        title="Products"
        :table-def="tableDef"
        :loaded-count="loadedCount"
        :total-count="totalCount"
      />
      <div class="table-page-filters">
        <TableFilterBar />
      </div>
      <div class="table-page-body">
        <AsTable :column-menu="{ sort: true, filters: true, hide: true, resetWidth: true }" />
        <div v-if="loadingMetadata" class="table-loading-overlay" />
      </div>
      <TablePagination mode="pagination" />
    </AsTableRoot>
  </div>
</template>
```

That's the whole client.

## Anatomy of the mount

### `<AsTableRoot>` — the renderless orchestrator

`AsTableRoot` doesn't render any chrome of its own. It fetches `/meta`,
builds the `TableDef`, owns reactive state and exposes everything via a
slot. Key props:

| Prop           | Purpose                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`          | The data endpoint. moost-db serves `/meta` and `/q` (paged data) under the same path.                                                                                   |
| `limit`        | Default page size. Also the block size for `<AsWindowTable>` fetches.                                                                                                   |
| `types`        | Cell-type → component dispatch map. Seed with `createDefaultCellTypes()`, override entries as you go.                                                                   |
| `components`   | Named component overrides looked up via `@ui.table.component "name"`.                                                                                                   |
| `controls`     | Skin-slot overrides — header cell, column menu, filter dialog, config dialog, etc. Pass only the entries you replace; every slot falls back to its built-in internally. |
| `queryFn`      | Replace the built-in moost-db data fetcher with your own. See [Query Function](/tables/query-function).                                                                 |
| `forceFilters` | Always-applied `FilterExpr` (Uniquery shape), AND-merged with user filters.                                                                                             |
| `forceSorters` | Always-applied `SortControl[]`, prepended before user sorters; user can't remove them.                                                                                  |
| `preset`       | Opt-in preset configuration. Omit to disable presets.                                                                                                                   |
| `queryOnMount` | Default `true`. Set `false` if you want to defer the first fetch.                                                                                                       |

The default slot exposes the full reactive state — `tableDef`,
`allColumns`, `columns`, `columnNames`, `columnWidths`,
`filterFields`, `filters`, `sorters`, `results`, `pagination`,
`searchTerm`, `selectedRows`, `selectedCount`, `totalCount`,
`loadedCount`, plus the loading/error flags (`querying`,
`queryingNext`, `loadingMetadata`, `queryError`, `metadataError`,
`mustRefresh`), the keyboard nav bridge (`navBridge`), and the
public methods (`query`, `queryNext`, `resetFilters`,
`showConfigDialog`, `openFilterDialog`, `closeFilterDialog`,
`setFieldFilter`, `removeFieldFilter`, `addFilterField`,
`removeFilterField`, `actions`, `prompt`). External `v-model`s are
supported for `filterFields`, `columnNames`, `columnWidths`,
`sorters`, `selectedRows` and the URL bridge `urlQuery`.

Underneath, `<AsTableRoot>` also mounts its companion dialogs
(`AsFilterDialog`, `AsConfigDialog`, `AsConfirmDialog`, and lazily
`AsActionFormDialog` when actions carry `@InputForm` payloads) so
column-menu and row-action flows work without any extra wiring on
your side.

### `<AsTable>` — the renderer

`<AsTable>` injects the root context and renders the actual `<table>`.
It accepts presentational props only: `:stickyHeader`, `:select`
(selection mode), `:rowActionsColumn` (insert a synthesised actions
column), `:columnMenu` (which entries to show in the header dropdown),
`:reorderable`, `:resizable`, `:columnMinWidth`. State props
(`:rows`, `:columns`) are escape hatches — by default it reads
`state.results` and `state.columns` straight from the context.

`<AsWindowTable>` is the virtualised twin. Same context, different
renderer — see [Pagination & Virtualization](/tables/pagination).

### `createDefaultCellTypes()` and `:controls`

`createDefaultCellTypes()` returns a fresh cell-type map you can spread
to extend or override. For `:controls`, pass only the entries you
replace — every chrome slot falls back to its built-in internally, so
spreading defaults is redundant (and opts the lazy dialogs into eager
bundling):

```ts
import { createDefaultCellTypes, AsTableCellValue } from "@atscript/vue-table";
import StatusBadgeCell from "./StatusBadgeCell.vue";
import MyFilterDialog from "./MyFilterDialog.vue";

const components = {
  status: StatusBadgeCell, // matches @ui.table.component 'status'
};

const controls = {
  filterDialog: MyFilterDialog, // only the overrides — no spreading defaults
};
```

The default cell-type map:

| Cell type   | Default component  |
| ----------- | ------------------ |
| `text`      | `AsTableCellValue` |
| `number`    | `AsCellNumber`     |
| `boolean`   | `AsTableCellValue` |
| `date`      | `AsCellDate`       |
| `datetime`  | `AsCellDate`       |
| `relative`  | `AsCellDate`       |
| `array`     | `AsCellArray`      |
| `object`    | `AsCellJson`       |
| `union`     | `AsCellUnion`      |
| `enum`      | `AsTableCellValue` |
| `ref`       | `AsTableCellValue` |
| `__actions` | `AsRowActions`     |

## Next steps

- [Annotations Reference](/tables/annotations) — every annotation the
  table reads.
- [Query Function](/tables/query-function) — non-moost backends and
  force filters.
- [Filtering](/tables/filtering) — the filter bar, value-help, and how
  filters become Uniquery.


---
URL: "ui.atscript.dev/tables/pagination"
LLMS_URL: "ui.atscript.dev/tables/pagination.md"
outline: "deep"
---

# Pagination & Virtualization

`vue-table` ships two renderers that share the same `<AsTableRoot>`
context: classic page-by-page `<AsTable>`, and the virtualised
`<AsWindowTable>` that streams blocks as the user scrolls. The state
contract is identical — only the chrome and the fetch strategy differ.

## Choosing a mode

|                            | `<AsTable>` (paginated)                             | `<AsWindowTable>` (virtual)                                |
| -------------------------- | --------------------------------------------------- | ---------------------------------------------------------- |
| Row count it scales to     | hundreds to low thousands per page                  | tens of thousands or unbounded                             |
| Visible rows               | the whole page is in the DOM                        | only the viewport window (+ overscan)                      |
| Fetch unit                 | one page at a time                                  | block-aligned slices of `:limit` rows                      |
| Pagination control         | external (you pair `state.pagination`)              | none — scroll is the controller                            |
| Best for                   | CRUD admin, value-help, lists you act on row-by-row | logs, ledgers, analytics drilldowns, infinite-scroll feels |
| Mounts the loading overlay | yes (`querying`)                                    | yes (`querying`) + per-row skeleton (`windowLoading`)      |

If you're not sure, start with `<AsTable>`. Swap to `<AsWindowTable>`
once you actually hit row counts where loading every page is wasteful.

## `<AsTable>` — paginated

The renderer itself doesn't draw the pagination control — you pair it
with whatever UI you like, bound to `state.pagination`.

```vue
<AsTableRoot url="/db/tables/products" :limit="10" v-slot="slot">
  <AsTable :column-menu="{ sort: true, filters: true, hide: true, resetWidth: true }" />
  <TablePagination mode="pagination" />
</AsTableRoot>
```

`state.pagination` is a `Ref<PaginationControl>`:

```typescript
interface PaginationControl {
  page: number; // 1-based
  itemsPerPage: number;
}
```

Writing to it triggers the root watcher; a new query fires
automatically. Filter / sort / search changes reset
`state.pagination.page` back to 1 (debounced ~500ms for filters so the
user can type freely before the page reset costs them a re-fetch).

::: details Build your own pagination
A `TablePagination.vue` that wraps Reka UI's `PaginationRoot` +
page-size selector is a one-pager:

```vue
const currentPage = computed({ get: () => state.pagination.value.page, set: (page) => {
state.pagination.value = { ...state.pagination.value, page }; }, });
```

Use any pagination component; you only need to write to
`state.pagination.value`.
:::

The `<AsTable>` renderer accepts presentational props for the chrome:

- **`:select="multi"`** — render a leading checkbox column. The full
  multi-select wire (`Space`, `Shift+click`, `select all` from
  `<AsTableActions>`) is automatic.
- **`:rowActionsColumn="first" | "last" | "merge-select"`** — synthesise
  a locked `__actions` pseudo-column from `state.actions.row`. See
  [Actions & Selection](/tables/actions).
- **`:columnMenu="{ sort, filters, hide, resetWidth }"`** — toggle each
  entry of the header dropdown.
- **`:reorderable`** / **`:resizable`** — column drag and resize. Default
  `true`.
- **`:rowDelete`** — opt into the synthesised `__remove` action. Only
  surfaces when `tableDef.canRemove === true`.

## `<AsWindowTable>` — virtualised

Same root, different renderer. A windowed table view typically looks
like this:

```vue
<script setup lang="ts">
import { AsTableRoot, AsTable, createDefaultCellTypes } from "@atscript/vue-table";
import TableToolbar from "../../components/TableToolbar.vue";
import TableFilterBar from "../../components/TableFilterBar.vue";

const types = createDefaultCellTypes();
</script>

<template>
  <div class="table-page">
    <AsTableRoot
      url="/db/tables/products"
      :types="types"
      :limit="5000"
      v-slot="{ tableDef, loadedCount, totalCount, loadingMetadata }"
    >
      <TableToolbar
        title="Virtual Scroll — 5,000 Products"
        :table-def="tableDef"
        :loaded-count="loadedCount"
        :total-count="totalCount"
      />
      <div class="table-page-filters">
        <TableFilterBar />
      </div>
      <div class="table-page-body">
        <AsTable sticky-header :virtual-row-height="36" :virtual-overscan="10" />
        <div v-if="loadingMetadata" class="table-loading-overlay" />
      </div>
    </AsTableRoot>
  </div>
</template>
```

Notice the example uses `<AsTable>` with `:virtual-row-height` set —
that's the `<AsTable>` path doing TanStack-Vue-Virtual rendering when a
row height is provided. For the dedicated windowed renderer with
block-aligned scroll-driven fetches, use `<AsWindowTable>`:

```vue
<AsTableRoot url="/db/tables/big_logs" :limit="200" :block-size="200">
  <AsWindowTable :row-height="32" :min-rows="20" />
</AsTableRoot>
```

### How fetching works

`<AsWindowTable>` watches its viewport top and row count. When either
changes (after a debounce — `dragReleaseDebounceMs`, default 300ms),
the state computes the set of block-aligned slices needed to cover the
visible range and calls `state.loadRange(skip, limit)`:

- Blocks are aligned to multiples of `blockSize` (default `:limit`).
- Rows land in `state.windowCache: Map<absIdx, row>`.
- Block fetches in flight populate `state.windowLoading` — the per-row
  skeleton uses this for placeholder rendering.
- Successive viewport changes that already have cached rows DON'T
  refetch; the cache is the single source of truth until
  `state.invalidate()` is called.

`state.results` and `state.windowCache` share row references — when a
forward / backward scroll reveals contiguous already-loaded rows, the
state merges them into `results` so existing UI bindings stay stable.

### Tunables on `<AsWindowTable>`

| Prop              | Default                      | Purpose                                                                         |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------- |
| `:row-height`     | `DEFAULT_ROW_HEIGHT_PX` (32) | Fixed row height in pixels. Virtual scroll requires this.                       |
| `:rows`           | undefined                    | Force exactly N rows of height (overrides min/max).                             |
| `:min-rows`       | undefined                    | Floor; useful for value-help dialogs that should never collapse.                |
| `:max-rows`       | undefined                    | Cap; useful for embedded tables on dashboard cards.                             |
| `:select="multi"` | `"none"`                     | Multi-select checkbox column.                                                   |
| `:row-delete`     | `false`                      | Synthesised `__remove` action.                                                  |
| `:column-menu`    | (full set)                   | Column-menu entries.                                                            |
| `:enter-action`   | `"main-action"`              | `"toggle-select"` for value-help tables where Enter shouldn't fire main action. |

### Tunables on `<AsTableRoot>` for windowed mode

| Prop                        | Default | Purpose                                                                                    |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `:limit`                    | 25      | Default page size + block size for `loadRange`.                                            |
| `:block-size`               | 100     | Override the page-alignment unit independently of `:limit`.                                |
| `:drag-release-debounce-ms` | 300     | How long the viewport watcher waits after the user stops scrolling before issuing fetches. |

## State changes that invalidate

Both renderers share one rule: any change that affects the result set
re-queries from page 1 (paginated mode) or invalidates the window cache
and re-fetches the visible range (windowed mode):

- `state.filters` / `state.filterFields` (filter-change watcher,
  debounced 500ms).
- `state.sorters`.
- `state.searchTerm`.
- `state.columnNames` only when the underlying projection (`$select`)
  changes.

`state.pagination.itemsPerPage` change resets to page 1 as well.

`state.mustRefresh` flips to `true` when a state mutation lands while a
query is in flight — surfaces a "results are stale, refresh to apply"
indicator in toolbars. The next watcher tick will fire the refetch
automatically; the flag is there for UI.

## Manual refresh

`state.query()` is reserved for user-initiated refresh. Wire it to a
toolbar button or pull-to-refresh gesture:

```vue
<button :disabled="state.querying.value" @click="state.query">Refresh</button>
```

It's the contract for the table state machine: programmatic changes
(filters, sorters, pagination, column changes) re-fetch automatically
through internal watchers — you don't call `state.query()` to apply
them. If you find yourself reaching for it after a mutation, the
watcher is what you actually want.

## Next steps

- [URL State](/tables/url-state) — pagination is included in the URL
  bridge by default; you can opt it out per-aspect.
- [Actions & Selection](/tables/actions) — `state.selectedRows`
  survives a `selectionPersistence` policy across re-queries.
- [Cells](/tables/cells) — per-cell render cost is the main driver of
  windowed-mode performance; the defaults are tuned to be cheap.


---
URL: "ui.atscript.dev/tables/presets"
LLMS_URL: "ui.atscript.dev/tables/presets.md"
outline: "deep"
---

# Presets

Presets save a table view by name. The view is durable: a user can
build the perfect column / filter / sort combination, save it as
"My open orders", and recall it across reloads, devices, and
sessions. Public presets share the view across all users on the
same table.

The client side lives in `@atscript/vue-table`. The persistence
layer is `@atscript/moost-ui-presets` — see [Server-Side Presets](/tables/server-presets)
for the controller setup.

## The snapshot model

A preset is a partial `PresetSnapshot`:

```ts
interface PresetSnapshot {
  columns?: {
    columnNames: string[];
    columnWidths?: Record<string, string>;
  };
  filters?: string[]; // displayed filter field paths
  filterOps?: FieldFilters; // applied filter conditions
  sorters?: SortControl[];
  itemsPerPage?: number;
}
```

Every key is optional. A preset that names only `sorters` claims
only the sort aspect — on apply, the table writes new sorters and
leaves columns / filters / itemsPerPage untouched. This **per-aspect
opt-in** is the entire reason presets are useful: a "sort by
priority" preset doesn't fight a "show financial columns" preset.

Each aspect's presence on the snapshot is the claim that the
preset owns it. The wire form (`PresetSnapshotWire` with
entries-arrays for atscript validation) is converted via
`toWireSnapshot()` / `fromWireSnapshot()` from `@atscript/ui-table`.

## Three preset kinds

| Kind       | ID prefix | Persisted | Scope                |
| ---------- | --------- | --------- | -------------------- |
| **System** | `sys:`    | No        | Built into the app   |
| **User**   | (uuid)    | Yes       | One user, one table  |
| **Public** | (uuid)    | Yes       | All users, one table |

System presets are declared by the app, never round-trip to the
server, and always render in the picker at index 0 onwards. The
standard "All rows" entry is `STANDARD_PRESET_ID = 'sys:standard'`.

User presets are private to the creator. Public presets show in
every user's picker on the same `(app, tableKey)`. Public preset
labels are unique within `(app, tableKey)` — race-safe at the DB
layer via a unique index.

## User config (`userConf`)

Per-user, per-table preferences keyed deterministically as
`uc:${user}:${app}:${tableKey}`:

```ts
interface UserConfData {
  defaultPresetId?: string; // applied at first load
  favPresetIds?: string[]; // pinned in the picker
}
```

The userConf row is auto-stamped by the server when a write
arrives, and the client surfaces it as `state.preset.userConf`. Its
shape is exactly two fields, but they're load-bearing — `setDefault`
and `toggleFav` are atomic operations on this row.

## App config (`appConf`)

App-wide, one row per `(user, app)` — not per table. Carries
appearance, language, timezone, density, date format, custom JSON.
`useAppPrefs()` is the composable that owns it:

```ts
import { useAppPrefs, provideCellLocale } from "@atscript/vue-table";

const { prefs, save } = useAppPrefs({ url: "/api/db/_presets" });

provideCellLocale(() => ({
  language: prefs.value.language,
  timezone: prefs.value.timezone,
}));

await save({ appearance: "dark" }); // optimistic shallow merge
```

`save()` is optimistic: the local `prefs` updates immediately, the
server roundtrip happens in the background, and a failure rolls
back to the previous value.

## The Vue composables

### `usePresets(opts)`

Wraps `PresetsClient` (in ui-table) and exposes a reactive surface
— the same one mounted under `state.preset` when the table root is
configured with `:preset`. Direct use is for custom pickers; most
apps just pass the `preset` prop and let `<AsPresetPicker>` consume
`state.preset`.

```ts
const presets = usePresets({
  url: "/api/db/_presets",
  tableKey: "orders",
  systemPresets: [
    {
      id: "open",
      label: "Open",
      content: { filterOps: { status: [{ type: "eq", value: ["pending"] }] } },
    },
  ],
});
```

### `useLocalDraft(opts)`

Overlays in-progress edits on `localStorage`. The user fiddles with
filters, refreshes the tab, and the table opens in the same state.
The draft is per `(app, tableKey)`, debounced 300ms, and cleared
automatically when the live snapshot matches the active preset's
claimed aspects (so the URL bar stays clean once you're "done"
editing).

Wired automatically when `<AsTableRoot :preset="{ ..., persistDrafts: true }">`
is set; direct use is for headless setups.

### `useAppPrefs(opts)`

App-wide user prefs, as above. One round-trip on mount, optimistic
writes via `save()`, optional localStorage cache for cold paint
without a flash of defaults.

## The picker

`<AsPresetPicker>` is a Tier-1 component — a dropdown that lists
system + user + public presets, with **Save**, **Save as…**,
**Reset**, and **Manage…** actions. It reads `state.preset` so the
root has to be configured with `:preset`:

```vue
<AsTableRoot
  url="/api/db/tables/orders"
  :preset="{ url: '/api/db/_presets', tableKey: 'orders', systemPresets }"
>
  <AsTableActions>
    <AsPresetPicker />
  </AsTableActions>
  <AsTable />
</AsTableRoot>
```

When the picker is not configured (omit `:preset`), the preset
surface stays inert: `state.preset.available === false`, every
mutator throws, and the picker hides itself. This makes presets a
zero-cost opt-in.

## Date shortcuts

`dateShortcuts()` returns a fixed list of date-range presets useful
for `bw` (between) conditions: **Last 7 Days**, **Last 30 Days**,
**Month to Date**, **Last 90 Days**, **Last 6 Months**, **Last 12
Months**, **Year to Date**. The filter dialog's date input renders
them as quick-pick buttons.

```ts
import { dateShortcuts } from "@atscript/ui-table";

for (const sc of dateShortcuts()) {
  // { label: 'Last 7 Days', dates: ['2026-05-06', '2026-05-13'] }
}
```

Pass `dateShortcuts(now)` with an explicit reference date for
deterministic tests.

## End-to-end wiring

A typical table page shows the whole flow:

```vue
<AsTableRoot
  :key="path"
  v-model:url-query="urlQuery"
  :url="`/api/db/tables/${apiPath}`"
  :controls="controls"
  :preset="{
    url: '/api/db/_presets',
    tableKey: path,
    systemPresets,
    persistDrafts: true,
  }"
>
  <AsTableActions>
    <AsPresetPicker />
  </AsTableActions>
  <AsTable />
</AsTableRoot>
```

Note `:preset.systemPresets` is per-table — each table can declare
its own built-in views.

## Next steps

- [Server-Side Presets](/tables/server-presets) — wire up the
  Moost controller, override hooks, configure DB.
- [URL State](/tables/url-state) — the address-bar bridge that
  complements presets.


---
URL: "ui.atscript.dev/tables/query-function"
LLMS_URL: "ui.atscript.dev/tables/query-function.md"
outline: "deep"
---

# Query Function

`<AsTableRoot>` is generic over its data source. There are two
supported wirings:

- **Path A — moost-db.** Point `:url` at a moost-db endpoint and the
  built-in `Client` (from `@atscript/db-client`) handles everything:
  metadata, paged data, value-help, actions.
- **Path B — custom `queryFn`.** Provide your own fetcher. The table
  still consumes the moost-db `/meta` response shape for capabilities,
  but you control how rows are loaded.

## Path A — moost-db

This is the default when you set `:url`:

```vue
<AsTableRoot url="/db/tables/products" :limit="25" v-slot="slot">
  <AsTable />
</AsTableRoot>
```

Under the hood `<AsTableRoot>`:

1. Resolves a `Client` via the shared `getMetaEntry(url, clientFactory)`
   cache. The first caller per URL creates the client; subsequent
   callers (tables AND value-help pickers) reuse it.
2. Fetches `/meta` and the serialized atscript type in parallel.
3. Calls `createTableDef(meta, type)` to merge them into a `TableDef`.
4. Calls `client.pages(query, page, size)` for data fetches. `query`
   is a `Uniquery` object built by `buildTableQuery`.

### The `/meta` response

`MetaResponse` (from `@atscript/db-client`, re-exported from
`@atscript/ui`) carries everything the client needs:

```typescript
interface MetaResponse {
  searchable: boolean;
  vectorSearchable: boolean;
  searchIndexes: SearchIndexInfo[];
  primaryKeys: string[];
  preferredId: string[];
  versionColumn?: string; // OCC version column (when `@db.column.version` is declared)
  crud: TCrudPermissions; // canCreate / canUpdate / canRemove
  actions: TDbActionInfo[]; // declarative server actions
  relations: RelationInfo[]; // to / from / via summaries
  fields: Record<string, FieldMeta>; // per-field { sortable, filterable }
  type: TSerializedAnnotatedType; // serialized .as type tree
}
```

`versionColumn` is present only on tables annotated with `@db.column.version` (see atscript-db's optimistic concurrency reference). It names the column the server manages for optimistic concurrency. Custom `queryFn` implementations don't need to do anything with it — atscript-ui handles the version-field hiding and 409 handling automatically. Just preserve the field in your returned `MetaResponse` shape. See the [Edit forms with optimistic concurrency](/tables/edit-form-occ) pattern guide.

The capability flags drive UI gates:

- `meta.fields[path].filterable` / `.sortable` enable the column menu's
  filter and sort entries.
- `meta.searchable` enables the search bar.
- `meta.crud.canRemove` gates the synthesised `__remove` row action.
- `meta.actions` populates `state.actions.table / .row / .rows` with
  declarative actions.

See [db.atscript.dev/http/crud](https://db.atscript.dev/http/crud) for
the full meta + CRUD route reference.

### The `Uniquery` data shape

`buildTableQuery` produces a `Uniquery` object combining filters,
sorters, projection, search and pagination:

```typescript
{
  filter: FilterExpr | undefined,
  controls: {
    $select?: string[],          // visible column paths (projection)
    $sort?: { [path]: 1 | -1 },  // user + force sorters
    $search?: string,            // search term (or "$search:indexName")
    $actions?: true,             // ask server for per-row gateable actions
  }
}
```

Pagination is passed separately as the `page` and `size` arguments —
moost-db returns a `PageResult<T> = { data, page, itemsPerPage, pages,
count }` for every page. The table reads `count` for the total row
count and uses the rest to align block prefetch with the server's
page math.

Detailed Uniquery semantics, operators and projection rules live in the
[atscript-db query syntax docs](https://db.atscript.dev/api/queries).

## Path B — custom `queryFn`

Bring your own fetcher. The signature:

```typescript
type QueryFn = (
  query: Uniquery,
  page: number,
  size: number,
) => Promise<PageResult<Record<string, unknown>>>;

interface PageResult<T> {
  data: T[];
  page: number;
  itemsPerPage: number;
  pages: number;
  count: number;
}
```

You still need a `/meta`-shaped response somewhere — the table relies on
its capability flags, field metadata and serialized type. The simplest
approach is to write a static endpoint that returns a `MetaResponse`
built from your atscript file at server startup.

```vue
<script setup lang="ts">
import { AsTableRoot, AsTable, createDefaultCellTypes } from "@atscript/vue-table";
import type { Uniquery } from "@uniqu/core";

const types = createDefaultCellTypes();

async function queryFn(query: Uniquery, page: number, size: number) {
  const res = await fetch(
    `/api/my-rows?${new URLSearchParams({
      page: String(page),
      size: String(size),
      q: JSON.stringify(query),
    })}`,
  );
  const json = await res.json();
  return { data: json.rows, total: json.total };
}
</script>

<template>
  <AsTableRoot url="/api/my-rows" :query-fn="queryFn" :types="types" :limit="50">
    <AsTable />
  </AsTableRoot>
</template>
```

`:url` is still required — it's the cache key used by
`getMetaEntry`, and the built-in client uses it for the `/meta` fetch
unless you also supply a custom `clientFactory`. For fully-custom
backends, the most common pattern is to expose `<your-base>/meta` that
returns a `MetaResponse`, and route `<your-base>/q` through your
`queryFn`.

::: tip Skipping moost-db entirely
For pure-static datasets (in-memory arrays) use
`createStaticTableState` from `@atscript/vue-table` — it ships with a
default substring-matcher `queryFn` and a synthesised `/meta` derived
from the `.as` type. Useful for fixtures, e2e tests, and dev playgrounds.
:::

## Force filters and force sorters

Both wirings support always-applied constraints that the user cannot
remove:

```vue
<AsTableRoot
  url="/db/tables/orders"
  :force-filters="{ status: 'open' }"
  :force-sorters="[{ field: 'createdAt', direction: 'desc' }]"
/>
```

`buildTableQuery` merges these with user state via `mergeFilters` and
`mergeSorters`:

- **`mergeFilters(force, user)`** — combines with `$and` at the top
  level. If `force` exists, every user condition AND-s with it. Both
  are `FilterExpr`s from `@uniqu/core`.
- **`mergeSorters(force, user)`** — prepends `force` first. If a field
  appears in both lists, the force entry wins; the matching user entry
  is dropped from the merged result.

Both are exported from `@atscript/ui-table` for direct use in
non-AsTableRoot contexts.

## Cache and reuse

A single `/meta` fetch is shared across every component that points at
the same URL — multiple tables, value-help pickers and form `ref`
fields all consult the same `MetaCacheEntry`. The cache lives in
`@atscript/ui` (`getMetaEntry` / `resetMetaCache`). Call
`clearTableCache()` (alias for `resetMetaCache`) if you need to drop a
stale entry — for instance after a schema reload during development.

## Next steps

- [Filtering](/tables/filtering) — how `state.filters` becomes the
  `FilterExpr` half of `Uniquery`.
- [Sorting](/tables/sorting) — `state.sorters` and force-sort
  semantics.
- [Pagination & Virtualization](/tables/pagination) — how `page` /
  `size` (and block-aligned fetches for windowed tables) work in
  practice.


---
URL: "ui.atscript.dev/tables/server-presets"
LLMS_URL: "ui.atscript.dev/tables/server-presets.md"
outline: "deep"
---

# Server-Side Presets

`@atscript/moost-ui-presets` is the server half of the preset
feature. It ships `AsPresetEntry` (the `.as` schema for the
storage row), `AsPresetsController` (an abstract Moost controller),
and the read-gate / write-rule machinery that backs the client's
`PresetsClient`.

You extend the controller, plug in `getCurrentUser()`, and mount it
at a URL. The client points `usePresets()` / `<AsTableRoot :preset>`
at that URL.

## Install

```bash
pnpm add @atscript/moost-ui-presets @atscript/moost-db @atscript/db-sqlite
```

Pick the DB adapter that matches your stack — sqlite / postgres /
mysql / mongo. The schema is portable.

## The storage row

`AsPresetEntry` is one row per preset, userConf, or appConf. The
schema lives at
[`packages/moost-ui-presets/src/as-preset-entry.as`](https://github.com/mav-rik/atscript-ui/blob/main/packages/moost-ui-presets/src/as-preset-entry.as):

```atscript
@db.table 'as_presets'
export interface AsPresetEntry {
    @meta.id
    @db.default.uuid
    id: string

    @db.index.plain 'preset_scope_idx'
    type: 'preset' | 'userConf' | 'appConf'

    @db.index.plain 'preset_scope_idx'
    @db.index.unique 'preset_public_label_idx'
    app: string

    @db.index.plain 'preset_scope_idx'
    @db.index.unique 'preset_public_label_idx'
    tableKey?: string

    @db.index.plain 'preset_scope_idx'
    @db.index.plain 'preset_user_idx'
    user: string

    userLabel?: string

    @db.index.plain 'preset_public_idx'
    public?: boolean

    @db.index.plain 'preset_label_idx'
    label?: string

    @db.index.unique 'preset_public_label_idx'
    publicLabel?: string

    aspects?: PresetAspect[]

    @db.json
    data: PresetContent | UserConfContent | AppConfContent

    @db.default.now createdAt: number
    @db.default.now updatedAt: number
}
```

Three notable design points:

- **`publicLabel` enforces public-name uniqueness** at the DB layer.
  Stamped equal to `label` only when `type='preset' AND public=true`,
  `NULL` otherwise. The composite unique index over `(app, tableKey,
publicLabel)` relies on `NULL ≠ NULL` semantics so private rows
  don't collide.
- **`aspects[]` is derived** by the controller from `data.content`
  keys on every write. The picker projects this without loading
  the snapshot blob, which keeps the list view cheap.
- **`tableKey` is absent for appConf** — appConf rows are
  per-`(user, app)` only.

Sync the schema with your DB adapter before the controller mounts.
See [db.atscript.dev sync](https://db.atscript.dev/sync) for the
adapter-specific commands.

## Extending the controller

`AsPresetsController` is `@Inherit()`-annotated abstract. You
subclass it, override **at least** `getCurrentUser()`, and apply
your auth / table-mounting decorators:

```ts
import { AsPresetsController } from "@atscript/moost-ui-presets";
import { TableController } from "@atscript/moost-db";
import { Authenticate, HttpError } from "@moostjs/event-http";
import { presetsTable } from "../db";
import { useSession } from "../auth/use-session";
import { SessionGuard } from "../auth/session.guard";

@Authenticate(SessionGuard)
@TableController(presetsTable, "db/_presets")
export class PresetsController extends AsPresetsController {
  protected async getCurrentUser(): Promise<string> {
    const session = useSession();
    if (!session?.userId) throw new HttpError(401, "Not authenticated");
    return String(session.userId);
  }

  protected async canPublishPresets(
    _app: string,
    _tableKey: string,
    _user: string,
  ): Promise<boolean> {
    return useSession()?.roleName === "admin";
  }

  protected async getMaxPresetsPerUser(
    _app: string,
    _tableKey: string,
    _user: string,
  ): Promise<number> {
    const role = useSession()?.roleName;
    if (role === "admin") return 100;
    return 10;
  }

  protected async getUserLabel(_user: string): Promise<string | undefined> {
    return useSession()?.username;
  }
}
```

Hookable methods:

| Method                                      | Default                               | Purpose                               |
| ------------------------------------------- | ------------------------------------- | ------------------------------------- |
| `getCurrentUser()`                          | abstract — **required**               | Resolve the caller's user id          |
| `getMaxPresetsPerUser(app, tableKey, user)` | returns `this.maxPresetsPerUser` (10) | Per-user cap on preset creation       |
| `canPublishPresets(app, tableKey, user)`    | returns `true`                        | Gate for `private → public` writes    |
| `getUserLabel(user)`                        | returns `undefined`                   | "by alice" attribution on public rows |

`getUserLabel()` exists so the controller doesn't need a join to
the users table on every preset write — read straight from the
session.

## REST surface

The controller exposes one custom endpoint plus the four inherited
from `AsDbController`:

| Method | Path            | Purpose                                         |
| ------ | --------------- | ----------------------------------------------- |
| GET    | `/capabilities` | `{ canPublish, presetLimit, userId }`           |
| GET    | `/`             | List rows (gated by read-rule, optional filter) |
| POST   | `/`             | Create row                                      |
| PATCH  | `/:id`          | Partial update                                  |
| DELETE | `/:id`          | Remove row                                      |

`/capabilities` is the only bespoke endpoint. It runs both hooks
(`canPublishPresets`, `getMaxPresetsPerUser`) with the caller's
`(app, tableKey, user)` and returns the result for the client to
gate its UI without guessing. The client calls it once on mount.

## Permission model

### Read gate

The controller installs a read filter via `transformFilter()`:

```ts
user === currentUser OR (type === 'preset' AND public === true)
```

Every list query is rewritten to match the gate. Even an explicit
`filter` from the client is `AND`-ed with this rule. Users can't
read other users' private rows; everyone reads public preset rows
in their `(app, tableKey)`.

### Write rules

- **Reserved id prefixes** `sys:`, `uc:`, `ac:` are rejected from
  client writes. The controller stamps `uc:*` and `ac:*` ids
  itself; `sys:*` is client-only.
- **Public-label uniqueness** within `(app, tableKey)` is enforced
  by the `preset_public_label_idx` unique index. Two users racing
  the same public name produces a 409 instead of slipping past a
  read-then-write window.
- **Per-user cap** is enforced on every create. `getMaxPresetsPerUser()`
  is called inside the transaction; over-cap requests get HTTP `409`
  with `code: "preset_limit_reached"`, plus `limit` and `count` in
  the payload so the client can render an accurate message.
- **`canPublishPresets()` gates the `private → public` transition**.
  Already-public rows are grandfathered — revoking publish
  permission doesn't unpublish existing preset rows. This is
  deliberate: a role demotion shouldn't disappear a shared
  view that other users may be relying on.

### Stamping

The controller transparently stamps:

- `user` from `getCurrentUser()` (clients can't impersonate).
- `userLabel` from `getUserLabel()` on every preset write.
- `label` mirroring `data.label` on every preset write.
- `publicLabel` equal to `label` when `type='preset' AND public=true`,
  else `NULL`.
- `aspects[]` derived from `data.content` keys on every preset
  write.
- `createdAt` / `updatedAt` from `@db.default.now`.

The client doesn't need to know any of this — it sends a clean
`PresetSnapshotWire`, the controller fills the rest.

## Client wiring

The client points at the controller's URL via the table root's
`:preset` prop:

```vue
<AsTableRoot
  :url="`/api/db/tables/orders`"
  :preset="{
    url: '/api/db/_presets',
    tableKey: 'orders',
    systemPresets: [
      {
        id: 'open',
        label: 'Open',
        content: {
          /* ... */
        },
      },
    ],
  }"
>
  <AsTableActions>
    <AsPresetPicker />
  </AsTableActions>
  <AsTable />
</AsTableRoot>
```

For headless access — custom picker, programmatic flows — use
`usePresets()`:

```ts
import { usePresets } from "@atscript/vue-table";

const presets = usePresets({
  url: "/api/db/_presets",
  tableKey: "orders",
  systemPresets,
});

await presets.savePresetAs("Q4 Open", snapshot, { public: true });
```

## Mounting once for the whole app

The controller mounts at one URL per app — there's no per-table
routing. All `(app, tableKey)` scoping happens in the data layer.
Mount once in your Moost app, pass the same URL to every
`<AsTableRoot :preset>`, and the controller filters rows by
`(app, tableKey)` on the way out.

## Next steps

- [Presets](/tables/presets) — the client-side model.
- [db.atscript.dev](https://db.atscript.dev) — DB adapter wiring,
  `AsDbController` reference, schema sync.
- [moost](https://moost.org) — controller decorators, guards,
  interceptors.


---
URL: "ui.atscript.dev/tables/sorting"
LLMS_URL: "ui.atscript.dev/tables/sorting.md"
outline: "deep"
---

# Sorting

The sort model is a flat array: `SortControl[]`. Multi-sort is the
default — later entries break ties of earlier ones. The state contract
is the same as for filters: pure mutators, single watcher reaction.

## The sort model

```typescript
interface SortControl {
  field: string; // column path (dot-notation)
  direction: "asc" | "desc";
}
```

State lives at `state.sorters`. The renderer translates it into the
`$sort` portion of `Uniquery`:

```typescript
// state.sorters
[
  { field: "status", direction: "asc" },
  { field: "createdAt", direction: "desc" },
]

// → controls.$sort
{ status: 1, createdAt: -1 }
```

Order matters. The server applies the directives in the same order, so
`status` is the primary sort and `createdAt` is the tiebreaker.

## How sorters get into the state

### Header click

Clicking a `<AsTableHeaderCell>` toggles the column's position in
`state.sorters`:

1. **Not in sorters** → appended as `asc`.
2. **Already `asc`** → flipped to `desc`.
3. **Already `desc`** → removed from the array.

Shift-click (or repeated clicks while another column is already sorted)
preserves the rest of the array — that's how the user builds a
multi-sort.

The header cell only fires the toggle when `column.sortable === true`,
which itself derives from `meta.fields[path].sortable` (the server flag
from `@db.index.*` / `@db.column.sortable` / `@db.table.sortable`). For
non-sortable columns the header is inert.

### The config dialog

`<AsConfigDialog>`'s _Sorters_ tab is the heavy-duty editor:

- Reorder sorters by drag.
- Flip direction.
- Remove sorters.
- (Re-)add any sortable column.

All operations write back to `state.sorters`; nothing else changes
until the watcher re-fires the query.

### `v-model:sorters`

`<AsTableRoot>` accepts an external `Ref<SortControl[]>` via
`v-model:sorters`. Useful for surfacing sort state in a parent
component (URL state, persistence, sync between sibling tables).

## Force sorters

`<AsTableRoot :force-sorters="...">` (or the underlying
`useTable({ forceSorters })`) pins a list of sorters that always
prepend the user's:

```vue
<AsTableRoot
  url="/db/tables/items"
  :force-sorters="[{ field: 'priority', direction: 'desc' }]"
>
```

The merge rule is implemented by `mergeSorters` in
`@atscript/ui-table`:

```typescript
import { mergeSorters } from "@atscript/ui-table";

mergeSorters(
  [{ field: "priority", direction: "desc" }],
  [
    { field: "priority", direction: "asc" },
    { field: "name", direction: "asc" },
  ],
);
// → [{ field: "priority", direction: "desc" }, { field: "name", direction: "asc" }]
```

If a user sorter targets the same field as a force sorter, the user
entry is dropped from the merged result — the force entry wins. The
user's array isn't mutated; only the merged result that flows into
`buildTableQuery` is affected.

This is the natural reading of "force": the server _always_ sees the
force sorter, and the user can layer additional tie-breakers
underneath but cannot override.

## Programmatic sorting

For one-off application from the parent component, write directly to
the model:

```vue
<AsTableRoot ref="root" url="/db/tables/orders" v-slot="{ sorters }">
  <button
    @click="root!.state.sorters.value = [{ field: 'amount', direction: 'desc' }]"
  >
    Sort by amount
  </button>
  <AsTable />
</AsTableRoot>
```

Watchers downstream will re-fire the query automatically — you don't
need to call `state.query()`.

## What ends up on the wire

`buildTableQuery` (in `@atscript/ui-table`) assembles the `$sort`
controls block from the merged sorters:

```typescript
const sorters = forceSorters?.length ? mergeSorters(forceSorters, userSorters) : userSorters;

const $sort: Record<string, 1 | -1> = {};
for (const s of sorters) {
  $sort[s.field] = s.direction === "asc" ? 1 : -1;
}
```

Backends consume the same shape — see
[atscript-db query syntax](https://db.atscript.dev/api/queries) for the
adapter-specific lowering.

## Next steps

- [Pagination & Virtualization](/tables/pagination) — how sort
  changes interact with page reset and block invalidation.
- [URL State](/tables/url-state) — bookmarkable sort order.
- [Config Dialog](/tables/config-dialog) — the _Sorters_ tab UX.


---
URL: "ui.atscript.dev/tables/url-state"
LLMS_URL: "ui.atscript.dev/tables/url-state.md"
outline: "deep"
---

# URL State

Filters, sorters, pagination, and full-text search round-trip
through the browser address bar. Sharing a URL shares the exact
view. Bookmarking a URL bookmarks the exact view. Back/forward
navigates between views.

## The composable

`useTableUrlQuery(useRoute(), useRouter())` returns a
`WritableComputedRef<string>` that owns the entire `route.query`.
Bind it to `<AsTableRoot v-model:url-query>`:

```vue
<script setup lang="ts">
import { useRoute, useRouter } from "vue-router";
import { AsTableRoot, useTableUrlQuery } from "@atscript/vue-table";

const urlQuery = useTableUrlQuery(useRoute(), useRouter());
</script>

<template>
  <AsTableRoot url="/api/db/tables/orders" v-model:url-query="urlQuery" />
</template>
```

The composable does **type-only** imports of `Router` and
`RouteLocationNormalizedLoaded`, so `@atscript/vue-table` has no
runtime dependency on `vue-router`. Pass in already-resolved
instances from the consumer app.

## What syncs

Four aspects round-trip:

| Aspect     | URL form (uniqu syntax)     |
| ---------- | --------------------------- |
| Filters    | `name=acme&status='active'` |
| Sorters    | `$sort=-createdAt,+name`    |
| Pagination | `$skip=50` (page-derived)   |
| Search     | `$search='laptop'`          |

Default view (page 1, no filters, no sorters, no search) emits an
empty string — no `?` in the URL.

The encoder lives in `@atscript/ui-table` as
`stateToUrlQueryString()`; the decoder is
`urlQueryStringToState()`. The Vue composable is just a thin
vue-router bridge — apps that need a custom routing integration can
call those directly.

## Per-aspect gating

Some pages don't want every aspect in the URL. Orders, for example,
might share filters but always land recipients on page 1 — pinning
the linker's page would be wrong. Use `urlQuerySync`:

```vue
<AsTableRoot
  v-model:url-query="urlQuery"
  :url-query-sync="{ pagination: false }"
  url="/api/db/tables/orders"
/>
```

The shape:

```ts
interface UrlQuerySync {
  filters?: boolean | string[]; // allowlist of field paths
  sorters?: boolean | string[]; // allowlist of field paths
  search?: boolean; // $search
  pagination?: boolean; // $skip + $limit
}
```

`true` (or omitted) syncs the whole aspect. `false` opts out
entirely. A `string[]` allowlist syncs only the listed field paths
— useful for "share the public filters, hide the internal ones".

The gate is honoured **symmetrically**: the encoder leaves the
aspect out, the decoder ignores it on hydration. Asymmetric gating
would produce self-echoing URLs.

## Hydration

On first mount, `applyUrlQuery(urlString)` replays the URL onto
state:

- Replaces `state.filters`, `state.sorters`, `state.searchTerm`,
  `state.pagination.page`.
- Unions decoded filter field paths into `state.filterFields` so
  hidden inputs become visible (you arrived at this URL because
  someone filtered by them).
- Sets `state.hydratingFromUrl` for the current tick — the root
  watcher suppresses its query call so a second fetch doesn't
  follow the URL replay.

The bridge is echo-guarded: writes that originated from
`applyUrlQuery` don't fire a follow-up URL write back, and writes
that originated from state mutations don't trigger a re-hydration
of the state they came from.

## End-to-end wiring

A canonical table-page consumer:

```vue
<script setup lang="ts">
import { computed } from "vue";
import { useRoute, useRouter } from "vue-router";
import { AsTable, AsTableRoot, useTableUrlQuery } from "@atscript/vue-table";

const urlQuery = useTableUrlQuery(useRoute(), useRouter());

// Per-table aspect gates from the route's metadata
const props = defineProps<{ path: string }>();
const urlQuerySync = computed(() => {
  if (props.path === "orders") return { pagination: false };
  return undefined;
});
</script>

<template>
  <AsTableRoot
    :key="path"
    v-model:url-query="urlQuery"
    :url-query-sync="urlQuerySync"
    :url="`/api/db/tables/${path}`"
  >
    <AsTable />
  </AsTableRoot>
</template>
```

A few things to note:

- `:key="path"` remounts the root when the table changes. The URL
  parser only fires on initial mount; remounting on path is how
  cross-table navigation hydrates from the new URL.
- `urlQuerySync` is a `ComputedRef` so each table page picks its
  own gating without affecting siblings.
- The default mode is `replace`, so typing in the search box does
  not pollute history with 30 entries. Use
  `useTableUrlQuery(route, router, { mode: 'push' })` if every
  state change should be a discrete back-button step.

## Caveats

`useTableUrlQuery` owns the **entire** `route.query`. Apps that mix
table state with unrelated query params (e.g. an analytics tag,
`?utm_source=...`) should write a small `WritableComputedRef`
themselves that merges in the table aspect rather than wholesale-
replacing the query. The pattern is small enough that we don't
want to grow the public API surface to cover it.

## Next steps

- [Presets](/tables/presets) — durable named views (server-side).
- [Server-Side Presets](/tables/server-presets) — wire up Moost.


---
URL: "ui.atscript.dev/workflows"
LLMS_URL: "ui.atscript.dev/workflows.md"
outline: "deep"
---

# Workflows

`@atscript/vue-wf` (client) and `@atscript/moost-wf` (server) implement
**HTTP round-trip workflow forms**: long, multi-step user flows where
the _server_ decides which screen comes next.

A single workflow is one long-lived conversation: the server pauses,
asks the client for a form, validates the answer, optionally branches,
and resumes — all over plain HTTP, no sockets, no client-side state
machine. Built on top of [`@moostjs/event-wf`](https://moost.org).

## What it solves

The flows everyone writes by hand and gets wrong:

- **Login + MFA** — credentials, then OTP iff `mfaEnabled`, then a
  session cookie.
- **Sign-up with email verification** — register, send code, verify,
  create user, sign in.
- **Invite + register** — admin invites by email, invitee gets a
  magic link, lands on a "finish your account" form.
- **Multi-step checkout** — address, then payment, then confirm,
  with per-step server validation and conditional branches (e.g. skip
  payment for free tier).
- **Password change with re-auth** — confirm current password,
  collect new one, save.

These are all the same shape: a server-owned **state machine** with
**form steps**, branching on server-side state the browser is not
allowed to see (`mfaEnabled`, `roleName`, …).

## The mental model

```
┌─────────┐  POST /wf {wfid}            ┌─────────┐
│ client  │ ─────────────────────────►  │ server  │
│         │                             │         │
│  AsWf   │ ◄───────────────────────── │  Step   │
│  Form   │  {inputRequired, wfs}       │ handler │
│         │                             │         │
│         │  POST /wf {wfs, input}      │         │
│         │ ─────────────────────────►  │         │
│         │                             │  Step   │
│         │ ◄───────────────────────── │ handler │
│         │  {inputRequired, wfs}       │         │
│         │           ...               │         │
│         │ ◄───────────────────────── │  Step   │
│         │  {finished: true, ...}      │ handler │
└─────────┘                             └─────────┘
```

Every round-trip is one POST. The response is one of:

- `{ inputRequired: { payload, transport, context }, wfs }` — render
  this form next, here is the new state token.
- `{ finished: true, ... }` — done; the rest of the body is the
  flow's result payload (session cookie set, redirect URL, …). The
  `finished: true` marker is supplied by `handleAsOutletRequest`, so
  step handlers only return their domain data via
  `finishWf({ data })` (from `@atscript/moost-wf`).
- `{ sent: true }` / `{ outlet: "..." }` — flow paused waiting for
  an external event (email link clicked, webhook fired). The current
  HTTP session is done; resume happens later via the token.
- `{ error: { message } }` — recoverable error; the client surfaces
  it and lets the user retry.

The client never decides which form comes next. The client just
**renders whatever the server returns**, posts back the answer, and
keeps going until `finished: true`.

## The two packages

### `@atscript/vue-wf` — the client

One Vue 3 component (Tier 1, auto-imported by `AsResolver`):

```vue
<AsWfForm path="/api/wf" name="auth/login" :types="types" @finished="onFinished" />
```

Or use the composable `useWfForm({ ... })` directly when you want to
roll your own UI shell around the round-trip.

See [Client: AsWfForm](/workflows/client) for the full API.

### `@atscript/moost-wf` — the server

A thin layer on top of [`@moostjs/event-wf`](https://moost.org)
that:

- Wraps each step's input/output in the wire format the Vue client
  expects (`{ inputRequired: { payload, transport, context } }`).
- Caches the serialized atscript schema per type (so the payload is
  built once per type, not once per step run).
- Validates the incoming input against the form type before the step
  handler runs.
- Filters workflow context through a `@wf.context.pass` whitelist
  before sending it to the browser (no accidental state leakage).
- Lets step handlers signal "re-pause with these errors" through
  `useAtscriptWf(Type).requireInput({ ... })` — a `StepRetriableError`
  the workflow engine catches natively.
- Ships an `AsWfStore` for **durable state persistence** in any
  atscript-db table — opt in for flows that must survive process
  restart (email magic links, multi-day approvals).

See [Server-Side Authoring](/workflows/server-authoring).

## Quick map

| Topic                                          | Page                                                 |
| ---------------------------------------------- | ---------------------------------------------------- |
| Two-step end-to-end example                    | [Hello World](/workflows/hello-world)                |
| `@Workflow` + `@Step` + `@WorkflowSchema`      | [Server-Side Authoring](/workflows/server-authoring) |
| `@WfInput`, `requireInput`, server-side errors | [Form Input & Validation](/workflows/form-input)     |
| Alt actions (resend code, save draft, …)       | [Actions](/workflows/actions)                        |
| Passing context to the client form             | [Context Passing](/workflows/context)                |
| Durable state with `AsWfStore`                 | [State Persistence](/workflows/state-persistence)    |
| Magic links, outlets, resume                   | [Outlets & Resume](/workflows/outlets-resume)        |
| `<AsWfForm>` + `useWfForm()` reference         | [Client: AsWfForm](/workflows/client)                |
| Terminal screens, redirects, choice buttons    | [Finish Screens](/workflows/finish-screens)          |
| Login+MFA, invite+register, checkout           | [Recipes](/workflows/recipes)                        |

## Related

- [Forms](/forms/) — single-step forms (the rendering layer the
  workflow client reuses for each step).
- [Tables](/tables/) — annotation-driven smart tables.
- [moost.org](https://moost.org) — the moost framework + the
  underlying `@moostjs/event-wf` workflow engine.
- [atscript.dev](https://atscript.dev) — `.as` files, annotations,
  the type system used to declare every form.
- [db.atscript.dev](https://db.atscript.dev) — the DB layer used by
  `AsWfStore`.


---
URL: "ui.atscript.dev/workflows/actions"
LLMS_URL: "ui.atscript.dev/workflows/actions.md"
outline: "deep"
---

# Actions

A workflow form's submit button advances the flow. **Actions** are
the other buttons next to it — _resend code_, _save draft_, _use
backup method_, _forgot password_. Each one posts back to the same
step with an `action` name, optionally with form data.

## The two action kinds

| Kind             | Annotation                   | Sends data?                  | Server reads via                                                         |
| ---------------- | ---------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| Plain action     | `@ui.form.action 'name'`     | No                           | `@WfAction(Form)` param (step skipped unless `@WfInput({ pass: true })`) |
| Action with data | `@wf.action.withData 'name'` | Yes (deep-partial validated) | `@WfAction(Form)` param + `@WfInput()` data                              |

Both render as buttons in the rendered form's action row. Both let
the step keep the user on the same screen, re-render the same form,
finish the flow, or do something arbitrary.

## Declaring actions on the form

Actions are declared as fields on the form type, with the action
annotation:

```atscript
@meta.label 'Verify Identity'
@ui.form.submit.text 'Verify Code'
export interface MfaPincodeForm {
    @meta.label 'Verification Code'
    @ui.form.placeholder '000000'
    @meta.required 'Code is required'
    @expect.minLength 6, '6 digits expected'
    @expect.maxLength 6, '6 digits expected'
    code: string

    // Plain action — no form data.
    @ui.form.action 'resend'
    @meta.label 'Resend Code'
    _resend?: boolean

    // Action with data — sends current form fields with deep-partial validation.
    @wf.action.withData 'saveDraft'
    @meta.label 'Save Draft'
    _saveDraft?: boolean
}
```

The field itself is a placeholder — the runtime never stores a value
on it. It only carries the annotation and the label. Use a leading
underscore name to make the intent clear, and make it optional so it
doesn't fail required-field validation.

The form renderer reads these annotations and emits one button per
action next to the submit button.

## Reading the action on the server

Two ways, mirroring how you read input.

### Decorator: `@WfAction(Form)`

```ts
import { WfInput, WfAction, useAtscriptWf } from "@atscript/moost-wf";
import { MfaPincodeForm } from "../forms/MfaPincodeForm.as";

@Step("login-verify-otp")
async verifyOtp(
  @WorkflowParam("context") ctx: LoginCtx,
  @WfAction(MfaPincodeForm) action: string | undefined,
  @WfInput({ pass: true }) input?: MfaPincodeForm,
) {
  const wf = useAtscriptWf(MfaPincodeForm);

  if (action === "resend") {
    ctx.otpCode = String(Math.floor(100000 + Math.random() * 900000));
    await sendOtpEmail(ctx.email!, ctx.otpCode);
    // Re-pause the same form (no errors) so the user can re-enter the code.
    throw wf.requireInput();
  }

  if (action === "saveDraft") {
    // input here is partial-validated form data from @wf.action.withData.
    await drafts.save(ctx.userId!, input ?? {});
    throw wf.requireInput();
  }

  // No action → normal submit path; input is fully validated.
  if (input!.code !== ctx.otpCode) {
    throw wf.requireInput({ errors: { code: "Invalid code" } });
  }
  return;
}
```

`@WfAction(Form)` returns the action name string, or `undefined` for
a normal submit. The handler dispatches with a regular `switch` / `if`
chain. The form-type argument is required — the decorator validates
the incoming action against the form's `@ui.form.action` /
`@wf.action.withData` whitelist and throws `StepRetriableError` for
unknown actions before the step body runs.

`@WfInput({ pass: true })` opts this step into handling no-data
actions (`@ui.form.action`) without forcing input — the parameter
resolves to `undefined` when a no-data action fires. Without
`pass: true`, the decorator throws on no-data actions.

Use `?:` syntax (`input?: Form`), not a union (`input: Form | undefined`) — the union breaks atscript metadata reflection (TS emits `Object` instead of the AsType for union-typed parameters). `@WfInput({ pass: true })` composes `@Optional()` internally so global validator pipes skip the `undefined` value.

### Composable: `useAtscriptWf()`

For full explicit control (no decorator policy matrix), call the
composable directly:

```ts
import { useAtscriptWf } from "@atscript/moost-wf";

@Step("login-verify-otp")
async verifyOtp(@WorkflowParam("context") ctx: LoginCtx) {
  const wf = useAtscriptWf(MfaPincodeForm);
  const action = wf.resolveAction();

  if (action === "resend") {
    ctx.otpCode = String(Math.floor(100000 + Math.random() * 900000));
    await sendOtpEmail(ctx.email!, ctx.otpCode);
    throw wf.requireInput();
  }

  const input = wf.resolveInput({ partial: action === "saveDraft" ? "deep" : undefined });
  if (action === "saveDraft") {
    await drafts.save(ctx.userId!, input);
    throw wf.requireInput();
  }
  if (input.code !== ctx.otpCode) {
    throw wf.requireInput({ errors: { code: "Invalid code" } });
  }
}
```

`resolveAction()` throws if the action isn't declared on the form
schema; `resolveInput()` throws if input is missing or invalid.
Both return a `StepRetriableError` the workflow engine catches
natively.

## How validation differs per kind

`@WfInput()` inspects the action before validating:

- **No action** (normal submit): full validation; missing required
  fields cause re-pause with errors.
- **`@ui.form.action`** (plain): the step is skipped unless declared
  with `@WfInput({ pass: true })`. With `pass: true`, the parameter
  resolves to `undefined` and the handler runs. Useful for _resend
  code_, _forgot password_, _cancel_.
- **`@wf.action.withData`**: deep-partial validation. The framework
  only checks the fields actually present in the payload — missing
  fields are not "required-failing". Useful for _save draft_ flows
  where the user might be halfway through.

If the action name is not declared on the form, the framework
re-pauses with a `__form` error `"Action "<name>" is not supported"`.

## Calling actions from the client

The client side mirrors the server: the rendered form has buttons
labeled with each action; clicking one fires the action via the
underlying composable.

### From the default `<AsWfForm>`

Nothing extra to wire — the component reads the form type's
annotations, classifies each action as plain vs with-data (based on
which annotation it carries), and POSTs the right body.

### From `useWfForm()` directly

```ts
import { useWfForm } from "@atscript/vue-wf";

const wf = useWfForm({ path: "/wf", name: "auth/login" });

// Plain action — no body besides token + action name.
wf.action("resend");

// Action with data — current form data, validated deep-partial server-side.
wf.actionWithData("saveDraft", currentFormData);
```

Bodies:

```http
POST /wf
{ "wfs": "<token>", "input": { "action": "resend" } }
```

```http
POST /wf
{ "wfs": "<token>", "input": { "action": "saveDraft", "formData": { "code": "123" } } }
```

`action` and `formData` ride inside the workflow's `input` envelope.
The wf engine wipes `body.input` after each step, so the action is
cleared for free between in-request step transitions — no cleanup
interceptor needed.

## Common patterns

### Resend a code

```ts
if (action === "resend") {
  ctx.otpCode = String(Math.floor(100000 + Math.random() * 900000));
  await sendOtp(ctx.email!, ctx.otpCode);
  throw useAtscriptWf(MfaPincodeForm).requireInput(); // re-render same form, no errors
}
```

### Forgot password (jump to a different flow)

```ts
if (action === "forgotPassword") {
  // Finish the current flow with a "redirect" payload — let the client
  // mount a different workflow.
  finishWf({ data: { redirect: "/recover" } });
  return;
}
```

### Switch verification method

```ts
if (action === "useBackup") {
  ctx.mfaMethod = "backup-codes";
  return; // advance — the schema's condition routes us to a different step
}
```

The action handler can do anything a normal step can — call
`finishWf()` / `abortWf()`, mutate context to flip a branch condition,
or re-pause the same form. The flow stays a flow.

## Where to go next

- [Form Input & Validation](/workflows/form-input) — `@WfInput()`
  and `useAtscriptWf().requireInput()` patterns reused above.
- [Context Passing](/workflows/context) — how the form renderer
  reads context (e.g. to label the _resend_ button with the masked
  email).
- [Forms / Annotations](/forms/annotations) — the full annotation
  reference, including `@ui.form.action`.


---
URL: "ui.atscript.dev/workflows/client"
LLMS_URL: "ui.atscript.dev/workflows/client.md"
outline: "deep"
---

# Client: AsWfForm

The Vue 3 mount point. `<AsWfForm>` is a Tier-1 component
(auto-imported by `AsResolver`) that owns the HTTP round-trip and
delegates rendering to `<AsForm>`. For full control over the chrome,
drop down to the underlying `useWfForm()` composable.

## Minimal mount

```vue
<script setup lang="ts">
import { AsWfForm } from "@atscript/vue-wf";
import { createDefaultTypes } from "@atscript/vue-form";

const types = createDefaultTypes();

function onFinished(response: unknown) {
  // response = { finished: true, ...envelope } — the marker is supplied by
  // handleAsOutletRequest; the envelope's `data` is what the step passed
  // via finishWf({ data }) server-side.
}
</script>

<template>
  <AsWfForm path="/api/wf" name="auth/login" :types="types" @finished="onFinished" />
</template>
```

That's the entire integration: pick a path, name the workflow,
provide the type map, listen for the completion event.

## Props

```ts
interface AsWfFormProps {
  // ── Required ───────────────────────────────────────────────
  /** HTTP endpoint for the workflow trigger. */
  path: string;
  /** Workflow ID to start (the @Workflow("...") id on the server). */
  name: string;
  /** Type-to-component map for AsForm. Usually `createDefaultTypes()`. */
  types: TAsTypeComponents;

  // ── Token transport ────────────────────────────────────────
  /** "body" (default) | "cookie" | "query". */
  tokenTransport?: "body" | "cookie" | "query";
  /** Token parameter name. Default "wfs". */
  tokenName?: string;
  /** Workflow ID parameter name. Default "wfid". */
  wfidName?: string;
  /** Pre-existing token to resume from (e.g. Vue Router param). */
  initialToken?: string;

  // ── HTTP options ───────────────────────────────────────────
  /** Initial input sent with the first request. */
  input?: Record<string, unknown>;
  /** Custom fetch options (headers, credentials, AbortSignal). */
  fetchOptions?: RequestInit;
  /** Override the global fetch — for auth interceptors / status buses. */
  fetch?: typeof fetch;
  /** Auto-start on mount. Default true. */
  autoStart?: boolean;

  // ── AsForm forwarding ──────────────────────────────────────
  /** First-validation strategy. See Forms / Validation. */
  firstValidation?: TFormState["firstValidation"];
  /** Custom component map (named overrides). */
  components?: Record<string, Component>;
  /** Per-form client factory (FK value-help). */
  clientFactory?: ClientFactory;
  /** Forwarded to `<AsForm>`. Suppress the root field's title only (the description still renders). */
  hideRootTitle?: boolean;
  /** Forwarded to `<AsForm>`. Suppress the default submit button. */
  hideSubmit?: boolean;

  // ── Finish screen routing ──────────────────────────────────
  /**
   * Forwarded to `<AsWfFinish>`. Invoked with the redirect target URL
   * when a `redirect` action fires. Matches the `navigate` option on
   * `@atscript/db-client`'s `Client` so one handler covers both.
   */
  navigate?: (url: string) => void | Promise<void>;
}
```

Defaults set at the component:

| Prop             | Default  |
| ---------------- | -------- |
| `autoStart`      | `true`   |
| `tokenTransport` | `"body"` |
| `tokenName`      | `"wfs"`  |
| `wfidName`       | `"wfid"` |

## Emits

```ts
defineEmits<{
  (e: "finished", response: unknown): void;
  (e: "error", error: { message: string; status?: number }): void;
  (e: "form", def: FormDef, context?: Record<string, unknown>): void;
  (e: "submit", data: unknown): void;
  (e: "loading", isLoading: boolean): void;
  // Fired by the default AsWfFinish screen when a WfFinished envelope's
  // `next` triggers an action. See "Finish Screens".
  (e: "dismiss"): void;
  (e: "action", action: WfAction): void;
}>();
```

- **`@finished`** — flow completed (`{ finished: true, ... }`) or
  paused via outlet (`{ sent: true }`). Fires with the full
  response.
- **`@error`** — HTTP failure (`!res.ok`), network error, or
  `{ error }` body. Treat as recoverable.
- **`@form`** — fires whenever a new `FormDef` arrives (initial
  step, or schema change between steps). Useful for analytics /
  step transitions.
- **`@submit`** — fires _just before_ a form submit hits the wire.
  Fires for normal submits only — actions fire `wf.action(...)`
  internally and don't trigger this event.
- **`@loading`** — fires on every transition into / out of the
  loading state. Use for skeleton UI or button-disable.

## Slots

The default slot wraps the whole component and forwards the
composable's state for total layout control:

```vue
<AsWfForm path="/api/wf" name="hello" :types="types">
  <template #default="{ form, state, actions }">
    <pre>{{ form }}</pre>
    <button :disabled="state.loading" @click="actions.retry">Retry</button>
  </template>
</AsWfForm>
```

When the default slot is **not** overridden (the usual case), the
component renders one of these named slots based on the current
state, with sensible fallbacks:

| Slot                  | When                                                                            | Slot props                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `wf.loading`          | First load (no formDef yet)                                                     | — (default: `as-form-overlay` spinner on a `min-h-[100px]` wrapper, matching the overlay shown on subsequent round-trips) |
| `wf.error`            | Transport error — both before a form loads AND as a banner above a mounted form | `{ error, retry }`                                                                                                        |
| `wf.finished`         | `finished === true`                                                             | `{ response, payload }`                                                                                                   |
| `wf.finish.message`   | finished with `message`                                                         | `{ message }`                                                                                                             |
| `wf.finish.countdown` | finished with `next.trigger === 'auto'`                                         | `{ secondsRemaining, totalSeconds, skip, cancel }`                                                                        |
| `wf.finish.skip`      | finished with `auto` next + `skipButton`                                        | `{ button, trigger }`                                                                                                     |
| `wf.finish.primary`   | finished with `next.trigger === 'manual'`                                       | `{ button, trigger }`                                                                                                     |
| `wf.finish.option`    | finished with `manual` next (each option)                                       | `{ button, index, trigger }`                                                                                              |
| `form.header`         | Above the rendered form                                                         | The forwarded `AsForm` `slotProps` bag                                                                                    |
| `form.before`         | Inside the form, above fields                                                   | "                                                                                                                         |
| `form.after`          | Inside the form, below fields                                                   | "                                                                                                                         |
| `form.error`          | `AsForm` form-level error banner                                                | bag + `message`, `dismiss`                                                                                                |
| `form.submit`         | Replace the submit button                                                       | bag + `text`                                                                                                              |
| `form.footer`         | Below the form                                                                  | "                                                                                                                         |
| `form.loading`        | Contents of the loading overlay                                                 | "                                                                                                                         |

The `form.*` slots are forwarded straight through to the inner
`<AsForm>`, so each receives the **same `slotProps` bag** an AsForm slot
gets (`title`, `description`, `data`, `errors`, `formError`, `loading`,
`submit`, `reset`, …). See
[Forms — Slots & the slotProps bag](/forms/customization#slots-the-slotprops-bag)
for the full bag — it isn't restated here. `hideRootTitle` and
`hideSubmit` are likewise forwarded to `<AsForm>` (`hideRootTitle` hides the
root title only — the `@meta.description` still renders; see
[Forms — Hide props](/forms/customization#hide-props)), and **styling a wf form
is identical to styling any form** — override the relevant `as-*`
shortcut (see [Overriding a built-in `as-*` shortcut](/styling/shortcuts#overriding-a-built-in-as-shortcut)).

The `wf.finished` slot's `payload` is the typed `WfFinished` envelope
(`response` is the same value, kept for back-compat). When the
envelope's `next` is set, the default rendering switches into a
`AsWfFinish` screen — see [Finish Screens](/workflows/finish-screens)
for the envelope shape, the `wf.finish.*` scoped slots, the
`navigate` prop wiring, and the `@dismiss` / `@action` event contract.

Example: custom loading + finished states. The `wf.loading` slot
already has a default — the same `as-form-overlay` spinner that paints
on subsequent round-trips, on a wrapper with `min-h-[100px]` so the
page doesn't jump. Override only to swap in a branded indicator or
copy:

```vue
<AsWfForm path="/api/wf" name="auth/login" :types="types" @finished="onFinished">
  <template #wf.loading>
    <div class="spinner">Signing you in…</div>
  </template>

  <template #wf.finished="{ response, payload }">
    <!-- `payload` is the typed `WfFinished` envelope; `response` is the same
         value kept for back-compat. `payload` is `null` when the flow ended
         via an outlet pause (`{ sent: true }` / `{ outlet: '<name>' }`)
         rather than a true `finished: true` envelope. -->
    <div v-if="payload?.message" class="banner">
      {{ payload.message.text }}
    </div>
    <div class="success">
      Welcome, {{ (payload?.data as any)?.user?.username }}!
    </div>
  </template>

  <template #wf.error="{ error, retry }">
    <div class="error">
      <p>{{ (error as any).message }}</p>
      <button @click="retry">Try again</button>
    </div>
  </template>
</AsWfForm>
```

Providing `#wf.finished` opts out of the default `AsWfFinish` rendering —
the consumer takes full responsibility for the finish UI (including any
`next.action` wiring). To keep `AsWfFinish` and only restyle one piece,
override a `#wf.finish.*` sub-slot instead. See
[Finish Screens](/workflows/finish-screens) for the sub-slot contract.

## `useWfForm()` composable

Same plumbing without the rendering layer. Use it when:

- You want to render multiple workflows under one shell (login + MFA
  with shared chrome).
- You need to drive the flow programmatically (kick off via a button
  click, not on mount).
- You're embedding the flow in a non-standard layout (modal, wizard
  stepper, multi-pane).

```ts
import { useWfForm } from "@atscript/vue-wf";

const wf = useWfForm({
  path: "/api/wf",
  name: "auth/login",
  autoStart: false,
  tokenTransport: "cookie",
});

// Programmatic kick-off.
async function login() {
  await wf.start({
    /* optional initial input */
  });
}
```

### Return shape

```ts
interface UseWfFormReturn {
  // Reactive state
  formDef: ShallowRef<FormDef | null>;
  formData: ShallowRef<Record<string, unknown> | null>;
  formContext: ShallowRef<Record<string, unknown>>;
  errors: ShallowRef<Record<string, string>>;
  formKey: Ref<number>; // bump :key on AsForm to force remount
  loading: Ref<boolean>;
  finished: Ref<boolean>;
  response: ShallowRef<unknown>;
  error: ShallowRef<unknown>;

  // Methods
  start: (input?: Record<string, unknown>) => Promise<void>;
  submit: (data: unknown) => Promise<void>;
  action: (name: string) => Promise<void>;
  actionWithData: (name: string, data: unknown) => Promise<void>;
  retry: () => Promise<void>;
}
```

A rolled-your-own shell. Note that the placeholder text below is just
illustrative — `<AsWfForm>` renders an `as-form-overlay` spinner on a
`min-h-[100px]` wrapper during the first round-trip by default, so when
you stick with the wrapper component you get the overlay for free:

```vue
<script setup lang="ts">
import { useWfForm } from "@atscript/vue-wf";
import { AsForm, createDefaultTypes } from "@atscript/vue-form";

const wf = useWfForm({ path: "/api/wf", name: "auth/login" });
const types = createDefaultTypes();
</script>

<template>
  <div v-if="wf.loading.value && !wf.formDef.value">Loading…</div>
  <div v-else-if="wf.finished.value">Welcome!</div>
  <AsForm
    v-else-if="wf.formDef.value && wf.formData.value"
    :key="wf.formKey.value"
    :def="wf.formDef.value"
    :form-data="wf.formData.value"
    :types="types"
    :errors="wf.errors.value"
    :form-context="wf.formContext.value"
    @submit="wf.submit"
    @action="wf.action"
  />
</template>
```

Notice `:key="wf.formKey.value"` — when the schema changes between
steps, `formKey` increments; binding it as `:key` forces `AsForm` to
remount so the field components don't try to reconcile against a
new schema. The default `<AsWfForm>` does this for you.

## Custom fetch: auth headers, interceptors, status buses

The `fetch` prop swaps the function used for every request. The most
common reason: forward an Authorization header _and_ react to 401s
in a global app banner:

```ts
import { inject } from "vue";

const onAuthExpired = inject<() => void>("onAuthExpired");

async function authedFetch(url: string, init?: RequestInit): Promise<Response> {
  const token = localStorage.getItem("token");
  const headers = new Headers(init?.headers);
  if (token) headers.set("Authorization", `Bearer ${token}`);
  const res = await fetch(url, { ...init, headers });
  if (res.status === 401) onAuthExpired?.();
  return res;
}
```

```vue
<AsWfForm path="/api/wf" name="auth/login" :types="types" :fetch="authedFetch" />
```

A wrapper-friendly status bus typically wraps the global `fetch`
once at app boot. The same wrapper passed here keeps the workflow
client in sync with the rest of the app's HTTP behavior.

## Aborting

Every `start` / `submit` / `action` aborts the previous in-flight
request:

```ts
abortController?.abort();
abortController = new AbortController();
```

So calling `wf.action('resend')` while a slow `wf.submit(...)` is
mid-flight cancels the submit and dispatches the action. The user
never sees a "delayed" response from the old request.

The component also aborts on unmount.

## SSR

`<AsWfForm>` calls `start(input)` from `onMounted` by default, which `fetch`es `path` to retrieve the first form schema. Under SSR (`createSSRApp`) `onMounted` runs at hydration time on the client — but if a parent mounts a child `<AsWfForm>` during server rendering (e.g. inside a `<Suspense>` boundary that awaits child effects), the `fetch` fires in Node and either crashes (no `globalThis.fetch` polyfill) or hits your own server from itself.

Two equivalent guards:

```vue
<!-- 1. Set autoStart="false" and trigger explicitly after hydration. -->
<AsWfForm v-slot="{ actions }" path="/wf" name="…" :types :auto-start="false">
  <button @click="actions.start()">Begin</button>
</AsWfForm>

<!-- 2. v-if on a client-only ref. -->
<AsWfForm v-if="hydrated" path="/wf" name="…" :types />
```

```ts
import { onMounted, ref } from "vue";
export function useHydrated() {
  const hydrated = ref(false);
  onMounted(() => (hydrated.value = true));
  return hydrated;
}
```

The `<AsForm>` shell itself is SSR-safe — it has nothing to render until `formDef` is populated, so the only concern is the auto-`fetch` on mount. `useWfForm()` direct callers get the same `autoStart: false` knob.

## Reference

- Component: `packages/vue-wf/src/components/as-wf-form.vue`
- Composable: `packages/vue-wf/src/use-wf-form.ts`

## Where to go next

- [Form Input & Validation](/workflows/form-input) — how server-side
  errors flow back into `wf.errors`.
- [Outlets & Resume](/workflows/outlets-resume) — magic-link
  patterns using `initialToken`.
- [Recipes](/workflows/recipes) — end-to-end flows.


---
URL: "ui.atscript.dev/workflows/context"
LLMS_URL: "ui.atscript.dev/workflows/context.md"
outline: "deep"
---

# Context Passing

Every workflow has a **context** — a typed, mutable object that
persists across steps. Steps mutate it; conditions read it; the
state strategy serializes it between rounds. This page covers how it
works and — importantly — how to expose select keys to the _client
form_ without leaking the rest.

## The context object

Declared by the generic on `@WorkflowSchema<Ctx>`:

```ts
interface LoginCtx {
  userId?: number;
  username?: string;
  email?: string;
  roleId?: number;
  roleName?: SessionPayload["roleName"];
  mfaEnabled?: boolean;
  otpCode?: string;
}

@Workflow("auth/login")
@WorkflowSchema<LoginCtx>([
  { id: "login-credentials" },
  { id: "login-verify-otp", condition: (ctx) => !!ctx.mfaEnabled },
  { id: "login-issue-session" },
])
flow() {}
```

Inject it with `@WorkflowParam("context")`:

```ts
@Step("login-credentials")
async enterCredentials(
  @WorkflowParam("input") input: { username?: string; password?: string } | undefined,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  const user = await usersTable.findOne({ filter: { username: input!.username } });
  // Mutations persist into the next step
  ctx.userId = user!.id;
  ctx.email = user!.email;
  ctx.mfaEnabled = !!user!.mfaEnabled;
  if (ctx.mfaEnabled) {
    ctx.otpCode = String(Math.floor(100000 + Math.random() * 900000));
    await sendOtpEmail(ctx.email, ctx.otpCode);
  }
  return;
}
```

Mutations are persisted by the state strategy between steps. With
`EncapsulatedStateStrategy` the whole context is encrypted into the
token; with `HandleStateStrategy` (`AsWfStore`) it lives in the
`state` JSON column.

**Keep it serializable.** No class instances, functions, blobs.
Primitives, arrays, plain objects only.

## Exposing context to the client form

By default the client form sees **nothing** about the context. If
your `@ui.form.fn.title` wants to read `ctx.email`, or your action
button label wants `ctx.username`, you have to opt those keys in.

### `@wf.context.pass 'key'`

Decorate the **form type** (not the field) with one or more
`@wf.context.pass` annotations:

```atscript
@wf.context.pass 'email'
@meta.label 'Verify Identity'
@ui.form.submit.text 'Verify Code'
@ui.form.fn.title '(data, ctx) => `Enter the code sent to ${ctx.email || "your email"}`'
export interface MfaPincodeForm {
    @meta.label 'Verification Code'
    @ui.form.placeholder '000000'
    @meta.required 'Code is required'
    @expect.minLength 6, '6 digits expected'
    @expect.maxLength 6, '6 digits expected'
    code: string
}
```

The list works as a whitelist:

- Multiple `@wf.context.pass` annotations accumulate (merge strategy
  `append`).
- Only listed keys are extracted from the workflow context.
- Keys present on the context but not listed are **never sent** to
  the client.

### How it propagates

When a step's `@WfInput()` decorator (or a manual
`useAtscriptWf(MfaPincodeForm).requireInput()` call) throws a
`StepRetriableError`, the framework:

1. Calls `extractPassContext(MfaPincodeForm, ctx)` — reads
   `wf.context.pass` annotations from the type's metadata, picks
   only matching keys off the context object.
2. Builds the response: `{ inputRequired: { payload, transport,
context: { email: ctx.email } } }`.
3. The client form's `formContext` ref ends up as `{ email: "..." }`.

Both `@WfInput()` and `useAtscriptWf().requireInput()` call
`extractPassContext` under the hood, so the whitelist applies
uniformly.

If you re-pause with errors, errors merge into the context:

```json
"context": {
  "email": "alice@example.com",
  "errors": { "code": "Invalid code" }
}
```

The client splits `errors` back off (it lives on the form's
`errors` ref) and leaves the rest as `formContext`.

## Reading context on the client

### From the `<AsWfForm>` slots

The slot props expose `formContext`:

```vue
<AsWfForm path="/wf" name="auth/login" :types="types">
  <template #form.header="{ formContext }">
    <div v-if="formContext?.email">
      We sent a code to {{ formContext.email }}.
    </div>
  </template>
</AsWfForm>
```

### From `useWfForm()`

```ts
const wf = useWfForm({ path: "/wf", name: "auth/login" });

watch(wf.formContext, (ctx) => {
  console.log("server context:", ctx); // { email: "alice@example.com" }
});
```

### From dynamic form annotations

The most common consumer is a `@ui.form.fn.*` expression on the form
itself. The function receives `(data, ctx)`:

```atscript
@wf.context.pass 'email'
@ui.form.fn.title '(data, ctx) => `Enter the code sent to ${ctx.email}`'
export interface MfaPincodeForm { /* ... */ }
```

`data` is the current `formData.value`; `ctx` is the whitelisted
context. The full set of dynamic field functions is documented at
[Forms / Dynamic Fields](/forms/dynamic-fields).

Use this for:

- **Dynamic titles** — `"Welcome back, ${ctx.username}"`.
- **Dynamic submit labels** — `"Pay $${ctx.total}"`.
- **Conditional descriptions** — `"Sent to ${ctx.maskedPhone}"`.
- **Action labels** — `"Resend to ${ctx.email}"`.

## Display-only fields backed by context

When a step needs to **show** something the server computed — a TOTP
enrolment URI, a one-shot magic link, a masked phone number — without
asking the user to edit it, combine context-pass with a phantom field
typed as `ui.paragraph` and a `@ui.form.fn.value` resolver.

```atscript
@wf.context.pass 'totpUri'
@wf.context.pass 'magicLink'
@meta.label 'Activate TOTP & share invite link'
@ui.form.submit.text 'Continue'
export interface QrCopyDemoForm {
    @meta.label 'Scan with your authenticator app'
    @ui.form.fn.value '(v, data, ctx) => ctx.totpUri'
    @ui.form.component 'qr-code'
    totpUri: ui.paragraph

    @meta.label 'Magic link'
    @ui.form.fn.value '(v, data, ctx) => ctx.magicLink'
    @ui.form.component 'copy'
    magicLink: ui.paragraph
}
```

What each piece does:

- `@wf.context.pass 'totpUri' / 'magicLink'` whitelists the two keys
  into `formContext`. Without them, `ctx.totpUri` / `ctx.magicLink`
  would be `undefined` on the client.
- `ui.paragraph` marks the field as **phantom**. The form treats it as
  non-data chrome — no slot is allocated in `formData`, and the value
  never crosses back to the server on submit. Phantom values reach the
  renderer through `props.value`, not `props.model.value`.
- `@ui.form.fn.value` resolves the displayed value from the context.
  Combine with `@ui.form.component 'qr-code'` / `'copy'` from
  [`@atscript/vue-aooth`](/forms/aooth-components) — those components
  read `props.value ?? props.model?.value`, so the same renderer works
  for phantom and data-bound fields.

::: warning Field-level fn signature
Field-level functions are `(v, data, ctx, entry)`. Writing
`'(_, ctx) => ctx.totpUri'` silently routes `formData` into `ctx` and
the real context goes unread. Only **form-level** keys
(`@ui.form.fn.title`, `@ui.form.fn.description`,
`@ui.form.fn.submit.text`, `@ui.form.fn.submit.disabled`) use the
two-argument `(data, ctx)` shape. See [Dynamic Fields](/forms/dynamic-fields#scope-passed-to-every-function).
:::

When the resolved value should land in the bound data slot — because a
downstream column, audit log, or schema expects it — use a data field
with `@meta.readonly` + `@ui.form.fn.value` instead of a phantom one.
`AsField` resolves the function and writes the result into the bound
path through a watcher (see the "Readonly watcher" block in
`packages/vue-form/src/components/as-field.vue`). Phantom is the
cleaner shape whenever the value is purely display.

## What stays server-side

Anything **not** in `@wf.context.pass` never crosses the wire:

```ts
// Server-side context for the LoginCtx flow:
ctx.userId = 42; // ← not in @wf.context.pass — NEVER sent
ctx.otpCode = "123456"; // ← not in @wf.context.pass — NEVER sent
ctx.email = "..."; // ← whitelisted — sent
```

The framework defaults to _whitelist_ not _blacklist_ for exactly
this reason: forgetting to mark `otpCode` private would be a
catastrophic bug; forgetting to mark `email` public is a harmless
"the title shows 'your email'" fallback.

## When context shape changes between steps

A multi-step flow accumulates state — by step 3, `ctx.userId` exists;
in step 1 it doesn't. That's fine: the form's dynamic functions
should always be defensive about `ctx?.email`-style access.

When you store a context value into a durable store **shadow column**
(see [State Persistence](/workflows/state-persistence)) the same
rule applies — the field is optional (`?:`) because mid-flow rows
may not have the value yet.

## Where to go next

- [State Persistence](/workflows/state-persistence) — putting
  `@wf.store.fromContext` on a row column so context values are
  queryable from your admin UI.
- [Forms / Dynamic Fields](/forms/dynamic-fields) — the full
  `@ui.form.fn.*` toolbox that consumes `ctx`.
- [Recipes](/workflows/recipes) — flows that lean on context-driven
  dynamic UI.


---
URL: "ui.atscript.dev/workflows/finish-screens"
LLMS_URL: "ui.atscript.dev/workflows/finish-screens.md"
outline: "deep"
---

# Finish Screens

When a workflow terminates, the server returns a `WfFinished` envelope.
`<AsWfForm>` reads it, fires `@finished`, and — by default — renders an
`AsWfFinish` screen that drives the next user action: a redirect, a
countdown, a button choice, or just a final message.

This page documents the envelope shape, the workflow-author helpers
that produce it, the slot contract for customizing the rendering, and
the event contract for hooking the actions into your router.

## Why a unified terminal shape

Different workflows want different post-finish UX — sign-in wants a
silent redirect, a long-running task wants a countdown the user can
skip, a multi-outcome flow wants a choice screen. Without a shared
shape the client either renders nothing (forcing every consumer to
own the screen) or hardcodes one outcome (forcing the server to
write JavaScript). The envelope keeps the server in charge of intent
and lets the client render the corresponding UX without a custom
component per workflow.

## The envelope

```ts
interface WfFinished<TData = unknown> {
  finished: true;
  data?: TData;
  message?: WfMessage;
  next?: WfNext;
  aborted?: boolean;
  reason?: string;
}

interface WfMessage {
  level: "info" | "success" | "warn" | "error";
  text: string;
}

type WfNext =
  | { trigger: "immediate"; action: WfAction }
  | {
      trigger: "auto";
      timeoutMs: number;
      action: WfAction;
      skipButton?: { label: string; behavior?: "now" | "cancel" };
    }
  | {
      trigger: "manual";
      primary?: WfButton;
      options?: WfButton[];
    };

interface WfButton {
  label: string;
  action: WfAction;
}

type WfAction =
  | { type: "redirect"; target: string; reason?: string }
  | { type: "reload" }
  | { type: "dismiss" };
```

- **`finished: true`** — required marker. The HTTP adapter wraps bare
  step results to add it; the helpers below already include it, so
  wrapping is a no-op for them.
- **`data`** — your domain payload. Whatever the consumer reads on
  `@finished`. Type-parameterize via `WfFinished<MyShape>`.
- **`message`** — optional banner rendered at the top of the finish
  screen. Use for "you're signed in" / "submission saved" toasts that
  the screen itself shows for a beat before navigating.
- **`next`** — what to do next. Drives the rendering trigger.
- **`aborted` / `reason`** — soft-failure signal. Used together when
  the flow ends in a recoverable terminal state (`"reason: rate-limited"`).

When `next` is omitted, `AsWfFinish` just renders the `message` (if any)
and waits for the consumer to act. With `next` set, the rendering and
action wiring follow the rules below.

## Helpers

`@atscript/moost-wf` ships two helpers — `finishWf(opts?)` and
`abortWf(reason, opts?)` — that wrap `useWfFinished` from
`@moostjs/event-wf`. Both accept the same shared options bag:

```ts
interface FinishWfOpts<T = unknown> {
  data?: T;
  message?: WfMessage;
  next?: WfNext;
}

function finishWf<T = unknown>(opts?: FinishWfOpts<T>): void;
function abortWf(reason: string, opts?: FinishWfOpts): void;
```

Use them in place of raw `useWfFinished().set({ value: {...} })` whenever
possible — they build the envelope correctly and keep the wire shape
stable across upgrades.

### Terminal data

Domain payload, no transition UI. The client reads `data` on
`@finished` and is responsible for what happens next.

```ts
import { finishWf } from "@atscript/moost-wf";

@Step("invoice-submit-save")
async save(@WorkflowParam("input") input: InvoiceInput) {
  const id = await invoices.insertOne(input);
  finishWf({ data: { ok: true, id } });
}
```

### Message-only

Pure message — no data, no transition. Use when the only outcome is
"tell the user something."

```ts
finishWf({
  message: { level: "success", text: "We've sent a verification email." },
});
```

### Redirect (immediate or auto)

Set `next.trigger` to `"immediate"` for a redirect on mount, or
`"auto"` for a countdown + optional skip button.

```ts
// Immediate — `AsWfFinish` triggers the `navigate` prop on mount, no UI flashes by.
finishWf({
  next: {
    trigger: "immediate",
    action: { type: "redirect", target: "/dashboard", reason: "post-login" },
  },
});

// Auto — countdown ticks down, skip button fires the action immediately.
finishWf({
  message: { level: "success", text: "All set!" },
  next: {
    trigger: "auto",
    timeoutMs: 4000,
    action: { type: "redirect", target: "/dashboard" },
    skipButton: { label: "Go now" },
  },
});
```

`WfAction`'s `reason` field is propagated via `@action` for analytics or
branching. `skipButton.behavior` defaults to `"now"` (fire the action
immediately); set it to `"cancel"` to only clear the timer.

### Manual choice

`trigger: "manual"`. The user picks one of the buttons. Provide either a
`primary` (Enter-key target) or one or more `options`. An empty `manual`
shape with neither `primary` nor `options` produces an unactionable
screen — the renderer expects at least one button.

```ts
finishWf({
  message: { level: "info", text: "Submission queued. What's next?" },
  next: {
    trigger: "manual",
    primary: {
      label: "View submission",
      action: { type: "redirect", target: "/submissions/123" },
    },
    options: [
      { label: "Submit another", action: { type: "redirect", target: "/submit" } },
      { label: "Done", action: { type: "dismiss" } },
    ],
  },
});
```

When `primary` is omitted, all `options` render with equal visual
weight and the first option becomes the Enter-key target.

### Aborted soft-failure

`abortWf(reason, opts?)` sets `aborted: true` plus the reason; the same
`FinishWfOpts` bag lets you attach `data`, a `message`, or a `next`
action that takes the user away from the form.

```ts
import { abortWf } from "@atscript/moost-wf";

abortWf("rate-limited", {
  message: { level: "warn", text: "Too many attempts. Try again in 5 minutes." },
});
```

### Combining shapes

`FinishWfOpts` is one bag — combine `data`, `message`, and `next` as
needed (e.g. `manual` choice with terminal `data` AND a primary button):

```ts
finishWf({
  data: { receiptId: 42 },
  next: {
    trigger: "manual",
    primary: { label: "Print", action: { type: "reload" } },
    options: [{ label: "Done", action: { type: "dismiss" } }],
  },
});
```

## Rendering on the client

`<AsWfForm>` renders the finish screen automatically. The default
behaviour ships in `AsWfFinish` (Tier-2 swappable), wired to
`<AsWfForm>` so consumers get correct rendering without any
template work.

The three triggers:

- **`immediate`** — no DOM is rendered. The action fires on mount.
  Redirects call the `navigate` prop you pass to `<AsWfForm>`; if no
  prop is provided, the component falls back to
  `window.location.assign`. The user sees a screen-reader-only
  "Redirecting…" announcement and that's it.
- **`auto`** — a filled primary CTA (the skip button) whose
  background fills left-to-right with a `bg-black/20` darken overlay
  over `timeoutMs`, with a smaller muted countdown line ("Continuing
  in N…") centered underneath. The button **is** the progress
  indicator — there's no separate progress bar. Clicking it fires the
  action immediately (`behavior: 'now'`, the default) or only clears
  the timer (`behavior: 'cancel'`). The fill is CSS-driven via
  `@keyframes progress-fill` plus a `--progress-duration` custom
  property, so the bar animates smoothly regardless of the JS
  countdown's tick rate. If `skipButton` is omitted from the
  envelope, only the countdown text renders.
- **`manual`** — `message` banner + buttons. The primary button (if
  provided) gets initial focus and is the Enter-key target; options
  render alongside. If no `primary`, the first option is the
  Enter-key target.

## Customizing via slots

`<AsWfForm>` forwards five named scoped slots into `AsWfFinish`. Each
has a working default — override only the pieces you want to
restyle. Every slot scope includes a callback so your custom UI
keeps the action wiring without re-implementing the logic.

| Slot                  | Renders when                              | Scope                                                                                                                            |
| --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `wf.finished`         | Any finished envelope                     | `{ response, payload }` — full override; ignores the rest of the table                                                           |
| `wf.finish.message`   | `payload.message` is set                  | `{ message: WfMessage }`                                                                                                         |
| `wf.finish.countdown` | `next.trigger === 'auto'`                 | `{ secondsRemaining, totalSeconds, skip, cancel }` — `secondsRemaining` ticks 1/sec (250ms internally; integer transitions only) |
| `wf.finish.skip`      | `next.trigger === 'auto'` + `skipButton`  | `{ button: { label, behavior }, trigger }`                                                                                       |
| `wf.finish.primary`   | `next.trigger === 'manual'` with primary  | `{ button: WfButton, trigger }`                                                                                                  |
| `wf.finish.option`    | `next.trigger === 'manual'` (each option) | `{ button: WfButton, index: number, trigger }`                                                                                   |

Example — override the primary button with a design-system one,
keeping the trigger contract:

```vue
<AsWfForm path="/api/wf" name="checkout" :types="types" :navigate="navigate">
  <template #wf.finish.primary="{ button, trigger }">
    <MyBrandButton :variant="'filled'" @click="trigger">
      {{ button.label }}
    </MyBrandButton>
  </template>
</AsWfForm>
```

The `trigger` callback runs the action (redirect / reload / dismiss)
exactly as the default button would. Custom UI never needs to
re-implement the redirect-or-emit decision.

## Routing

`redirect` actions go through a `navigate` prop on `<AsWfForm>`. The
prop is a function that receives the target URL — your handler decides
cross-origin vs in-app routing.

```ts
import { useRouter } from "vue-router";
const router = useRouter();
const navigate = (url: string) => router.push(url);
```

```vue
<AsWfForm path="/api/wf" name="checkout" :types="types" :navigate="navigate" />
```

If no `navigate` prop is provided, `AsWfFinish` falls back to
`window.location.assign(url)`. In an SSR or non-browser context with
no prop and no browser `location`, it logs `console.error` and does
nothing — better than crashing the render path.

The same `navigate` handler can be passed to `@atscript/db-client`'s
`Client({ navigate })` option, so one navigation function covers both
workflow redirects and `processor: 'navigate'` DB actions.

## Events

`<AsWfForm>` (and the default `AsWfFinish`) emit two events when an
action runs:

```ts
defineEmits<{
  (e: "dismiss"): void;
  (e: "action", action: WfAction): void;
}>();
```

- **`@dismiss`** — fired for `action.type === 'dismiss'`. The flow
  stays on screen — the consumer decides what to do (close a modal,
  reset state, etc.).

- **`@action`** — fires before every action, including reloads and
  redirects. The `WfAction` payload includes the optional
  `reason` for analytics or telemetry, without intercepting
  navigation.

## Aborted flows

A workflow that calls `abortWf(reason)` still fires `@finished` on the
client — `aborted` and `reason` are exposed on the envelope alongside
`data`. Treat them like a soft-error: render a banner via the `message`
field (if you set one) or branch on `payload.aborted` inside the
`wf.finished` slot for full control.

## Reusing the progress-button primitive

The auto-mode skip button is built on a public `c8-progress` shortcut
family in `@atscript/ui-styles`. The same primitive composes any
"fills then fires" UI — hold-to-confirm CTAs, timed confirmations, any
button you want to double as its own progress indicator. The three
classes:

```html
<button
  class="c8-filled scope-primary c8-progress h-fingertip-m px-$m"
  :style="{ '--progress-duration': '4000ms' }"
>
  <span class="c8-progress-fill" />
  <span class="c8-progress-label">Confirm</span>
</button>
```

- `c8-progress` — adds `relative overflow-hidden`. Layer it on top of
  any `c8-*` base (`c8-filled`, `c8-flat`, `c8-light`).
- `c8-progress-fill` — absolutely-positioned `bg-black/20` overlay
  that animates `width 0% → 100%` over `--progress-duration` via the
  globally-registered `@keyframes progress-fill` (no JS).
- `c8-progress-label` — keeps the label in flow so the button doesn't
  collapse to its padding box. Required.

The keyframes are registered as a UnoCSS preflight by `asPresetVunor`,
so consumers don't have to register anything beyond installing the
preset. See [Styling — the as-\* shortcut system](/styling/shortcuts)
for the broader shortcut tree.

## Reference

- Types and helpers: `packages/moost-wf/src/wf-finished.ts`
- Default component: `packages/vue-wf/src/components/defaults/as-wf-finish.vue`
- Client wiring: `packages/vue-wf/src/components/as-wf-form.vue`

## Where to go next

- [Client: AsWfForm](/workflows/client) — props, emits, full slot
  list, custom fetch.
- [Server-Side Authoring](/workflows/server-authoring) — the
  surrounding decorator stack the helpers plug into.
- [Outlets & Resume](/workflows/outlets-resume) — `{ sent: true }`
  vs. `{ finished: true }` and how the two pause types interact.


---
URL: "ui.atscript.dev/workflows/form-input"
LLMS_URL: "ui.atscript.dev/workflows/form-input.md"
outline: "deep"
---

# Form Input & Validation

How a step receives validated form input, and how it re-renders the
same form with errors when validation fails. The handler stays
focused on business logic; the framework handles the envelope, the
validation, and the wire format.

## Two ways to receive input

### Manual: `@WorkflowParam("input")`

The lowest-level option, shown throughout
[Server-Side Authoring](/workflows/server-authoring):

```ts
interface WfInputEnvelope {
  action?: string;
  formData?: { username?: string; password?: string };
}

@Step("login-credentials")
async enterCredentials(
  @WorkflowParam("input") input: WfInputEnvelope | undefined,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  const formData = input?.formData;
  if (!formData?.username || !formData?.password) {
    throw useAtscriptWf(LoginForm).requireInput();
  }
  // ... use formData.username, formData.password ...
}
```

The wire envelope wraps user data in `{ action?, formData? }` — both
peers ride the workflow's `input` slot, which the engine wipes between
steps. `@WfInput()` and `useAtscriptWf(Type).resolveInput()` unwrap
`formData` for you; only the manual `@WorkflowParam("input")` form
exposes the envelope shape.

You write the empty-input guard, you decide when to re-pause. No
automatic validation — the handler sees raw client data.

### Decorator: `@WfInput()`

`@WfInput()` collapses the boilerplate into one parameter:

```ts
import { WfInput } from "@atscript/moost-wf";
import { LoginForm } from "./LoginForm.as";

@Step("login-credentials")
async enterCredentials(
  @WfInput() input: LoginForm,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  // input is validated and typed — auth.login can use it directly
  await this.auth.login(input.username, input.password);
}
```

The decorator does three things:

1. **Auto-pause** on first call (no input yet) — returns the
   serialized schema to the client; the handler body never runs.
2. **Auto-validate** subsequent calls against the form type. Any
   `@expect.*`, `@meta.required`, `string.email`, custom
   `@ui.form.validate` rule baked into the type fires automatically.
3. **Reject the input** with a `StepRetriableError` carrying the
   schema + field errors — the workflow engine catches it natively
   and re-pauses the same step with the new error map.

If validation fails, the framework re-pauses the workflow at the
same step with the field errors. The handler body is **not** called
— so by the time your code runs, the input is guaranteed valid for
that type's static constraints.

## Bailing out with custom errors

Validation that the `.as` type can't express — DB uniqueness checks,
auth failures, business-rule violations — uses
`useAtscriptWf(Type).requireInput(opts?)` to build the same
`StepRetriableError` the decorator throws. **Throw it** (don't
return) to re-pause with the schema + the error map.

```ts
import { useAtscriptWf, WfInput } from "@atscript/moost-wf";
import { LoginForm } from "./LoginForm.as";

@Step("login-credentials")
async enterCredentials(
  @WfInput() input: LoginForm,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  const user = await usersTable.findOne({ filter: { username: input.username } });
  if (!user || !verify(input.password, user.password)) {
    throw useAtscriptWf(LoginForm).requireInput({
      errors: { password: "Invalid username or password" },
    });
  }
  ctx.userId = user.id;
  return;
}
```

`requireInput()` accepts:

- `errors` — `Record<string, string>` keyed by field path. Special
  key `__form` is a top-level form-wide error.
- `formMessage` — convenience for `errors: { __form: '...' }`.
  Combine with `errors` to attach a form-wide message alongside
  field errors.

```ts
throw useAtscriptWf(LoginForm).requireInput({
  formMessage: "Account is suspended",
});
```

## Server-side validation errors

The same flow handles both kinds of errors uniformly:

| Error source                   | What the framework does                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| Type-level (`@expect.*`, etc.) | `@WfInput()` validates the input. On fail, throws `StepRetriableError`; engine re-pauses. |
| Business-level                 | Handler calls `throw useAtscriptWf(Type).requireInput({ errors: { field: 'msg' } })`.     |

Both produce the same wire response — `{ inputRequired: { payload,
transport, context: { errors: {...} } } }` — and the client renders
the same form with the new errors.

### Mid-handler validation: "email already taken"

A classic case the `.as` type can't express:

```ts
@Step("register-details")
async enterDetails(
  @WfInput() input: RegisterForm,
  @WorkflowParam("context") ctx: RegisterCtx,
) {
  const wf = useAtscriptWf(RegisterForm);

  const usernameTaken = await usersTable.findOne({ filter: { username: input.username } });
  if (usernameTaken) {
    throw wf.requireInput({ errors: { username: "Username already taken" } });
  }
  const emailTaken = await usersTable.findOne({ filter: { email: input.email } });
  if (emailTaken) {
    throw wf.requireInput({ errors: { email: "Email already registered" } });
  }

  // ... advance, hash password, etc. ...
}
```

Pass multiple errors in one map; they all light up at once on the
client:

```ts
throw useAtscriptWf(RegisterForm).requireInput({
  errors: {
    username: "Username already taken",
    email: "Email already registered",
  },
});
```

### Form-level (cross-field) errors

`formMessage` shows the error at the form's root, not attached to
any field:

```ts
throw useAtscriptWf(LoginForm).requireInput({
  formMessage: "Account is suspended",
});
```

The client's default form renders form-level errors at the top of
the form chrome (see [Forms / Validation](/forms/validation)).

## Same-form detection: preserving user input

The client tracks the serialized payload of the last-received form.
When the server returns the **same** form (same schema, same type
identity) — typically because validation failed and the same step is
re-pausing — the client:

- Keeps the existing `FormDef` and `formData` (no remount, no
  blanking).
- Updates `errors` to the new error map.
- Bumps `formKey` only when the schema _actually changes_.

User-typed values stay put. Only the errors flip.

This is invisible to step authors — just `throw wf.requireInput({...})`
and the client handles it.

## Composable-driven control

When you want to interleave action handling and input validation
explicitly (without the `@WfInput` policy matrix), call
`useAtscriptWf()` directly:

```ts
import { useAtscriptWf } from "@atscript/moost-wf";
import { LoginForm } from "./LoginForm.as";

@Step("login-credentials")
async enterCredentials(@WorkflowParam("context") ctx: LoginCtx) {
  const wf = useAtscriptWf(LoginForm);
  const action = wf.resolveAction();
  if (action === "forgot") {
    await this.sendPasswordReset();
    return;
  }
  const input = wf.resolveInput();
  // ... auth ...
}
```

The three helpers are pure and independent:

- `resolveInput(opts?)` — validates `state.input` and returns it
  typed; throws `StepRetriableError` on missing/invalid input.
- `resolveAction()` — returns the action name or `undefined`;
  throws `StepRetriableError` for unknown actions.
- `requireInput(opts?)` — builds the retriable error for custom
  branches.

`@WfInput()` is the same composable plus the action-vs-input policy
matrix from [Actions](/workflows/actions).

## Action validation differs

Form data sent with an _action_ (see [Actions](/workflows/actions))
validates with `partial: "deep"` — the framework only checks the
fields that are present, so a "save draft" action with half a form
filled in passes. Plain form submits validate the whole shape.

`@WfInput()` applies this policy automatically based on the action's
declaration (`@ui.form.action` vs `@wf.action.withData`); you don't
write a separate guard.

## Where to go next

- [Actions](/workflows/actions) — alt buttons that send the same
  form data + an action name.
- [Context Passing](/workflows/context) — making server context
  available to the rendered form (e.g. `ctx.email` in the page
  title).
- [Forms / Validation](/forms/validation) — the underlying client
  validation model that surfaces these errors.


---
URL: "ui.atscript.dev/workflows/hello-world"
LLMS_URL: "ui.atscript.dev/workflows/hello-world.md"
outline: "deep"
---

# Hello World

A two-step workflow end-to-end: the server asks for a name, then
returns a greeting. Demonstrates the full round-trip without any of
the production-flow noise (auth, DB, MFA).

## Install

```bash
# Server
pnpm add moost @moostjs/event-http @moostjs/event-wf @atscript/moost-wf

# Client
pnpm add @atscript/vue-form @atscript/vue-wf
```

Both packages depend on `@atscript/core` + `@atscript/typescript` for
`.as` compilation. Make sure your `atscript.config.*` registers the
`moost-wf` plugin so the `@wf.*` annotations resolve:

```ts
// atscript.config.ts
import wfPlugin from "@atscript/moost-wf/plugin";

export default {
  plugins: [wfPlugin()],
};
```

See [atscript.dev](https://atscript.dev) for `asc` CLI setup.

## 1. Define the form types

`shared/forms/hello.as` — shared between server and client; the
server uses it as input validation, the client renders it.

```atscript
@meta.label 'Hello'
@ui.form.submit.text 'Say hi'
export interface HelloForm {
    @meta.label 'Your name'
    @ui.form.placeholder 'World'
    @meta.required 'Name is required'
    @expect.minLength 1, 'At least 1 character'
    name: string
}
```

That is the entire schema. The submit button label, the field label,
the placeholder, the required rule, the min-length validation — all
declared once, lifted out by the build, consumed by both ends.

## 2. Server: the workflow

`server/workflows/hello.workflow.ts`:

```ts
import { Controller } from "moost";
import { Workflow, Step, WorkflowSchema, WorkflowParam, outletHttp } from "@moostjs/event-wf";
import { serializeFormSchema, extractPassContext, finishWf } from "@atscript/moost-wf";
import { HelloForm } from "../../shared/forms/hello.as";

interface HelloCtx {
  name?: string;
}

@Controller()
export class HelloWorkflow {
  @Workflow("hello")
  @WorkflowSchema<HelloCtx>([{ id: "ask-name" }, { id: "greet" }])
  flow() {}

  @Step("ask-name")
  ask(
    @WorkflowParam("input") input: { name?: string } | undefined,
    @WorkflowParam("context") ctx: HelloCtx,
  ) {
    if (!input?.name) {
      return outletHttp(serializeFormSchema(HelloForm), extractPassContext(HelloForm, ctx));
    }
    ctx.name = input.name;
    return;
  }

  @Step("greet")
  greet(@WorkflowParam("context") ctx: HelloCtx) {
    finishWf({ data: { message: `Hello, ${ctx.name}!` } });
    return;
  }
}
```

`createAsHttpOutlet()` (registered below) wraps the `inputRequired`
envelope automatically, so the step body stays at one line:
`outletHttp(schema, context)`. A thin helper that also merges
field-level errors into the context is shown in
[Server-Side Authoring](/workflows/server-authoring).

### Mount the workflow on a Moost app

`server/main.ts`:

```ts
import { Moost } from "moost";
import { MoostHttp, Post } from "@moostjs/event-http";
import { MoostWf, EncapsulatedStateStrategy, type WfOutletTriggerDeps } from "@moostjs/event-wf";
import { createAsHttpOutlet, handleAsOutletRequest } from "@atscript/moost-wf";
import { Controller } from "moost";
import { HelloWorkflow } from "./workflows/hello.workflow";

@Controller()
class WfController {
  constructor(private readonly wf: MoostWf) {}

  @Post("wf")
  async handle() {
    const wfApp = this.wf.getWfApp();
    const deps: WfOutletTriggerDeps = {
      start: (schemaId, ctx, opts) => wfApp.start(schemaId, ctx as never, { input: opts?.input }),
      resume: (state, opts) => wfApp.resume(state as never, { input: opts?.input }),
    };
    return handleAsOutletRequest(
      {
        allow: ["hello"],
        state: new EncapsulatedStateStrategy({
          secret: Buffer.from(process.env.WF_SECRET!, "hex"),
        }),
        outlets: [createAsHttpOutlet()],
        token: { read: ["body"], write: "body", name: "wfs" },
      },
      deps,
    );
  }
}

const app = new Moost();
void app.adapter(new MoostHttp()).listen(3000);
app.adapter(new MoostWf());
app.registerControllers(WfController, HelloWorkflow);
void app.init();
```

The HTTP controller forwards every `POST /wf` to the workflow engine
via `handleAsOutletRequest` — a thin wrapper around
`handleWfOutletRequest` that supplies the `finished: true` marker
`<AsWfForm>` reads, so step handlers can return plain domain data via
`finishWf({ data })`. The wrapper reads the body, routes to start vs
resume, runs the matched step, and serializes the outlet response. We use `EncapsulatedStateStrategy` here: the state token
is a signed, self-contained blob; no DB needed. See
[State Persistence](/workflows/state-persistence) for the durable
option.

## 3. Client: mount the form

`src/views/HelloView.vue`:

```vue
<script setup lang="ts">
import { ref } from "vue";
import { AsWfForm } from "@atscript/vue-wf";
import { createDefaultTypes } from "@atscript/vue-form";

const types = createDefaultTypes();
const greeting = ref<string | null>(null);

function onFinished(response: unknown) {
  greeting.value = (response as { message: string }).message;
}
</script>

<template>
  <div v-if="greeting">{{ greeting }}</div>
  <AsWfForm v-else path="/wf" name="hello" :types="types" @finished="onFinished" />
</template>
```

Nine lines of Vue. `<AsWfForm>` posts `{ wfid: "hello" }` on mount,
the server returns the `HelloForm` schema, the client renders it,
the user submits, the server returns `{ finished: true, message }`,
and `@finished` fires.

## The round-trip, traced

The wire conversation, abbreviated:

```http
POST /wf
{ "wfid": "hello" }
```

→

```json
{
  "inputRequired": {
    "payload": { "$as": "...serialized HelloForm metadata..." },
    "transport": "http",
    "context": {}
  },
  "wfs": "<state-token>"
}
```

Client deserializes `payload` back into a runtime atscript type,
builds a `FormDef`, renders the form. User types `World`, submits:

```http
POST /wf
{ "wfs": "<state-token>", "input": { "name": "World" } }
```

→

```json
{
  "finished": true,
  "message": "Hello, World!"
}
```

The state token (`wfs`) is the entire workflow state in encrypted
form. Lose it and the flow is gone — but with `EncapsulatedStateStrategy`
there is no server-side row to clean up either.

## Next steps

- [Server-Side Authoring](/workflows/server-authoring) — the full
  decorator stack, branching, error returns.
- [Form Input & Validation](/workflows/form-input) — `@WfInput()`,
  validation errors that re-render the same form.
- [Client: AsWfForm](/workflows/client) — props, slots, the
  composable form.


---
URL: "ui.atscript.dev/workflows/outlets-resume"
LLMS_URL: "ui.atscript.dev/workflows/outlets-resume.md"
outline: "deep"
---

# Outlets & Resume

A workflow doesn't always pause for _form input_. Sometimes it
pauses for an **external event**: an email link clicked, a webhook
fired, an approval submitted from another app. That's what
**outlets** are for, and **resume** is how the flow picks up where
it left off — possibly in a different browser session entirely.

## What an outlet is

An outlet is a side-channel the workflow engine writes to when a
step decides to pause for something other than form input. The HTTP
outlet (which we've used for input forms) is one of several:

| Outlet   | Where it sends                 | Used for                                 |
| -------- | ------------------------------ | ---------------------------------------- |
| HTTP     | The current HTTP response body | Request form input (the round-trip)      |
| Email    | An email sender                | Magic links, confirmation, OTP delivery  |
| (custom) | Anywhere — webhooks, SMS, …    | Whatever your step calls `outletX()` for |

When a step returns an outlet payload that's **not HTTP**, the
client sees `{ sent: true }` or `{ outlet: "name" }` in its current
HTTP response. From the browser's perspective, the flow is _done_.
But on the server it's _paused_, waiting for an out-of-band
resumption.

## A typical email-magic-link flow

A `users/invite` flow:

```
1. Admin posts "invite alice@example.com as viewer"
   → server: insert pending user, persist context, advance.
2. Server step calls outletEmail(email, template, payload)
   → email outlet writes Set-Cookie? No: it dispatches the email
     (with ?wfs=<uuid> in the magic-link URL) and pauses the flow.
   → HTTP response: { sent: true, wfs: <uuid> }
3. Admin's screen: "Invite sent."
4. Alice clicks the email link "https://app/invite?wfs=<uuid>"
   → her browser loads the app, app extracts wfs from URL.
   → <AsWfForm :initialToken="wfs" name="users/invite" />
5. Client POSTs { wfs } to /wf — no wfid, just the token.
   → engine looks up the handle, resumes the paused step.
6. Server returns the next form (invite-accept) — Alice fills in
   username + password, submits.
7. Server: complete user record, issue session cookie, done.
```

The token (`wfs`) does two jobs: it identifies the paused workflow,
and it serves as a single-use credential (the email recipient
proves they got the email by holding the token).

## Returning an outlet from a step

The engine ships built-in helpers; the email outlet is the one used
in the demo:

```ts
import { outletEmail, type WfOutletRequest } from "@moostjs/event-wf";

@Step("invite-send")
@StepTTL(24 * 60 * 60 * 1000) // token expires in 24h
sendInvite(@WorkflowParam("context") ctx: InviteCtx) {
  // First run → emit the email outlet, the engine persists state + pauses.
  // Resume run (invitee POSTs with wfs) → advance past this step.
  if (ctx.inviteEmailSent) return;
  ctx.inviteEmailSent = true;
  return outletEmail(ctx.email!, "user-invite", {
    userId: ctx.userId,
    roleId: ctx.roleId,
  }) as { inputRequired: WfOutletRequest };
}
```

`outletEmail(toAddress, templateId, payload)` builds an outlet
request. The email outlet (registered on the controller — see below)
hands the request to your sender, which composes and sends the
email. The URL inside the email embeds `?wfs=<handle>`.

The `if (ctx.inviteEmailSent) return` guard is essential: when Alice
resumes, the engine re-enters this step, and we must _not_ send the
invite a second time. Flip a flag in context on first run, check it
on resume.

`@StepTTL(ms)` from `@moostjs/event-wf` sets a per-step expiry: the
row gets `expiresAt = now + ms`. After that window, the resume
request returns an error.

## Registering outlets on the controller

The HTTP dispatcher registers every outlet your flows use:

```ts
import { createEmailOutlet } from "@moostjs/event-wf";
import { createAsHttpOutlet, handleAsOutletRequest } from "@atscript/moost-wf";
import { consoleEmailSender } from "../workflows/email-sender";

return handleAsOutletRequest(
  {
    allow: ALLOWED_WORKFLOWS,
    state: handleStrategy,
    outlets: [createAsHttpOutlet(), createEmailOutlet(consoleEmailSender)],
    token: { read: ["body", "query", "cookie"], write: "body", name: "wfs" },
  },
  deps,
);
```

`createAsHttpOutlet()` is the canonical HTTP outlet for atscript-ui
workflows — it wraps generic form payloads in the
`{ inputRequired: { payload, transport, context } }` envelope the
`<AsWfForm>` client decodes. Payloads that already carry one of the
client's root-level routing keys — `finished`, `sent`, `outlet`, or
`error` — pass through at the response root (merged with `context`
if any), so `outletHttp({ outlet: "awaiting-payment" })` for a
webhook pause, `outletHttp({ error: { message } })`, etc. continue
to work without registering a separate outlet.

`handleAsOutletRequest` is the matching trigger: a thin wrapper
around `handleWfOutletRequest` that supplies the `finished: true`
marker `<AsWfForm>` reads when a step calls `finishWf({ data })`
(from `@atscript/moost-wf`). Pass-through for non-object
responses (redirect's empty-string body, primitives), arrays, and
already-marked envelopes (`inputRequired` / `finished` / `error` /
`sent` / `outlet`). If you need a bare HTTP outlet + trigger for
non-`<AsWfForm>` consumers (a custom JS client, an inline-data
response, …), use `createHttpOutlet` and `handleWfOutletRequest`
from `@moostjs/event-wf` directly — they flatten payload + context
onto the response root unconditionally and leave the shape to you.

`createEmailOutlet(sender)` takes a sender — your function that
actually composes + dispatches the email. A `consoleEmailSender` that
just logs the link to stdout is fine for development; production
plugs in SES, SendGrid, Postmark.

## Token transport for resume

The `token` config on `handleAsOutletRequest` controls how the token
crosses the wire on _resume_. Three places it can live:

| Transport | Read                 | Write                    | Use when                                             |
| --------- | -------------------- | ------------------------ | ---------------------------------------------------- |
| `body`    | JSON body, key `wfs` | JSON response, key `wfs` | Default. Token lives only in memory; lost on reload. |
| `cookie`  | `Cookie: wfs=...`    | `Set-Cookie: wfs=...`    | Survives page reload. Same browser only.             |
| `query`   | `?wfs=...`           | Append to redirect URLs  | Magic links — URL-shareable; single-use.             |

`token.read` is a list, so the same endpoint can accept all three.
`token.write` is the format the server hands back on every response.

Configured globally on the controller — the _client_ picks how to
read the initial token via `<AsWfForm tokenTransport="...">` or the
`initialToken` prop (see below).

## The client side: resuming

### Option A: `initialToken` prop

The cleanest: the host route knows where the token lives (Vue Router
param, app state, query, …) and hands it to the form:

```vue
<script setup lang="ts">
import { useRoute } from "vue-router";
import { AsWfForm } from "@atscript/vue-wf";
import { createDefaultTypes } from "@atscript/vue-form";

const route = useRoute();
const types = createDefaultTypes();
const wfs = route.query.wfs as string;
</script>

<template>
  <AsWfForm
    path="/api/wf"
    name="users/invite"
    :initial-token="wfs"
    :types="types"
    @finished="onFinished"
  />
</template>
```

`initialToken` is included in the first request, so the server
resumes the paused flow instead of starting a new one. Works
regardless of `tokenTransport`.

### Option B: `tokenTransport: "query"` auto-detection

If the token sits in `window.location.search`, the form auto-reads
it on mount:

```vue
<AsWfForm path="/api/wf" name="users/invite" token-transport="query" :types="types" />
```

The composable's `readInitialToken()` pulls `?wfs=...` from the URL
and seeds the first request.

### Option C: `tokenTransport: "cookie"`

The browser sends the cookie automatically; the form just mounts. No
token wiring at all:

```vue
<AsWfForm path="/api/wf" name="auth/login" token-transport="cookie" :types="types" />
```

Good for "save and continue later" on the same machine.

## How resume works on the wire

On resume, the client posts **just the token**, no `wfid`:

```http
POST /wf
{ "wfs": "<uuid>" }
```

The engine:

1. Looks up the handle in the store (`HandleStateStrategy.consume`
   → `wfStore.getAndDelete`).
2. Reads `state.schemaId` to know which workflow.
3. Re-runs the paused step (which usually advances past its
   `outletX` call thanks to the context flag).
4. Continues until the next pause or finish.

The race-safe `getAndDelete` (see [State Persistence](/workflows/state-persistence#race-safe-consume-getanddelete))
ensures two simultaneous clicks on the same link only resume once.

Common pitfall: the token is single-use by default. The flow's
_next_ outlet request mints a new token. If your client throws away
the new token (e.g. because it didn't expect another round-trip),
the user is stuck. `<AsWfForm>` handles this automatically — it
reads the new `wfs` off every response.

## Combining outlets and form steps

A real flow mixes both — email pause, then form input, then another
email pause:

```ts
@Workflow("users/invite")
@WorkflowSchema<InviteCtx>([
  { id: "invite-start" },      // admin form
  { id: "invite-send" },        // email outlet → pause
  { id: "invite-accept" },      // invitee form
  { id: "invite-issue-session" }, // finish
])
```

From the admin's browser:

- POST start → form (invite-start).
- POST input → next step (`invite-send` emits email, pauses).
- Admin sees `{ sent: true, wfs: <uuid> }`.

Hours later, from Alice's browser via magic link:

- POST `{ wfs }` → engine resumes at `invite-send`. The
  `ctx.inviteEmailSent` flag is set, so the step `return`s.
- Engine advances to `invite-accept` → emits the form.
- Alice fills it in, submits.
- Engine advances to `invite-issue-session` → the step writes the
  session cookie and calls `finishWf({ data })`.
- Alice sees `@finished` with the session payload.

## Custom outlets

`createXxxOutlet(...)` is just a function that converts your step's
return value into an `WfOutletRequest`. Roll your own when you need
SMS, push, Slack, a webhook — anything that's _not_ the current HTTP
response.

The pattern: define an `outletX(args)` helper that returns
`{ outlet: "name", payload: ... }`; register `createXOutlet(sender)`
on the controller; the engine routes requests to your sender and
emits `{ outlet: "name" }` (or `{ sent: true }`) to the client.

See [@moostjs/event-wf docs](https://moost.org) for the full outlet
contract.

## Where to go next

- [State Persistence](/workflows/state-persistence) — durable
  storage required for any outlet flow that has to survive process
  restart.
- [Recipes](/workflows/recipes) — the invite + register pattern
  end-to-end.
- [moost.org](https://moost.org) — the underlying workflow
  engine and outlet primitives.


---
URL: "ui.atscript.dev/workflows/recipes"
LLMS_URL: "ui.atscript.dev/workflows/recipes.md"
outline: "deep"
---

# Recipes

Production-shaped flows built from the primitives in the preceding
pages.

## Login + MFA

The canonical conditional-branch flow. Three steps; the middle one
runs only if the user has MFA enabled.

**What's interesting:**

- One `condition: needsMfa` on a single step changes the flow shape
  without touching the other steps.
- The OTP code is dispatched **inline** (`console.log` in the demo;
  email/SMS in production) — _not_ via the email outlet — because
  emitting an outlet would pause the workflow and prevent the next
  form from rendering in the same response.
- The OTP form whitelists `email` via `@wf.context.pass` so the
  title can read "Enter the code sent to alice@example.com".
- Field-level error (`{ password: "Invalid credentials" }`) and
  form-level error (`{ __form: "Account is suspended" }`) both
  re-render the same form without remounting; user-typed values
  stick.

**Sketch:**

```ts
@WorkflowSchema<LoginCtx>([
  { id: "login-credentials" },
  { id: "login-verify-otp", condition: (ctx) => !!ctx.mfaEnabled },
  { id: "login-issue-session" },
])
```

```atscript
@wf.context.pass 'email'
@meta.label 'Verify Identity'
@ui.form.fn.title '(data, ctx) => `Enter the code sent to ${ctx.email}`'
export interface MfaPincodeForm {
    @meta.required 'Code is required'
    @expect.minLength 6, '6 digits expected'
    code: string
}
```

See [Server-Side Authoring](/workflows/server-authoring) and
[Context Passing](/workflows/context) for the full mechanics.

## Sign-up with email verification

A linear four-step flow that combines server-side uniqueness checks
with OTP verification.

**What's interesting:**

- Two consecutive forms (`RegisterForm`, then `OtpForm`) — same
  pattern as login, no condition branch.
- The first step does **mid-handler validation**: checks the DB
  for an existing username/email and re-pauses with field-specific
  errors (`{ email: "Email already registered" }`).
- The password is hashed in step 1 (`enterDetails`), stored in
  `ctx.passwordHash`/`ctx.passwordSalt`, and persisted into the
  user row in step 3 (`createUser`) — never re-validated, never
  re-entered.
- Like login, OTP is dispatched inline so the next form ships in
  the same response.

**Sketch:**

```ts
import { WfInput, useAtscriptWf } from "@atscript/moost-wf";

@Step("register-details")
async enterDetails(
  @WfInput() input: RegisterForm,
  @WorkflowParam("context") ctx: RegisterCtx,
) {
  const wf = useAtscriptWf(RegisterForm);

  if (await usersTable.findOne({ filter: { username: input.username } })) {
    throw wf.requireInput({ errors: { username: "Username already taken" } });
  }
  if (await usersTable.findOne({ filter: { email: input.email } })) {
    throw wf.requireInput({ errors: { email: "Email already registered" } });
  }

  const pw = await hashPassword(input.password);
  ctx.username = input.username;
  ctx.email = input.email;
  ctx.passwordHash = pw.hash;
  ctx.passwordSalt = pw.salt;
  ctx.otpCode = String(Math.floor(100000 + Math.random() * 900000));
  // ... send OTP inline ...
  return;
}
```

See [Form Input & Validation](/workflows/form-input) for the
re-pause-with-errors mechanics.

## Invite + register (email magic link)

The flagship outlet flow. Two browser sessions, one workflow.

**What's interesting:**

- Uses `HandleStateStrategy` + `AsWfStore` for durable state —
  the magic link might be clicked tomorrow.
- Step 2 (`invite-send`) emits an email outlet; the admin's
  browser sees `{ sent: true }` and the flow pauses.
- The invitee clicks the link `https://app/invite?wfs=<uuid>`,
  the SPA mounts `<AsWfForm :initial-token="wfs" name="users/invite">`,
  and the engine resumes at `invite-send` (which `return`s thanks
  to the `ctx.inviteEmailSent` flag).
- `@StepTTL(24 * 60 * 60 * 1000)` puts a 24-hour expiry on the
  invite — `wfStore.cleanup()` reaps expired rows on a timer.
- Shadow columns (`@wf.store.fromContext 'email'`, `'roleName'`)
  mirror context onto the row so an admin UI can list "pending
  invites for alice@example.com" without scanning JSON blobs.
- Admin gate on step 1: inline `useSession()` check — arbac
  interceptors don't auto-cover WF steps.

**Sketch:**

```ts
@Workflow("users/invite")
@WorkflowSchema<InviteCtx>([
  { id: "invite-start" },        // admin form
  { id: "invite-send" },          // email outlet → pause
  { id: "invite-accept" },        // invitee form
  { id: "invite-issue-session" },// finish, set cookie
])
flow() {}

@Step("invite-send")
@StepTTL(24 * 60 * 60 * 1000)
sendInvite(@WorkflowParam("context") ctx: InviteCtx) {
  if (ctx.inviteEmailSent) return;
  ctx.inviteEmailSent = true;
  return outletEmail(ctx.email!, "user-invite", { userId: ctx.userId, roleId: ctx.roleId });
}
```

```atscript
import { AsWfStateRecord } from '@atscript/moost-wf/store.as'

@db.table 'wf_states'
export interface WfStateRow extends AsWfStateRecord {
    @meta.id @db.default.uuid
    id: string

    @meta.label 'Invite Email'
    @wf.store.fromContext 'email'
    @db.index.plain 'email_idx'
    inviteEmail?: string

    @meta.label 'Invite Role'
    @wf.store.fromContext 'roleName'
    @db.index.plain 'role_idx'
    inviteRole?: string
}
```

The invitee side:

```vue
<script setup lang="ts">
import { useRoute } from "vue-router";
import { AsWfForm } from "@atscript/vue-wf";
import { createDefaultTypes } from "@atscript/vue-form";

const route = useRoute();
const wfs = route.query.wfs as string;
const types = createDefaultTypes();
</script>

<template>
  <AsWfForm
    path="/api/wf"
    name="users/invite"
    :initial-token="wfs"
    :types="types"
    @finished="onFinished"
  />
</template>
```

See [Outlets & Resume](/workflows/outlets-resume) and
[State Persistence](/workflows/state-persistence) for the full
pattern.

## Multi-step checkout

Skeleton for an e-commerce checkout: collect address, payment,
confirm. Conditional payment step if the cart is not free.

**What's interesting:**

- Three forms in a row, each with its own validation. The first
  pulls country / state lists via the FK value-help mechanism
  (`@db.rel.FK` on the address fields → AsRef component).
- Payment step is **conditional** — skipped if `ctx.totalCents === 0`
  (free promo, gift, …) — same single-line predicate as the MFA
  branch.
- The confirm form is read-only: render the cart summary with
  context-passed values (`@wf.context.pass 'cartSummary'`,
  `@wf.context.pass 'totalCents'`), no editable fields, just one
  "Place order" submit.
- Action with data: a "Save Draft" button on the address step
  posts whatever's been typed so far (deep-partial validated)
  to `ctx.draftAddress`, lets the user come back later.
- Durable state strategy (`HandleStateStrategy`) so abandoned
  carts can be resumed by email.

**Sketch:**

```ts
interface CheckoutCtx {
  cartId: number;
  totalCents: number;
  address?: AddressInput;
  payment?: PaymentToken;
  draftAddress?: Partial<AddressInput>;
  cartSummary?: { items: Array<{ name: string; qty: number; cents: number }> };
}

@Workflow("checkout/place-order")
@WorkflowSchema<CheckoutCtx>([
  { id: "checkout-address" },
  { id: "checkout-payment", condition: (ctx) => ctx.totalCents > 0 },
  { id: "checkout-confirm" },
])
flow() {}

@Step("checkout-address")
async address(
  @WorkflowParam("context") ctx: CheckoutCtx,
  @WfAction(AddressForm) action: string | undefined,
  @WfInput({ pass: true }) input?: AddressForm,
) {
  const wf = useAtscriptWf(AddressForm);
  if (action === "saveDraft") {
    ctx.draftAddress = input ?? {};
    throw wf.requireInput(); // re-render same form, no errors
  }
  ctx.address = input!;
  return;
}
```

```atscript
@wf.context.pass 'cartSummary'
@wf.context.pass 'totalCents'
@meta.label 'Confirm Order'
@ui.form.submit.text 'Place Order'
@ui.form.fn.title '(data, ctx) => `Total: $${(ctx.totalCents / 100).toFixed(2)}`'
export interface ConfirmForm {
    // Read-only fields rendered from context, or just no fields at all
    // and a custom #form.before slot that shows the cart summary.
}
```

The "address with FK lookups" relies on
[Forms / Field Types](/forms/field-types) and the `clientFactory`
prop on `<AsWfForm>` — drop in the same client your forms layer
uses elsewhere.

## Putting it together

All four recipes share the same toolbox:

- `.as` types as the single source of truth.
- `@WorkflowSchema` for linear or branched flow shape.
- `@WfInput` + `useAtscriptWf().requireInput()` for validation +
  re-render-same-form.
- `@WfAction` for plain actions (resend, forgot, save draft).
- `@wf.context.pass` for safe context exposure.
- `AsWfStore` + shadow columns when state has to outlive the
  request.
- `outletEmail` / `outletHttp` / custom outlets for non-form
  pauses.

Pick one recipe, copy its skeleton, swap out the forms.

## Where to go next

- [Hello World](/workflows/hello-world) — strip every recipe down
  to two steps to see the moving parts.
- [Server-Side Authoring](/workflows/server-authoring) — the
  decorator stack reference.
- [Client: AsWfForm](/workflows/client) — the full client API.


---
URL: "ui.atscript.dev/workflows/server-authoring"
LLMS_URL: "ui.atscript.dev/workflows/server-authoring.md"
outline: "deep"
---

# Server-Side Authoring

How to declare a workflow on the server: the decorator stack, schema
with conditional branches, step return semantics, app wiring.

The reference flow used throughout this page is a typical login
workflow.

## The decorator stack

```ts
import { Controller } from "moost";
import { Workflow, Step, WorkflowSchema, WorkflowParam } from "@moostjs/event-wf";

interface LoginCtx {
  userId?: number;
  mfaEnabled?: boolean;
  otpCode?: string;
}

const needsMfa = (ctx: LoginCtx) => !!ctx.mfaEnabled;

@Controller()
export class LoginWorkflow {
  @Workflow("auth/login")
  @WorkflowSchema<LoginCtx>([
    { id: "login-credentials" },
    { id: "login-verify-otp", condition: needsMfa },
    { id: "login-issue-session" },
  ])
  flow() {}

  @Step("login-credentials")
  async enterCredentials(/* ... */) {}

  @Step("login-verify-otp")
  verifyOtp(/* ... */) {}

  @Step("login-issue-session")
  issueSession(/* ... */) {}
}
```

Five decorators do all the work:

| Decorator                            | Where          | What                                                                                                                                                   |
| ------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@Controller()`                      | class          | Standard Moost — makes the class DI-discoverable.                                                                                                      |
| `@Workflow("id")`                    | method         | Declares this controller method as a workflow root. The `id` is what clients pass as `wfid` (e.g. `wfid: "auth/login"`).                               |
| `@WorkflowSchema<Ctx>([…])`          | same method    | Lists the steps and any `condition?: (ctx) => boolean`. The engine evaluates each condition just before executing that step; false skips it.           |
| `@Step("id")`                        | sibling method | Implements one step. The `id` matches a `WorkflowSchema` entry.                                                                                        |
| `@WorkflowParam("input"\|"context")` | step arg       | Injects the current request input or the mutable context object. `input` is whatever the client posted under `input`; `context` is the per-flow state. |

The `flow()` method that carries `@Workflow` + `@WorkflowSchema` is
usually empty — its body is never called. The decorators just attach
the metadata; the engine reads it and dispatches `@Step` methods in
order.

## Linear vs branched flows

A linear flow just lists steps:

```ts
@WorkflowSchema<HelloCtx>([
  { id: "ask-name" },
  { id: "greet" },
])
```

A branched flow uses `condition`:

```ts
@WorkflowSchema<LoginCtx>([
  { id: "login-credentials" },
  { id: "login-verify-otp", condition: needsMfa },
  { id: "login-issue-session" },
])
```

`needsMfa(ctx)` runs **just before** `login-verify-otp` is about to
execute. If it returns false, the engine skips the step and advances
to `login-issue-session`. The condition reads from the same `context`
object the steps mutate, so a step can flip a flag and the next
condition picks it up.

Conditions stack: you can declare three optional steps in a row, each
with its own predicate, and only the matching subset runs.

## Step return semantics

Three things a step can do:

### 1. Request input (pause)

The recommended path is the `@WfInput()` decorator — see
[Form Input & Validation](/workflows/form-input). It auto-validates
the input against the schema, auto-pauses on missing/invalid input,
and lets the handler body focus on business logic:

```ts
import { WfInput, useAtscriptWf } from "@atscript/moost-wf";

@Step("login-credentials")
async enterCredentials(
  @WfInput() input: LoginForm,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  // input is schema-validated; reach the body only with valid input
  const user = await usersTable.findOne({ filter: { username: input.username } });
  if (!user || !verify(input.password, user.password)) {
    throw useAtscriptWf(LoginForm).requireInput({
      errors: { password: "Invalid credentials" },
    });
  }
  ctx.userId = user.id;
}
```

`useAtscriptWf(Type).requireInput({ errors? , formMessage? })` builds
a `StepRetriableError` carrying the schema + field errors; the
workflow engine catches it natively and re-pauses the same step. See
[Form Input & Validation](/workflows/form-input) for the full
contract.

Prefer the composable directly when you need to interleave action
handling with validation:

```ts
import { useAtscriptWf } from "@atscript/moost-wf";

@Step("login-credentials")
async enterCredentials(@WorkflowParam("context") ctx: LoginCtx) {
  const wf = useAtscriptWf(LoginForm);
  if (wf.resolveAction() === "forgot") {
    await this.sendPasswordReset();
    return;
  }
  const input = wf.resolveInput();
  // ... validate credentials ...
}
```

### 2. Advance to the next step

`return` (or `return undefined`) with no outlet — the engine just
moves on:

```ts
@Step("login-credentials")
async enterCredentials(/* ... */) {
  // ... validation passed ...
  ctx.userId = user.id;
  ctx.mfaEnabled = !!user.mfaEnabled;
  return; // → next step's condition is evaluated, then it runs
}
```

### 3. Finish the workflow

Call `finishWf(opts?)` (or `abortWf(reason, opts?)` for a soft failure)
from `@atscript/moost-wf` to build the `WfFinished` envelope and end
the flow:

```ts
import { finishWf } from "@atscript/moost-wf";

@Step("login-issue-session")
issueSession(@WorkflowParam("context") ctx: LoginCtx) {
  finishWf({
    data: { ok: true, user: { username: ctx.username! } },
    message: { level: "success", text: "Signed in." },
  });
  return;
}
```

`opts.data` becomes the envelope's typed payload the client sees on
`@finished`. `opts.message` / `opts.next` drive the terminal screen
(`<AsWfFinish>`) — see [Finish Screens](/workflows/finish-screens) for
the full envelope shape. The `finished: true` marker `<AsWfForm>`
routes on is supplied by the helper; `handleAsOutletRequest` only
wraps step results that don't already carry it (see app wiring below).

Use `abortWf("reason", { message })` when the flow ends in a
recoverable terminal state (rate-limited, user-cancelled). The envelope
adds `aborted: true` + `reason` so the client can render the failure
without treating it as a hard error.

::: tip Setting cookies alongside the envelope
`finishWf` / `abortWf` cover plain JSON envelopes. To attach
`Set-Cookie` headers (e.g. a session cookie issued on completion),
drop down to the raw `useWfFinished` from `@moostjs/event-wf`:

```ts
import { useWfFinished } from "@moostjs/event-wf";

useWfFinished().set({
  type: "data",
  value: { finished: true, data: { ok: true } },
  cookies: {
    session: {
      value: token,
      options: { httpOnly: true, sameSite: "Lax", path: "/", maxAge: 86_400_000 },
    },
  },
});
```

The helpers don't expose the `cookies` field — when you need it, build
the envelope yourself and hand the whole thing to `useWfFinished`.
The HTTP outlet forwards the cookies (see the eventContext caveat in
app wiring below).
:::

## App wiring

Two things to register: the workflow controllers and the HTTP
endpoint that dispatches incoming requests.

### Mount the workflow controllers

```ts
const app = new Moost();
void app.adapter(new MoostHttp()).listen(3000);
app.adapter(new MoostWf());
app.registerControllers(LoginWorkflow, RegisterWorkflow /* ... */);
```

`MoostWf` is the workflow adapter — it picks up classes with
`@Workflow` decorators and registers their steps with the underlying
`@prostojs/wf` engine.

### Mount the HTTP endpoint

A single `POST /wf` controller forwards every request to the engine:

```ts
import { Controller } from "moost";
import { Post } from "@moostjs/event-http";
import {
  MoostWf,
  EncapsulatedStateStrategy,
  createEmailOutlet,
  type WfOutletTriggerDeps,
} from "@moostjs/event-wf";
import { createAsHttpOutlet, handleAsOutletRequest } from "@atscript/moost-wf";

@Controller()
export class WorkflowsController {
  constructor(private readonly wf: MoostWf) {}

  @Post("wf")
  async handle() {
    const wfApp = this.wf.getWfApp();
    const deps: WfOutletTriggerDeps = {
      start: (schemaId, ctx, opts) =>
        wfApp.start(schemaId, ctx as never, {
          input: opts?.input,
          eventContext: opts?.eventContext as never,
        }),
      resume: (state, opts) =>
        wfApp.resume(state as never, {
          input: opts?.input,
          eventContext: opts?.eventContext as never,
        }),
    };
    return handleAsOutletRequest(
      {
        allow: ["auth/login", "auth/register"],
        state: new EncapsulatedStateStrategy({ secret: WF_SECRET }),
        outlets: [createAsHttpOutlet(), createEmailOutlet(sendEmail)],
        token: { read: ["body", "query", "cookie"], write: "body", name: "wfs" },
      },
      deps,
    );
  }
}
```

A few things to know:

- **Moost `globalPrefix` applies to workflow IDs too.** If your app
  is constructed with `new Moost({ globalPrefix: "api" })`, every
  `@Workflow("auth/login")` registers as `api/auth/login`. The
  `allow` whitelist and the client's `name` prop on `<AsWfForm>` must
  match the prefixed id.
- **`allow`** — the whitelist of workflow IDs the endpoint accepts.
  Without this, anyone with the URL could trigger any registered
  workflow.
- **`state`** — the state strategy. Pass a single `WfStateStrategy`
  instance (auto-registered as name `'default'`), or a named registry
  `{ strategies, default }` to mix strategies per flow. Two built-ins:
  `EncapsulatedStateStrategy` (token is a signed self-contained blob,
  no DB) and `HandleStateStrategy` (token is a handle; row lives in
  the store). See [State Persistence](/workflows/state-persistence)
  for swapping in `AsWfStore` and the named-registry form.
- **`outlets`** — register HTTP (always) and any other outlet the
  workflows use (email magic links, webhooks). Use
  `createAsHttpOutlet()` from `@atscript/moost-wf` so HTTP responses
  carry the `inputRequired` envelope the `<AsWfForm>` client expects.
  See [Outlets & Resume](/workflows/outlets-resume).
- **`token`** — where to read/write the state token. `body` is the
  default; `cookie` persists across reloads; `query` enables magic
  links (`?wfs=token` in URLs).
- **`eventContext` forwarding** — the `deps.start`/`deps.resume`
  wrappers forward the HTTP event context so the cookies-escape-hatch
  call to `useWfFinished().set({ cookies })` actually writes
  Set-Cookie on the response. Without this, the WF runs in an isolated
  context and cookies are silently dropped.

## Reading the workflow context

Inside a step, `@WorkflowParam("context")` gives you the typed,
mutable context object declared by `@WorkflowSchema<Ctx>`:

```ts
@Step("login-credentials")
async enterCredentials(
  @WorkflowParam("input") input: { username?: string; password?: string } | undefined,
  @WorkflowParam("context") ctx: LoginCtx,
) {
  const user = await usersTable.findOne({ filter: { username: input!.username } });
  ctx.userId = user!.id;
  ctx.mfaEnabled = !!user!.mfaEnabled;
  // mutations persist into the next step
}
```

The context is whatever you typed in the generic. The engine
serializes it into the state token (or into the durable store row)
between steps. Don't put non-serializable values in there
(class instances, functions, blobs).

See [Context Passing](/workflows/context) for the rules around
exposing context values to the _client_ form.

## Where to go next

- [Form Input & Validation](/workflows/form-input) — `@WfInput()`,
  `useAtscriptWf().requireInput()`, server-side errors.
- [Actions](/workflows/actions) — alt actions like "resend code" or
  "save draft".
- [Outlets & Resume](/workflows/outlets-resume) — pause for an
  external event, resume via a token in a magic link.


---
URL: "ui.atscript.dev/workflows/state-persistence"
LLMS_URL: "ui.atscript.dev/workflows/state-persistence.md"
outline: "deep"
---

# State Persistence

Workflow state has to live somewhere between steps. The framework
ships two strategies; this page covers when to use which, and how to
plug an atscript-db table in as a durable backend with `AsWfStore`.

## The two strategies

### `EncapsulatedStateStrategy` (default for short flows)

The state token is the state. Each round-trip the framework encrypts
the current `{ schemaId, indexes, context }` into a signed blob and
sends it back as `wfs`. The client returns the blob, the server
decrypts, runs the next step.

- No DB row, no cleanup, no migrations.
- Token lives wherever you put it (body / cookie / URL).
- **Lost if the client loses the token** (page reload without the
  token in cookie/URL).
- Token size scales with context size — keep `ctx` lean.

Good for: login, MFA, password change, multi-step forms where the
whole thing finishes in one sitting.

### `HandleStateStrategy` (DB-backed; `AsWfStore`)

The token is a UUID handle; the state lives in a database row. Each
step reads/writes the row.

- Survives process restarts.
- Survives the client dropping the token (you can hand the same
  UUID to another channel — see [Outlets & Resume](/workflows/outlets-resume)).
- Smaller tokens (just the UUID).
- Indexable: shadow columns expose context values as real DB
  columns, so an admin UI can `SELECT FROM wf_states WHERE
inviteEmail = 'a@b.com'`.
- Needs cleanup of expired rows.

Good for: email magic links (invite + finish-account), multi-day
approvals, "save and continue later", anything where the user
might come back after the browser tab is gone.

## Picking per workflow

`state` accepts either a single `WfStateStrategy` instance (the
shortcut — auto-registered under the name `'default'`) or a **named
registry** when you want to mix strategies across flows:

```ts
const encapsulatedStrategy = new EncapsulatedStateStrategy({ secret: WF_SECRET });
const handleStrategy = new HandleStateStrategy({ store: wfStore });

const HANDLE_STATE_WFIDS = new Set<string>(["users/invite", "approvals/multi-step"]);

@Post("wf")
async handle() {
  // ...
  return handleAsOutletRequest(
    {
      allow: ALLOWED_WORKFLOWS,
      state: {
        strategies: { handle: handleStrategy, encapsulated: encapsulatedStrategy },
        default: (wfid) => (HANDLE_STATE_WFIDS.has(wfid) ? "handle" : "encapsulated"),
      },
      // ...
    },
    deps,
  );
}
```

`default` picks the strategy name when a flow **starts** — a plain
string or a `(wfid) => name` function. The chosen name is embedded in
the issued token as `<name>.<raw>`, so on **resume** the framework
re-selects the strategy that persisted the state automatically — no
need to inspect token shape. Each strategy keeps its own independent
storage; names must match `/^[A-Za-z0-9_-]+$/`.

::: tip Version note
The named registry landed in `@wooksjs/event-wf` 0.7.16
(`@moostjs/event-wf` 0.6.20) and **replaced** the old
`state: (wfid) => WfStateStrategy` callback form, which was removed.
A step can also escalate at runtime with `swapStrategy('name')` (it
applies to the next pause). See the Moost docs for the full registry
contract.
:::

## Wiring `AsWfStore`

`AsWfStore` implements `WfStateStore` from `@prostojs/wf/outlets`,
backed by any `AtscriptDbTable` whose row shape extends
`AsWfStateRecord`.

### 1. Define the row type

Create a `.as` file that extends the base record with your
`@meta.id` primary key (and optionally shadow columns — covered
below):

```atscript
// `.as` files import the model from `/store.as` (raw atscript source);
// `.ts` files import the runtime class from `/store`.
import { AsWfStateRecord } from '@atscript/moost-wf/store.as'

@db.table 'wf_states'
export interface WfStateRow extends AsWfStateRecord {
    @meta.id
    @ui.table.hidden
    @db.default.uuid
    id: string

    // Indexable shadow columns from workflow context — covered below.
    @meta.label 'Invite Email'
    @wf.store.fromContext 'email'
    @db.index.plain 'email_idx'
    inviteEmail?: string

    @meta.label 'Invite Role'
    @wf.store.fromContext 'roleName'
    @db.index.plain 'role_idx'
    inviteRole?: string
}
```

The base `AsWfStateRecord` already declares:

| Column           | Type               | Notes                                                                                    |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------- |
| `handle`         | `string`           | Opaque correlation token; uniquely indexed (`handle_idx`).                               |
| `schemaId`       | `string`           | The workflow ID (`auth/login`, `users/invite`); indexed (`schema_idx`).                  |
| `state`          | JSON               | `{ context, indexes, meta? }` — the full state blob. `@db.json`, hidden from list views. |
| `expiresAt?`     | `number.timestamp` | Optional expiry; indexed (`expires_idx`).                                                |
| `updatedAt`      | `number.timestamp` | Set on every write; indexed (`updated_idx`).                                             |
| `createdAt`      | `number.timestamp` |                                                                                          |
| `createdBy?`     | `string`           | Stamped by the `actor` resolver.                                                         |
| `lastUpdatedBy?` | `string`           |                                                                                          |

### 2. Register the table with your db space

Standard atscript-db wiring — see
[db.atscript.dev / API / Tables](https://db.atscript.dev):

```ts
import { dbSpace } from "./db";
import { WfStateRow } from "./schemas/WfStateRow.as";

export const wfStateTable = dbSpace.table(WfStateRow);
```

### 3. Construct the store

```ts
import { AsWfStore } from "@atscript/moost-wf/store";
import { wfStateTable } from "../db";
import { useSession } from "../auth/use-session";

export const wfStore = new AsWfStore({
  // biome-ignore lint/suspicious/noExplicitAny: store touches base columns; subtype generic
  table: wfStateTable as any,
  actor: () => useSession()?.username,
});
```

Three options:

- **`table`** — your `AtscriptDbTable` of `WfStateRow`. Loose
  generic because the subtype is structurally a different annotated
  type than the base; the store only touches base columns +
  shadow columns.
- **`clock`** _(optional)_ — `{ now(): number }`. Default is
  `Date.now`. Inject a fake clock in tests.
- **`actor`** _(optional)_ — returns the username/principal stamped
  onto `createdBy` / `lastUpdatedBy`. Called per write. Returning
  `undefined` leaves the columns null.

### 4. Hand it to `HandleStateStrategy`

```ts
import { HandleStateStrategy } from "@moostjs/event-wf";

const handleStrategy = new HandleStateStrategy({ store: wfStore });
```

Plug it into your workflow controller as shown at the top of this
page.

## Shadow columns: `@wf.store.fromContext`

The full workflow state lives inside the `state` JSON blob — opaque
to SQL. **Shadow columns** are top-level table columns that get
mirrored from `state.context` on every write, so you can query them
with regular indexes.

### Declaring a shadow

Add a column to your row that extends `AsWfStateRecord`, with
`@wf.store.fromContext 'path.in.context'`:

```atscript
@meta.label 'Invite Email'
@wf.store.fromContext 'email'
@db.index.plain 'email_idx'
@ui.form.grid.colSpan 'half'
inviteEmail?: string

@meta.label 'Invite Role'
@wf.store.fromContext 'roleName'
@db.index.plain 'role_idx'
inviteRole?: string
```

The plugin enforces a few rules at compile time:

- Path must be dot-notation only (`a.b.c`); no arrays, no wildcards.
- Field must be **optional** (`?:`) or have a default — context
  shape varies between steps and a path-miss writes null.
- Field's underlying primitive must be `string | number | boolean`.
  No arrays, decimals, timestamps, or objects.
- Cannot annotate a `@meta.id` field.

### What happens on each `set()`

Every `wfStore.set(handle, state)` runs through `applyShadows`:

1. For each declared shadow field, walk the dot-path into
   `state.context`.
2. Coerce the value to the declared primitive type. Wrong type →
   write null and log once per field per process.
3. **Hit**: copy to the column.
4. **Miss on optional field**: write null (clears stale value).
5. **Miss on default-bearing field**: omit (DB default fires on
   insert; prior value sticks on update).

### Querying shadows

Once written, shadows are first-class table columns:

```ts
const pending = await wfStateTable.findMany({
  filter: { schemaId: "users/invite", inviteEmail: "alice@example.com" },
});
```

The classic admin-UI use case: "show all pending invites for
this email" without scanning JSON blobs.

### Backfilling: `heal()`

Adding a shadow column after the fact? Existing rows have nothing
in the new column. `heal()` re-runs `applyShadows` over the table:

```ts
const updated = await wfStore.heal();
console.log(`Backfilled ${updated} rows.`);
```

Options:

- `filter?: Record<string, unknown>` — narrow the scan (e.g. only
  rows for one `schemaId`).
- `batchSize?: number` — default 100.

No-op when no `@wf.store.fromContext` fields are declared.

## Cleanup

Expired rows accumulate unless you cull them. `cleanup()` deletes
where `expiresAt <= now()`:

```ts
const deleted = await wfStore.cleanup();
```

Options:

- `retention?: number` — milliseconds. Delete rows where
  `expiresAt <= now() - retention` (a grace period past expiry).
  Default 0 (drop everything ≤ now).
- `Number.POSITIVE_INFINITY` — no-op (returns 0); useful as an
  "off" switch.

Wire it on a timer at startup:

```ts
const RETENTION_MS = 86_400_000; // 1 day grace
setInterval(() => {
  wfStore.cleanup({ retention: RETENTION_MS }).catch((err) => {
    console.error("[wf-store] cleanup failed:", err);
  });
}, 5 * 60_000).unref();
```

## Race-safe consume: `getAndDelete`

Outlet resume flows (magic links) are single-use by default — the
engine calls `consume(token)` which calls `wfStore.getAndDelete`.
The store guarantees:

1. `findRow(handle)` to load the state.
2. `deleteMany({ handle })` to consume.
3. `deletedCount === 1` gate — only the caller whose delete
   returned 1 gets the state; concurrent callers get `null`.

That's why two simultaneous clicks on a magic-link don't both
proceed. The pattern is preserved in subclasses — see the next
section.

## Subclassing for sharded / multi-tenant tables

Most behaviour lives in `protected` methods, designed for
extension. The two most common overrides:

```ts
class TenantedAsWfStore extends AsWfStore {
  constructor(
    private tenantId: string,
    opts: AsWfStoreOptions,
  ) {
    super(opts);
  }

  // Layer tenant scope into every read.
  protected async findRow(handle: string) {
    return (await this.table.findOne({
      filter: { handle, tenantId: this.tenantId },
    })) as never;
  }

  // Stamp tenantId on every write.
  protected buildSetPayload(handle: string, state: any, opts: any) {
    return { ...super.buildSetPayload(handle, state, opts), tenantId: this.tenantId };
  }
}
```

When overriding `findRow`, **preserve the `getAndDelete` contract**
— that method calls `findRow` then `deleteMany({ handle })` and
gates on `deletedCount === 1`. If your `findRow` adds filters
(`tenantId`), make sure your delete uses the same key shape so
race-safety still holds.

## Where to go next

- [Outlets & Resume](/workflows/outlets-resume) — the killer use
  case for durable state: pause + resume across channels.
- [db.atscript.dev](https://db.atscript.dev) — the `AtscriptDbTable`
  API, schemas, query syntax.
- [Recipes](/workflows/recipes) — the invite + register flow uses
  `AsWfStore` end-to-end.