#Built-in field components

A3S Form fields have two parts: JSON Schema defines value types and validation, while UI nodes define controls, copy, and presentation. The Renderer only returns controlled values. It does not store business data or perform network requests for the host.

The interactive examples render the repository's real FormRenderer and display the JSON value returned after each field change.

#Common properties

Every field node uses kind: "field" and binds to its Schema through schemaPath. The Renderer, Designer, Vue adapter, and Web Component share these properties.

UiOption has the shape { label, value, disabled? }. value must be a JSON primitive and cannot contain a function or component instance.

When the Designer marks an array field as required, it adds the field to the parent required array and ensures minItems is at least 1. Turning it off restores minItems to 0, preventing an empty array from passing validation while the interface marks it as required.

#Designer configuration panel

The Designer maintains a unified UX profile for 38 production nodes. When a node is selected, the panel header shows its component type, category, purpose, field binding, and current state. Content and common behavior remain visible, while component type, initial value, field contract, and canvas placement move into Advanced settings. Matrices, option collections, data grids, and host components automatically use a wider task pane.

The configuration panel uses the semantic structure from @a3s-lab/ui@0.4.1; Form only adds node-level layout.

When the Schema allows a default value, the properties panel presents a control that matches the value type. Password, file upload, signature, and matrix fields do not expose inappropriate default-value inputs. A radio default uses its stable submitted value, and a multi-select default is stored as an array of the same item type.

Extension components should use the Inspector primitives supplied by Form. They apply A3S UI field, input, textarea, select, accordion, and switch contracts to native controls, so extensions do not need to copy panel styles.

import {
  FormInspectorControl,
  FormInspectorToggle,
  type FormNodeInspectorProps,
} from '@a3s-lab/ui/form/react';

function Inspector({ node, onUpdateNode }: FormNodeInspectorProps) {
  return (
    <>
      <FormInspectorControl label="Editor height">
        <select
          value={Number(node.customProps?.rows ?? 10)}
          onChange={(event) =>
            onUpdateNode({
              customProps: { ...node.customProps, rows: Number(event.target.value) },
            })
          }
        >
          <option value="6">Compact</option>
          <option value="10">Standard</option>
          <option value="16">Expanded</option>
        </select>
      </FormInspectorControl>
      <FormInspectorToggle
        label="Show line numbers"
        checked={node.customProps?.lineNumbers === true}
        onChange={(lineNumbers) =>
          onUpdateNode({ customProps: { ...node.customProps, lineNumbers } })
        }
      />
    </>
  );
}

#Configuring options in the Designer

select, radio, and multi-select use the structured option editor. Display labels can change independently while submitted values remain stable, so reordering or renaming an option does not change stored values.

Bulk editing changes one label per line. Existing rows preserve submitted values by position, new rows receive new stable values, and removed rows delete both the option and Schema enum value. Disable an option instead of deleting it when historical data must remain valid.

The component picker groups controls by value structure. Switching to a component with a different value structure rebuilds the field Schema, so review compilation results and existing controlled values before release.

const node = {
  id: 'name',
  kind: 'field',
  label: 'Task name',
  widget: 'text',
  schemaPath: '/properties/name',
  width: 6,
};

#Component reference

#Text input

#Single-line text text

Use for names, identifiers, and short titles. Put length, format, and pattern constraints in the Schema.

{
  "value": "同步客户数据"
}

#Multiline text textarea

Use for notes and descriptions. Set a reasonable maxLength for long text instead of putting complete file contents into a form value.

{
  "value": "失败时保留现场，并通知流程负责人。"
}

#Number number

An empty input returns null; a populated input returns a JavaScript number. The Schema remains authoritative for range and step constraints.

{
  "value": 3
}

#Email email

Uses native email-input behavior, with consistent validation through the Schema Profile email format.

{
  "value": "ops@a3s.dev"
}

#Password password

This control only masks input; it does not encrypt it. Never put long-lived credentials in a form document, default value, log, or screenshot.

{
  "value": ""
}

#Date date

Represents a calendar date without a time zone.

{
  "value": "2026-08-09"
}

#URL url

Use for callback addresses, resource links, and service endpoints. The browser input type is url, while the Schema uses the uri format.

{
  "value": "https://a3s.dev/form"
}

{
  "schema": { "type": "string", "format": "uri" },
  "ui": { "widget": "url", "placeholder": "https://example.com" }
}

#Telephone tel

Telephone formats vary by country and product context, so the component does not rewrite numbers. Add a Schema pattern when a fixed format is required.

{
  "value": "+86 138 0000 0000"
}

#Time

#Date and time date-time

The control explicitly displays UTC. A controlled value with an offset is converted to UTC before editing, and user changes are written back with a Z suffix.

{
  "value": "2026-08-09T09:30:00Z"
}

#Time time

Use when only a UTC time of day matters, such as a schedule shared across regions. Values with offsets are converted to UTC.

{
  "value": "09:15:00Z"
}

#Choice and collections

#Select select

Use when many options are available and the user chooses one. Static options and Schema enum should remain aligned; the host loads dynamic options through dataSource.

