Skip to content

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).

atscript
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.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.

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:

atscript
@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:

  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).
  5. 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, call invalidateValueHelpCache() 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.

atscript
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
}
ArgumentMeaning
targetThe dictionary interface (a @db.alias is refused). Served by a moost-db controller; the controller stamps its path.
fieldA top-level scalar field of the target. The picker stores this field's value, and it must have the host field's type.
filterOptional static scope, field-to-literal comparisons of the target only. AND'd into every picker query.
  • It wins over @db.rel.FK on the field or on its chain, and it travels through chain refs and extends (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.view nor declares @db.http.path) is ignored and the FK walk runs. A @db.table / @db.view target 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.view nor 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.literalLabel it 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.

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'
}
AnnotationPicker behaviour
@ui.dict.labelPrimary text shown for each row
@ui.dict.descrSecondary text under the label
@ui.dict.attrExtra columns shown in the expanded mini-table view
@ui.dict.searchableForces the picker to send $search even without fulltext index
@ui.dict.filterableField appears in the picker's filter dialog
@ui.dict.sortableField 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>):

vue
<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:

typescript
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; $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.

Cross-references ​

Next steps ​

Released under the MIT License.