atscript-ui-forms

Install

npx skills add moostjs/atscript-ui      # installs all atscript-ui skills (this one + general + tables + wf + styles)
npx skills add moostjs/atscript         # sibling — .as language

pnpm add @atscript/core @atscript/typescript @atscript/ui @atscript/vue-form vue
pnpm add @atscript/ui-fns                       # opt-in: dynamic @ui.form.fn.* + @ui.form.validate
pnpm add @atscript/ui-styles vunor unocss       # styling
pnpm add unplugin-vue-components                # for AsResolver()

Quick start

// src/contact.as
@meta.label 'Contact'
@ui.form.submit.text 'Send'
export interface Contact {
    @meta.label 'Name'
    @meta.required 'Name is required'
    @ui.form.placeholder 'Jane Doe'
    name: string

    @meta.label 'Email'
    @meta.required 'Email is required'
    @ui.form.placeholder '[email protected]'
    email: string.email

    @meta.label 'Message'
    @ui.form.type 'textarea'
    @expect.maxLength 500, 'Keep it under 500 characters'
    message: string
}

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

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

function onSubmit(data: Contact) {
  // formData was { value: <Contact> } — vue-form unwrapped before emitting
  console.log(data);
}
</script>

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

AsResolver() from @atscript/ui-styles/vite auto-imports AsForm, AsField, AsIterator, AsCollapsible in templates — no manual import needed if unplugin-vue-components is wired.

Invariants

Key imports

// Tier 1 — primary (auto-imported by AsResolver)
import { AsForm, AsField, AsIterator, AsCollapsible } from "@atscript/vue-form";

// Tier 2 — defaults (swap targets; subpath imports also available)
import {
  AsFieldShell,
  AsInput,
  AsNumber,
  AsDecimal,
  AsSelect,
  AsRadio,
  AsCheckbox,
  AsDate,
  AsDatetime,
  AsTime,
  AsParagraph,
  AsAction,
  AsObject,
  AsArray,
  AsUnion,
  AsTuple,
  AsRef,
  AsMultiSelect,
} from "@atscript/vue-form";

// Composables
import {
  useAsForm,
  useAsFormPatch,
  useAsField,
  useAsState,
  useAsArray,
  useAsUnion,
  useAsTuple,
  useAsValueHelp,
  useAsDropdown,
  useAsOptionalAddFlow,
  useAsTriStateCheckbox,
  useAsDate,
  useAsDecimal,
  useAsNumber,
  useAsDualInput,
  useAsLocale,
  useAsPath,
  useAsTypeMap,
  useAsData,
  useAsErrorDismiss,
  useAsNestedSectionsStore,
  useAsDescendantErrorCounts,
  useAsExternalErrors,
  useAsUnionVariant,
} from "@atscript/vue-form";

// Factories + providers
import {
  createDefaultTypes,
  createAsFormDef,
  formatIndexedLabelParts,
  provideAsLocale,
  provideAsNestedSectionsStore,
} from "@atscript/vue-form";

// Types
import type {
  TAsComponentProps,
  TAsComponentEmits,
  TAsCollapsibleProps,
  TAsCollapsibleSlots,
  TAsChangeType,
  TAsTypeComponents,
  TAsUnionContext,
  TFormState,
  TFormRule,
  UseAsFieldOptions,
  UseAsFieldReturn,
  UseAsFormOptions,
  UseAsFormReturn,
} from "@atscript/vue-form";

References — load only what's needed

OCC-enabled edit forms

For tables annotated with @db.column.version, the server returns meta.versionColumn and auto-handles compare-and-set on update. Wire the form so the version field doesn't render as an input but the value still rides the wire:

import { createFormDef } from "@atscript/ui";
import { deserializeAnnotatedType } from "@atscript/typescript/utils";
import { VersionMismatchError } from "@atscript/db-client";

const meta = await client.meta();
const formDef = createFormDef(deserializeAnnotatedType(meta.type), {
  versionColumn: meta.versionColumn,
});

async function onSubmit(data: unknown) {
  try {
    await client.update(data as never);
  } catch (e) {
    if (e instanceof VersionMismatchError) {
      showError(`Row changed (current version: ${e.currentVersion}). Reload to continue.`);
    } else {
      throw e;
    }
  }
}

