@formscript/render

Render intents, per §15.2 and §15.3 of the specification.

FormScript emits intents, never markup (§15.2). This package computes the intent a renderer should present; the renderer maps it to a platform widget.

The fourteen intents

import { RENDER_INTENT_KINDS } from '@formscript/render';

RENDER_INTENT_KINDS; // ['RenderTextInput', 'RenderNumberInput', 'RenderChoice', …]

RenderTextInput, RenderNumberInput, RenderChoice, RenderMultiSelect, RenderDate, RenderToggle, RenderFile, RenderSignature, RenderLocation, RenderGroup, RenderRepeat, RenderProgress, RenderErrorSummary, RenderMessage — the fourteen of §15.2, in the order the specification lists them. RenderIntent is a discriminated union with one variant per intent, so intent.intent === 'RenderChoice' narrows the payload.

Computing an intent

The intent is computed from the declaration alone. The input is a plain record: no expression, no evaluator, no locale, no clock.

import { computeRenderIntent } from '@formscript/render';

const intent = computeRenderIntent({
  kind: 'field',
  id: 'email',
  name: 'email',
  type: { kind: 'scalar', name: 'string' },
  required: true,
  readOnly: false,
  derived: false,
  overridable: false,
  label: 'Email address',
});

intent?.intent; // 'RenderTextInput'

renderDeclarationFromBlock reads a parsed field, choice, group, repeat, section or page block into that record. It resolves only what is written down: a t("key") label needs a catalogue and a locale, and a dynamic required needs an evaluation, so the host supplies both.

The rules that select an intent

• options or optionsFrom makes a field a constrained selection, and RenderChoice (Spec-4.24, Spec-4.27).
• type = enum(…) makes a field a constrained selection, and RenderChoice.
• type = array(…) makes a field a multiple selection, and RenderMultiSelect; its options come from the element type when the element is an enum.
• A group is RenderGroup, a repeat is RenderRepeat, a page is RenderProgress, a choice is RenderChoice.
• A derived field (value = expr) is not editable unless it is overridable (Spec-7.4, §8.9).

The two planes

label, hint, help, placeholder, unit, addLabel, removeLabel and format are the presentation plane (§12.6). presentationPlane returns them; the data plane never reads them, and this package never evaluates a value expression, so an intent cannot depend on a presentation read. The analyzer reports E-TYPE-08 when a display value reaches a data position; this package does not report it again.

Judgement calls

The specification lists the fourteen intents but never says which declaration selects which. The rules above are the most literal reading; the choices that the text leaves open are recorded here.

• section → RenderGroup. §15.2 has no section intent. §7.14 makes a section a presentation grouping that introduces no data level, so it renders as the labelled composite a group renders as.
• page → RenderProgress. The only page-level intent in §15.2 is RenderProgress ("Page progress").
• duration → RenderTextInput. §15.2 has no duration intent. §5.1 lists duration beside date, so date and datetime give RenderDate and duration falls back to the free-text widget.
• object → RenderGroup, any → RenderTextInput. §15.2 has no composite-value intent and no untyped intent.
• A declared options list wins over the enum type's own options. §4.25 attaches labels to keys and does not say how the two sets combine; the analyzer reports a document whose two sets disagree.
• A field with no type produces no intent (Spec-7.6 makes type required) and a field whose options conflict with its type produces no intent (Spec-4.24). Neither is re-reported here: the analyzer owns those diagnostics.
• An inapplicable entity produces no intent (Spec-8.3: it is not rendered). selectRenderIntent still reports the widget it would use, so a renderer can keep the identity of a field that comes back.
• format is treated as presentation-plane. §12.6 puts formatted numbers, dates and currency in the presentation plane, and format is a display format (§8.1).
• §15.3 is only partly checkable. A label for every control, a stable identity and the placeholder prohibition are checkable from the intents and are implemented by checkRenderObligations. The focus and cursor obligations (Spec-15.4 bullets 4–5, Spec-15.5) are renderer behaviour; the stable id on every intent is what makes them achievable.

Ambiguities in the specification

• §15.2 does not say which properties select an intent, and it has no intent for a duration, an object or an any value.
• §7.13 says a choice is semantically a field whose type is enum, but §8.1 gives choice a type property of its own and Spec-4.27 lets a field with options be a string. This package therefore treats a choice as a choice whatever its type, and reports options-type-conflict only for a field whose type may not carry a choice set.
• §15.2 describes RenderProgress as "Page progress" without saying whether it stands for the page or for a progress element inside it.

Public API

53 exported symbols.