Nested Objects
Object types in .as schemas nest naturally. AsObject renders the root field as an iterator grid and every deeper section as a collapsible, with path-aware children that compute absolute paths automatically.
Section or namespace
Not every nested object becomes a section. An object prop is a section when it carries at least one annotation that gives it an identity of its own:
| Annotation | Effect |
|---|---|
@meta.label | Section with that title |
@meta.description | Section with a description under the title |
@ui.form.component | Your component renders the whole object |
@ui.form.type / @ui.type | Dispatches to that entry in the types map |
@ui.form.hidden / @ui.form.fn.hidden | The object and everything under it hides |
An object with none of them is a namespace: it is not a field, and its children render inline in the parent's grid at their full dotted paths. That is what keeps a DB-flattened struct (addr.street stored as addr__street) from growing chrome nobody asked for.
export interface Example {
// Namespace — renders `street` and `city` straight into the parent grid
address: {
street: string
city: string
}
// Section — renders a collapsible titled "Billing"
@meta.label 'Billing'
billing: {
iban: string
}
}Without a label, a section falls back to the prop name as its title.
It makes no difference whether the object is written inline or
referenced address: Address and address: { … } follow exactly the same rule. Annotations on the referenced declaration count as if written at the prop, so an @meta.label-annotated interface is a section everywhere it is used.
@ui.form.order is not in the table: order positions a field among its siblings, and a namespace object has no position of its own — its children carry their own order. Give the object a label if you want to place it as a unit.
Recursive types and navigation fields
A type may contain itself — a tree node with children: Node[], two interfaces that point at each other, a union holding the type. Forms build for any such type: the nested definitions repeat instead of expanding forever, and the form renders as deep as the data goes. A recursive object without an identity annotation still becomes a section where it closes the loop (it can't render inline — that would never end).
export interface Category {
name: string
parent?: Category // a section — the type reached again
children?: Category[] // an array of the same type
}Navigation fields of a db table — @db.rel.from, @db.rel.to, @db.rel.via — are not form fields by default: they hold related rows (loaded with $with), not data the row's own form edits, and a two-way pair points straight back at the form's type. The form leaves them out, its validator ignores loaded related rows, and neither the submitted data nor the patch carries them — at any depth, so a create or "duplicate" form seeded from a row loaded with $with does not write the related rows back. Edit the foreign key instead (see References (FK)). Building a payload yourself? omitSkippedNavFields(def, data) from @atscript/ui returns a copy without them.
To edit related rows inside the form anyway, annotate the navigation field with any @ui.form.* — even just its position:
@db.rel.from
@ui.form.order 5
lines?: OrderLine[] // rendered; `OrderLine.order` (the way back) stays outAn opted-in navigation object (@db.rel.to) always renders as its own section, never inlined into the parent's fields. Opting in means the form writes the related rows: a changed one goes into the submitted data and the patch, and the db performs a nested write to the related table — make sure that is what the form is for, and that the server allows it.
Since 0.1.164 — earlier versions crashed with "Maximum call stack size exceeded" on recursive types and rendered every navigation field.
The canonical example
A NestedForm.as schema that builds a two-level company profile.
@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
@meta.label 'Country'
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
}
}
@meta.label 'Contact'
@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, ctx, entry, t) => data.contact?.firstName ? t("Email for {name}", { name: data.contact.firstName }) : "Contact email address"'
email?: string.email
@meta.label 'Department'
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:
<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.labelbecomes 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. Drop their@meta.labeland they stop being sections:country.nameandcountry.codewould render straight into theaddressgrid.
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:
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:
@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. 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 — the user sees exactly which field failed without having to hunt through closed sections.
Reading the error counts yourself
The same data that drives the collapsed-section badge is available to your own components via useAsDescendantErrorCounts(). It returns a ComputedRef<Map<string, number>> keyed by every dotted-path prefix that has at least one error at or below it — so map.get("address") is the total error count anywhere under address. AsObject reads this map for its badge; you read it to badge a custom section shell (a tabbed layout, a side-nav) or to jump to the first errored section.
<script setup lang="ts">
import { useAsDescendantErrorCounts } from "@atscript/vue-form";
const errorCounts = useAsDescendantErrorCounts();
function errorsUnder(path: string): number {
return errorCounts?.value.get(path) ?? 0;
}
</script>
<template>
<nav>
<a v-for="s of sections" :key="s.path" :href="`#${s.path}`">
{{ s.label }}
<span v-if="errorsUnder(s.path)" class="badge">{{ errorsUnder(s.path) }}</span>
</a>
</nav>
</template>The composable returns undefined when no <AsForm> ancestor supplies the map — guard the .value access as above. The map is computed, so the counts update reactively as validation runs.
The map mirrors what fields display right now, not just the last submit: a live rule error (per the form's first-validation gating) counts the moment the field shows it, and fixing a value — typed or programmatic (e.g. a "discard changes" data restore) — drops the count immediately, no second submit needed. Submit-time errors for paths no mounted field owns (a not-selected union variant, an optional-disabled subtree) stay counted until the data is corrected or the next submit. External :errors entries count until dismissed by an edit.
Shared sections store
AsForm provides a AsNestedSectionsStore so the entire form shares one expand/collapse registry (useAsNestedSectionsStore()).
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.
<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.
Custom object renderer
Replace AsObject for one shape (e.g. an address card with a map preview) via the components map:
import AddressCard from "./AddressCard.vue";
const components = { "address-card": AddressCard };@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):
<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.
For a renderer that replaces the object's chrome entirely and re-lays-out its children — a tabbed shell, side-nav, or wizard — reach for the container-renderer kit (useAsVisibleFields, useAsFieldScope, useAsOptionalField, useAsLevel / provideAsNestedLevel, and AsIterator's :fields / :path-prefix / :levels props). See Container renderers.
Dynamic visibility on nested fields
Combine nesting with @ui.form.fn.* for context-aware children:
@meta.label 'Room'
@ui.form.fn.hidden '(v, data) => !data.contact?.department?.floor'
room?: stringdata is always the whole form's domain data — so data.contact?.department?.floor works from any depth. See Dynamic Fields.
Next steps
- Arrays — array-of-objects and nested arrays.
- Dynamic Fields — context-aware sections.
- Grid Layout — splitting nested fields across columns.