@stonecrop/aform

@stonecrop/aform

Schema-driven form components for the Stonecrop framework. Renders a ResolvedField[] array into a form, wiring field values to a data object via v-model:data. The array usually comes from registry.resolveSchema(), but may also be hand-authored for view chrome that has no backing doctype — see Authoring space vs rendering space.

Components

Installation

import { install } from '@stonecrop/aform'

app.use(install)

This registers all components globally. They can also be imported individually.

AForm

Authoring space vs rendering space

Stonecrop has two field shapes, and AForm consumes only the second:

resolveSchema() renames a table's columns to schema because schema is the ATable prop that runs schemaToColumns(); ATable's own columns prop means already-converted TableColumn[]. Passing an authoring-space field straight to AForm therefore does not render a table.

kind is required and is the only thing AForm dispatches on — it does not infer a field's type from its structure. Every path into rendering space sets it: Zod's preprocess, Doctype.fromObject, and the registry. When hand-authoring, declare it yourself and use satisfies to stay checked:

import type { ResolvedField, ResolvedTable } from '@stonecrop/aform/types'

const schema: ResolvedField[] = [
  {
    kind: 'table',
    fieldname: 'line_items',
    component: 'ATable',
    schema: [{ fieldname: 'item_code', label: 'SKU', component: 'ATextInput' }],
    config: { view: 'list' },
  } satisfies ResolvedTable,
]

Each column needs a component: schemaToColumns() drops entries without one, since absence is what marks a non-scalar entry.

Table rows come from the data model

A table's rows are never part of its schema. AForm reads them from dataModel[fieldname], so a rows key on the schema field is ignored, and a table whose fieldname has no matching data key renders empty:

// schema declares fieldname: 'line_items' → rows are read from here
const data = ref({ line_items: [{ item_code: 'LAPTOP-PRO-15', quantity: 2 }] })

A table inside a fieldset reads its rows from data[tableFieldname] too: a fieldset is layout, so every field inside one is a key of the record itself.

Field width

Set width on any schema field to control its share of the form row. The value is any valid CSS size and is applied as flex-basis + width directly on the field's flex item:

{ "fieldname": "notes", "component": "ATextInput", "label": "Notes", "width": "100%" }

Fields without width continue to share space equally (flex-grow: 1; min-width: 20ch).

AFormLink

A form input for selecting and navigating to linked documents (fields carrying a doctype marker). Combines a searchable text input, an optional dropdown of results, and a navigation arrow button.

Value shape

interface AFormLinkValue {
  id: string | number      // the linked record's ID; id: 0 is valid
  displayText?: string     // shown in the input; falls back to String(id)
  [extra: string]: https://github.com/agritheory/stonecrop/blob/HEAD/any     // extra fields available to formatter
}

When id is falsy, the component shows a — placeholder and hides the navigation arrow.

Props

{
  modelValue: AFormLinkValue
  label?: string
  mode?: 'edit' | 'read' | 'display'
  doctype?: string          // target doctype slug — used by the navigation arrow
  filterFunction?: (search: string) => AFormLinkValue[] | Promise<AFormLinkValue[]>
  isAsync?: boolean         // show loading indicator while filterFunction resolves
  formatter?: (value: AFormLinkValue) => string  // custom display text transform
  icon?: 'arrow-right' | 'chevron-right'         // navigation arrow icon
  disabled?: boolean
}

Modes

Filter function

Provide filterFunction to enable the search dropdown. The function receives a search string and must return AFormLinkValue[] or a Promise<AFormLinkValue[]>.

The function is called in two distinct situations:

1. On user interaction — when the user focuses or types into the field, the current input text is passed as the search string.
2. On mount (and on id change) — when the field has an id but no displayText, the function is called automatically with the existing id string so the display name can be resolved without user interaction. The first result whose id matches is shown; the bound value keeps its bare id, since a lookup is not an edit.

Because of case 2, implementations should handle both name-based searches (partial strings typed by the user) and exact id lookups (full id strings passed on mount). A common pattern is to attempt both:

// Sync
const filterFunction = (search: string): AFormLinkValue[] =>
  records
    .filter(r =>
      r.id === search ||                                  // exact id match (mount-time resolution)
      r.name.toLowerCase().includes(search.toLowerCase()) // name search (user typing)
    )
    .map(r => ({ id: r.id, displayText: r.name }))

// Async — set isAsync: true for loading indicator
const filterFunction = async (search: string): Promise<AFormLinkValue[]> => {
  const results = await api.search(search)  // API should handle both id and name queries
  return results.map(r => ({ id: r.id, displayText: r.name }))
}

Navigation

AFormLink injects aformLinkNavigator from the app layer rather than depending on vue-router directly. Provide it once in your app plugin:

import type { AFormLinkNavigator } from '@stonecrop/aform'

app.provide('aformLinkNavigator', {
  navigate(doctype: string, id: string | number) {
    router.push(`/${doctype}/${id}`)
  },
} satisfies AFormLinkNavigator)

interface AFormLinkNavigator {
  navigate(doctype: string, id: string | number): void
}

If no navigator is provided, the arrow button is still rendered but navigation clicks are silent no-ops.

Via resolveSchema

For fields carrying a doctype marker with no matching links declaration and no component, Registry.resolveSchema() automatically assigns component: 'AFormLink'. No manual wiring required:

const config: DoctypeConfig = {
  name: 'Sales Order',
  fields: [
    { fieldname: 'order_number', component: 'ATextInput', label: 'Order Number' },
    { fieldname: 'territory', doctype: 'territory', label: 'Territory' },
    // no 'links' entry for territory
  ],
}

registry.addDoctype(Doctype.fromObject(config))
const resolved = registry.resolveSchema(registry.registry['sales-order'])
// resolved[1] === { kind: 'field', fieldname: 'territory', component: 'AFormLink', doctype: 'territory', label: 'Territory' }

// Pass to AForm as normal — the territory field renders as AFormLink automatically

Declared links (those with a links entry and a registered target doctype) are unaffected — they continue to resolve as embedded AForm (1:1) or ATable (1:many) entries.