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).
import { CustomersTable } from './Customer'
import { ProductsTable } from './Product'
@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.FKplusCustomersTable.iddeclares 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.
Reference chains
A field does not have to point straight at the dictionary. A view field is often declared against an intermediate table — errorCode: Issue.errorCode, where Issue.errorCode: ErrorCode.code is the link that actually carries @db.rel.FK:
@db.view
export interface IssueView {
/// No `@db.rel.FK` here — the FK lives one hop down, on `Issue.errorCode`.
errorCode: Issue.errorCode
}Since 0.1.134 the UI follows such chains: extractValueHelp(prop) walks prop.ref → the referenced field → its own ref until it finds a link that carries @db.rel.FK and whose target declares @db.http.path, so the picker targets the dictionary (ErrorCode) rather than losing its value help. The walk is depth-bounded and cycle-safe; a chain that never reaches an FK link simply yields no value help.
The server does the same on its side: since @atscript/db 0.1.128 /meta and /meta/form/:name serialize such a view field with ref pointing at the terminal field and db.rel.FK: true lifted onto the field. So a form built from a compiled .as type and one built from /meta resolve to the same dictionary.
How the picker resolves the target
ValueHelpClient is a thin wrapper around a Client from @atscript/db-client that:
- Fetches the target type's
@db.http.pathmetadata once and caches it. - Queries the target with
$selectscoped to PK + label + (optional) descr. - On search, sends
$searchto a@db.index.fulltexttarget, or builds an$orregex filter for non-searchable targets, plus an exact-PK match. - Honours
$limit(default 20). - Shares identical searches on the same client (since 0.1.151): pickers mounting together send one request, and a result is reused for 5 s. Tune with
setValueHelpCacheTtl(ms); after writing a dictionary outside<AsTable>actions, callinvalidateValueHelpCache()so pickers refetch at once. See the API reference.
The client is created lazily and shared by every ref field in the form — pass <AsForm>'s clientFactory prop to build it your way.
Binding without a foreign key: @ui.valueHelp
Since 0.1.148. A foreign key is a real constraint, and it needs a unique target column. A dictionary keyed by (attribute, value) has none, and a view field cannot point its @db.rel.FK at a second table without changing its column source. @ui.valueHelp binds a field to a dictionary for the picker alone: no constraint, no query semantics, presentation only.
import { AttributeValue } from './attribute-value'
@db.view 'ticket_overview'
@db.view.for Ticket
export interface TicketOverview {
@ui.valueHelp AttributeValue, 'value', `attribute = 'color'`
color: Ticket.color
@ui.valueHelp AttributeValue, 'value', `attribute = 'size' and active = true`
size?: Ticket.size
@ui.valueHelp Country, 'code'
countryCode: Ticket.countryCode
}| Argument | Meaning |
|---|---|
| target | The dictionary interface (a @db.alias is refused). Served by a moost-db controller; the controller stamps its path. |
field | A top-level scalar field of the target. The picker stores this field's value, and it must have the host field's type. |
filter | Optional static scope, field-to-literal comparisons of the target only. AND'd into every picker query. |
- It wins over
@db.rel.FKon the field or on its chain, and it travels through chain refs andextends(the field's own annotation wins, nearest first). A binding whose target arrives without a path (an interface that is neither a@db.table/@db.viewnor declares@db.http.path) is ignored and the FK walk runs. A@db.table/@db.viewtarget needs no literal@db.http.path: its controller stamps the path at runtime. - Pinned fields are hidden. A field the filter pins with
=(attribute = 'color') is constant inside the picker, so the table pickers drop its column and filter input. - The committed value is
field, never the label or the key head. The picker also fetches it when it is a unique non-key field, and the exact-match search runs on it. - The same binding drives the form picker, the table's filter dialog and inline filter field, and workflow forms (the server sends the target's path with the form schema).
- The compiler checks the binding — target kind (a warning when the target is neither a
@db.table/@db.viewnor has@db.http.path), field existence and type, the filter's scope, repeating values and a manual-filterable target whose filter fields lack@db.column.filterable(the last two are warnings) — and the editor completes the target, the field and the filter. On@ui.literalLabelit completes the union's literals ('true'/'false'on a boolean) for the value and jumps from the value to the literal it names.
A custom picker that builds its own query passes info.filter and selects info.targetField — see the API reference.
For union labels see Union labels; for distinct-value filters, Distinct values.
Controlling display with @ui.dict.*
The target type's dictionary annotations decide what the picker shows for each row.
@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 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>):
<script setup lang="ts">
import { AsForm, type ClientFactory } from "@atscript/vue-form";
import { Client } from "@atscript/db-client";
const clientFactory: ClientFactory = (url, options) =>
new Client(url, {
...options,
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:
import { setDefaultClientFactory } from "@atscript/vue-form";
setDefaultClientFactory(
(url, options) =>
new Client(url, {
...options,
/* auth */
}),
);Per-form clientFactory props override the default. Both fall back to the built-in new Client(url, options) factory when unset. Spread the second argument into the Client options (since 0.1.153): it carries the library's metaKey / metaStore requests — see Client factory.
Picker UX
The default AsRef component is a Reka-ui Combobox with:
- Inline text search (debounced;
$searchfor fulltext targets,$orregex fallback for non-searchable ones). - Keyboard-navigable list of results (
data-highlighted/data-statedriven by Reka). - Display of
@ui.dict.labelplus a faint secondary@ui.dict.descrline. - 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.
Cross-references
- Server-side relation metadata — db.atscript.dev/relations
- Query controls (
$search,$select,$limit, filters) — db.atscript.dev/api/queries - Building the target's REST controller — db.atscript.dev/moost-db
Next steps
- Customization — swap
AsReffor your own picker - Validation — error messages for required FKs
- Locale & currency — formatting nearby decimal columns