The version prop is excluded from def.fields[] (so <AsForm> doesn't paint it) but stays in flatMap and the underlying form data, so the PATCH body preserves it for the server's $cas lift. createTableDef does the symmetric thing on the table side — the version column never appears in column / filter / sort dialogs. See the atscript-db skill (OCC reference) for the server-side mechanics (@db.column.version, $cas, VersionMismatchError).

Customization

Forms expose three swap mechanisms, layered on the tier model:

• Tier 1 — <AsForm>, <AsField>, <AsIterator> are the integration surface. Configure them via props and slots; if you need a fully custom shell, build one with useAsForm / useAsField directly.
• Tier 2 — the default field components (AsInput, AsSelect, AsRadio, AsCheckbox, AsDate, AsParagraph, AsAction, AsObject, AsArray, AsUnion, AsTuple, AsRef, AsMultiSelect — see "Key imports"). These are what you swap.
• Tier 3 — internal composition helpers. Not directly tagged or swapped; their style classes ride with whichever defaults import them.

Swap a built-in renderer (:types)

:types maps built-in renderer ids (per invariant 1: text, select, date, …) to a component. Useful when you want every field of a given built-in type to render with your design system's input:

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

const types = { ...createDefaultTypes(), text: MyTextInput };
</script>

<template>
  <AsForm :def="def" :form-data="formData" :types="types" />
</template>

Swap a specific field (:components + @ui.form.component)

:components looks up by a custom name the .as type opts into. Use this when you want one field — not every field of that type — to render with a custom widget (e.g. a country picker that's still a string to the rest of the system):

export interface Profile {
    @meta.label 'Country'
    @ui.form.component 'country-picker'
    country: string
}

<script setup lang="ts">
import CountryPicker from "./CountryPicker.vue";
const components = { "country-picker": CountryPicker };
</script>

<template>
  <AsForm :def="def" :form-data="formData" :components="components" />
</template>

:components takes precedence over :types (invariant 4). The :types map stays reserved for built-in ids — point custom names at :components and you keep the renderer ids available for genuine type-level overrides.

Wrap with AsFieldShell

When the framing (label, hint, error, required marker, description) is already what you want but the input itself isn't, wrap your custom input in AsFieldShell rather than re-implementing the chrome:

<script setup lang="ts">
import { AsFieldShell } from "@atscript/vue-form";
import type { TAsComponentProps } from "@atscript/vue-form";
defineProps<TAsComponentProps<string>>();
</script>

<template>
  <AsFieldShell v-bind="$props">
    <input :value="modelValue" @input="$emit('update:modelValue', $event.target.value)" />
  </AsFieldShell>
</template>

If instead you render a bare root (no AsFieldShell — e.g. a section or media block that doesn't want the label/error chrome), you must bind :class="props.class" (and :style="props.style") on that root yourself. class/style are declared props on TAsComponentProps, so they arrive as props.class — not $attrs — and are not auto-applied to the root; AsFieldShell does this for you. Omit it and the field loses its @ui.form.grid.colSpan/.rowSpan placement (renders at the wrong width). Binding props.class is sufficient at every span — the default full-width and any colSpan override both ride on it, so you don't add as-grid-item or col-span-* yourself.

Full contract for custom components (TAsComponentProps, TAsComponentEmits, locale providers) lives in [customization.md](references/customization.md).

Style consequence

If you swap AsSelect for a custom dropdown, the as-select-* shortcuts the default tagged drop out of your bundle automatically. Keep the default when its styling already fits your design system; for granular opt-out, see atscript-ui-styles (allShortcuts super-merge, swap in a narrower subset).

In-tree examples

@atscript/vue-aooth ships five production examples of the custom-component and phantom-field patterns — AsConsentArray, AsPasswordRules, AsQrCode, AsCopy, AsSsoProviders. They demonstrate useAsField inside a component, re-using compileFieldFn from @atscript/ui-fns for fn-string arrays, the phantom (ui.paragraph + @ui.form.fn.value + @wf.context.pass) display pattern, and — via AsSsoProviders — emitting a form action from a custom component (one-click: select + fire @ui.form.action). See [aooth-components.md](references/aooth-components.md).

See also

Reference docs: https://ui.atscript.dev/forms/. Source: https://github.com/moostjs/atscript-ui.