{
  "value": "staging"
}

#Radio radio

Use when there are few options and direct comparison is useful. Each option preserves native radio semantics, including browser-provided arrow-key behavior.

{
  "value": "review"
}

#Checkbox checkbox

Use to confirm one independent Boolean state.

{
  "value": true
}

#Switch switch

Use for an immediately enabled or disabled state, with role="switch" semantics. If toggling causes an irreversible side effect, use an explicit action button and confirmation flow instead.

{
  "value": true
}

#Multi-select multi-select

Uses a scannable checkbox panel instead of native select[multiple]. After reaching maxItems, unselected options become disabled while selected options can still be cleared.

{
  "value": [
    "human",
    "agent"
  ]
}

{
  "schema": {
    "type": "array",
    "items": { "type": "string", "enum": ["human", "agent", "reviewer"] },
    "minItems": 1,
    "maxItems": 2,
    "uniqueItems": true
  },
  "ui": {
    "widget": "multi-select",
    "options": [
      { "label": "Human member", "value": "human" },
      { "label": "Agent", "value": "agent" }
    ]
  }
}

Option values use strict equality, so the number 1 and string "1" remain distinct options.

#Tags tags

Press Enter, comma, or Add to commit an entry. Duplicate tags are not written, and removal buttons become disabled for retained items after the value reaches minItems.

{
  "value": [
    "Rust",
    "TypeScript"
  ]
}

#Numeric and business presentation

#Currency currency

The currency code appears as an input prefix, while the controlled value remains a plain number. Use it for budgets, thresholds, and quotes; it does not replace fixed-point decimal storage in a financial system.

{
  "value": 1280.5
}

{
  "schema": { "type": "number", "minimum": 0, "maximum": 1000000 },
  "ui": {
    "widget": "currency",
    "customProps": { "currency": "CNY", "step": 0.01 }
  }
}

#Rating rating

The default scale starts at 1 and reads its maximum from the Schema, supporting 1–10. The component uses native radio inputs, so keyboard and screen-reader semantics match a standard radio group.

{
  "value": 4
}

#Slider slider

Use for a numeric value with clear bounds where approximate selection is acceptable. Use number or currency when precise entry is required.

{
  "value": 65
}

The slider displays its current value and exposes aria-valuetext. Arrow keys, Page Up, Page Down, Home, and End retain native browser behavior.

#Hidden value hidden

A hidden field remains in the controlled value and in an input[type="hidden"] DOM element, but has no visible label or field shell. Use it for a stable identifier already known to the host that must be submitted with the configuration.

{
  "value": "org-a3s-lab"
}

Never put a secret, access token, or authorization decision in a hidden field.

#Calculated result calculated

Displays a host value or computed rule result in a read-only output. Numbers use the current locale for formatting without changing the raw controlled value.

{
  "value": 2561
}

{
  "ui": {
    "id": "total",
    "kind": "field",
    "widget": "calculated",
    "readOnly": true,
    "schemaPath": "/properties/total"
  },
  "rule": {
    "id": "calculate-total",
    "target": "total",
    "kind": "computed",
    "expression": {
      "op": "multiply",
      "left": { "op": "field", "path": "quantity" },
      "right": { "op": "field", "path": "unitPrice" }
    }
  }
}

#A3S UI component contract

The Designer canvas and Renderer share the same field implementations. The canvas uses inert to isolate example controls: they keep their normal appearance but leave the keyboard focus order and cannot change form values. Only read-only fields and calculated results use a disabled appearance.

Standalone pages and A3S products use the complete style entry point:

import '@a3s-lab/ui/form/a3s-ui.css';

If the host already loads A3S UI or requires strict isolation from document-level styles, use @a3s-lab/ui/form/styles.css instead. Both entry points use the same component structure and interactions.

#Using fields in React

Field components do not own values independently. Compile the document once, then pass the complete form value as a controlled property.

import { assertCompiled } from '@a3s-lab/ui/form/core';
import { FormRenderer } from '@a3s-lab/ui/form/react';
import '@a3s-lab/ui/form/a3s-ui.css';

const plan = assertCompiled(document);

function NodeSettings() {
  const [value, setValue] = useState({
    endpoint: 'https://api.example.com',
    roles: ['agent'],
    budget: 1000,
  });

  return <FormRenderer plan={plan} value={value} onChange={setValue} />;
}

Vue uses v-model, while the Web Component listens for value-change. All three adapters call the same React Renderer, so field values, validation, locale, read-only state, and host errors remain consistent.

#Validation and error states

• required comes from the parent object's Schema required array and is not duplicated in the UI node.
• Constraints such as minimum, maximum, multipleOf, minItems, and maxItems come from the Schema.
• Host errors enter through errors and bind to stable field paths.
• A read-only form disables every editable control while keeping calculated results readable.
• Empty options, data-source failures, duplicate tags, and collection limits all have visible, screen-reader-accessible messages.

For matrix row and column contracts, interactive examples, and embedding boundaries, see Matrix fields. See Repeatable field groups, Data grids, and Multi-step wizards for their respective collection and navigation contracts.