Ramonda

Fields

this.form.fields is the shape of your values, walked by property access.

const f = this.form.fields;

f.email;                 // a field
f.address.city;          // a field, one level down
f.contacts[0].value;     // a field inside a row

Nothing there is a string. f.adress.city is a compile error, and renaming city in the schema breaks the render rather than quietly reading undefined.

Everything is behind $

A field node is two things at once: a place to keep walking, and a thing with an API. $ separates them.

f.address;         // keep walking
f.address.$;       // the API for the address object itself
f.address.city.$;  // the API for the city field

Which means the API is always exactly one token away, and it is the same token everywhere:

const city = f.address.city.$;

city.value      // what it holds
city.error      // the first message, or undefined
city.errors     // all of them
city.touched    // has it been blurred
city.dirty      // has it been edited
city.path       // "address.city"
city.name       // the same, for the input's name attribute
city.set(next)  // write it
city.reset()    // back to its default
city.setError("no such city")  // a message from the server, on this field

// and, for a field one control holds, what that control is written with:
city.inputValue // the value as the control shows it
city.invalid    // whether it has a message, for aria-invalid
city.oninput    // the control's own handler, which writes the field
city.onblur     // marks it touched

Why one token instead of eleven names

A flat API — f.address.city.value, f.address.city.error — collides with your data. A form with contacts: { kind, value }[] could not say f.contacts[0].value, because value would be both a field of yours and a property of the API. The same goes for name on a person, errors on a report, path on a file picker.

Flat is eleven chances to collide, one per member. $ is one. And if you do have a field literally called $, the type says so by name and at("$") is the way through.

f.settings.at("$");              // a field actually named "$"
f.settings.at(keyFromRuntime);   // a key not known until runtime

Writing a control

A control is written with five attributes, each by name:

const email = f.email.$;

<input
  aria-label="Email"
  name={email.name}
  value={email.inputValue}
  oninput={email.oninput}
  onblur={email.onblur}
  aria-invalid={email.invalid}
/>;

oninput and onblur are built once per field and reused, so writing them on every render hands the control the same handler each time. Every attribute is there to read where the control is, and inside a form it recognises — <form onsubmit={this.form.submit}> — @ramonda/check reports a control that is missing one.

What you write follows the value's type:

the field holdsthe control
stringvalue={x.inputValue} — any control but the two that hand back a number, a checkbox and a file input; type="date" for a date written as text, which starts at ""
numbertype="number" value={x.inputValue} — "" for an emptied field; or type="range", a slider
booleantype="checkbox" checked={x.value === true} — a value not set yet, or cleared by a reset, is an unticked box
Datetype="date" value={x.inputValue} — the day, as YYYY-MM-DD; emptied, it holds nothing (undefined), so a date that may be empty takes it — z.date().nullish()
an object or a listno control holds one: its $ has no oninput, and writing it is a type error

inputValue is what a control shows of the value (InputValue<T>): a date as its YYYY-MM-DD. An element's value takes anything, so a Date written there directly — value={born.value} — compiles, and the field shows nothing: write inputValue. A number shows as FormNumber, a date as FormDay and text as FormText — a number and two strings, marked for ramonda-check, which reads the mark below.

The type is what turns an edit back into the value: type="number" and type="range" hand back a number — whatever the field held, as an empty field could be waiting for a number or text alike — a checkbox true or false, type="date" what the next paragraph says, and any other control text. So the control has to match the field: a number field written without its type fills the form with text, and a text field in a slider fills it with a number. ramonda-check reports either before it ships, as form-value-in-the-wrong-control, and RMF005 reports them in a running page once the field holds a value.

type="date" serves two kinds of field, a Date and a date written as text ("2026-10-29", a JSON Schema format: "date"), and the value the field holds tells them apart: text gets the control's text back, and a Date or nothing gets a day. So a date written as text starts at "" — in defaultValues, or in the row you append — and a Date emptied holds nothing rather than "". Where it starts is the author's to write: neither ramonda-check nor RMF005 can tell a date written as text that starts with nothing from a Date, and it takes a day on the first pick.

A choice lives on <Select>

Every other control holds its own value. A select's value is which of its children is chosen, so <select> is a type error and you write <Select>. The options stay ordinary tags:

import { Select } from "@ramonda/core";

<Select aria-label="Choice" value={this.choice} onchange={this.pick}>
  <option value="a">A</option>
  <option value="b">B</option>
</Select>;

<Select> takes everything a <select> takes — className, disabled, name, data-, aria-, every event — and passes it straight through to the element.

The reason the plain tag is refused is that selected on an option does not say one thing. HTML keeps the later of two selected options and gives a select with none the first option it holds, so what the attribute means depends on the order the options reach the select. You never write that order. value on the select is settled once the options are there and competes with nothing.

A multiple select takes a list, and keeps every value in it:

import { Select } from "@ramonda/core";

<Select multiple aria-label="Tags" value={this.picked} onchange={this.pickMany}>
  {this.all.map((v) => (
    <option key={v} value={v}>
      {v}
    </option>
  ))}
</Select>;

On a server-rendered page the choice arrives as selected on the chosen option, because that is where HTML keeps it and a select has no value attribute to carry. The reader sees the right option before any script runs.

value is the model's; defaultValue is where the field starts. A field with value shows what the model holds: its own handler writes the model, and the field shows the model again in the same event, before the event bubbles to anything around it — so a handler that does not take an edit leaves the field as it was, its caret and its selection where the edit found them, and a field with no handler of its own cannot be changed. A word typed through an input method — Japanese, Chinese, an Android keyboard, an accent on a Mac — reaches the handler at every step, isComposing saying it is not finished, so a search typed on any device runs as the user types; the field is not written until the word ends. A handler that waits for the finished word returns while isComposing, and is handed the word once when it ends — in Chromium and in Firefox, where it is measured. A field whose text is read when the form is sent, rather than held in state, takes defaultValue instead: it shows that first and then belongs to the user, and a form's reset returns to it. A default that changes later — a saved draft that loads — moves the field while it shows its default; once the user has picked, it moves only where a reset returns. A Select whose picked options are all replaced — a city list after its country changed — shows its default again.

<TextArea aria-label="Draft" value={this.draft} oninput={this.onInput} />;   // held by the model
<TextArea aria-label="Notes" name="notes" defaultValue={this.saved} />;       // the user's, sent with the form

What a field shows is set through the model, never by sending the field an event. A value known at the start is the field's initial state, @state accepted = true; one learned on mount is written in @mounted, this.draft = this.saved. A field learns its model through render, and the work a commit runs — @mounted, @updated, render() — is still running when an edit sent from there arrives. field-set-by-an-event reports one before it ships, and RMD062 reports the next event of that commit that reads the model while the first edit's render waits.

Refusing or rewriting an edit — the handler decides

A field's handler decides each edit by what it writes: the edit, to take it; something else, to rewrite it; nothing, to refuse it. The field shows the model in the same event, before anything around it reads it — so a refused keystroke is never drawn, and the caret and the selection go back where the edit found them.

import { Component, state, type EventOn } from "@ramonda/core";

class Phone extends Component {
  @state phone = "";

  typed(event: EventOn<HTMLInputElement, InputEvent>) {
    if (event.isComposing) return;
    const text = event.currentTarget.value;
    if (/^\d*$/.test(text)) this.phone = text;
  }

  render() {
    return <input aria-label="Phone" value={this.phone} oninput={this.typed} />;
  }
}

A handler that refuses or rewrites waits for the finished word: it returns while isComposing, and is handed the word once, when it ends. One that took the first steps of a word and refused the rest would keep a reading the input method had not finished — abに for ab日本 — in the model.

The handler is handed the edit's own input. Typed EventOn<HTMLInputElement, InputEvent>, it reads what the edit was — event.inputType: insertText, deleteContentBackward, insertFromPaste — and where the caret is, event.currentTarget.selectionStart, which is what a mask needs. A rewrite that keeps the text's length keeps the caret where it was; after one that changes the length, where the caret belongs is the app's to say.

TextArea — a <textarea> keeps its value inside the element

HTML gives a textarea no value attribute — the value is the element's text — so <textarea> is a type error and you write <TextArea>:

import { TextArea } from "@ramonda/core";

<TextArea aria-label="Draft" value={this.draft} oninput={this.onInput} />;

It renders <textarea>a draft</textarea>, so a server-rendered page shows the text before any script runs, and it passes everything else through to the element.

A checkbox's third state

indeterminate is a property and not an attribute — HTML has nowhere to write it — so it works on the client and a server-rendered page cannot carry it:

<input
  type="checkbox"
  aria-label="Select all"
  checked={this.all}
  indeterminate={this.some && !this.all}
  oninput={this.toggleAll}
/>

The box arrives unchecked and becomes mixed when the page hydrates. There is no way around that; it is what HTML offers.

Writing your own attributes

Everything else is written beside the five, as on any element:

const email = f.email.$;
const age = f.age.$;

<input
  aria-label="Email"
  name={email.name}
  value={email.inputValue}
  oninput={email.oninput}
  onblur={email.onblur}
  aria-invalid={email.invalid}
  className="wide"
  placeholder="you@example.com"
  autocomplete="email"
/>;
<input
  aria-label="Age"
  type="number"
  name={age.name}
  value={age.inputValue}
  oninput={age.oninput}
  onblur={age.onblur}
  aria-invalid={age.invalid}
  min={0}
  max={120}
/>;

To do something extra on an event, call the field's handler from a method of your own:

class SignupForm extends Component {
  private form = this.use(Form<typeof schema>, () => ({ schema, defaultValues, onSubmit }));

  onEmailInput(event: Event): void {
    this.form.fields.email.$.oninput(event);
    this.searchAsYouType(event);
  }

  searchAsYouType(event: Event): void {
    // your own work, after the field has taken the value
  }

  render() {
    const email = this.form.fields.email.$;
    return (
      <input
        aria-label="Email"
        name={email.name}
        value={email.inputValue}
        oninput={this.onEmailInput}
        onblur={email.onblur}
        aria-invalid={email.invalid}
      />
    );
  }
}

A method rather than an inline arrow, because methods are auto-bound: the identity never changes from one render to the next. An arrow here is a new function every render, which RMD020 reports.

The node types — LeafNode, ObjectNode and ArrayNode

A node's shape follows the value's, and each carries a different $.

the valuethe nodeits $
a string, number, boolean or DateLeafNode<T>LeafApi<T> — a FieldApi plus inputValue, invalid, oninput, onblur
an objectObjectNode<T>FieldApi<T>, with the properties beside it
an arrayArrayNode<E, T>ArrayApi<E, T> — a FieldApi plus length and rows

FieldTarget<T> is the smallest of them: anything with a $. Take it when you write a component that accepts a field without caring which kind — that is what a field in its own component does.

A schema with a property named $ gets Collision instead of a node, and the type carries its own explanation so the compiler prints it: the error names .$.at('$') and the option of renaming, rather than saying that some property does not exist on some type.

Controls that are not an <input>

A custom control — a date picker, a rich text editor, a set of radio buttons — reads value and calls set:

class Editor extends Component {
  private form = this.use(Form<typeof schema>, () => ({ schema, defaultValues, onSubmit }));

  pickTheme(next: string): void {
    this.form.fields.theme.$.set(next);
  }

  render() {
    return <ColourPicker value={this.form.fields.theme.$.value} onPick={this.pickTheme} />;
  }
}

set is the only way to write a field. value is readonly, so an assignment is a compile error before it is anything else:

Cannot assign to 'value' because it is a read-only property. ts(2540)

It also throws at runtime (RMF001), which is what catches it in JavaScript and in a file the checker is not covering. A field node is a proxy over a path rather than a place values live, so an assignment would land nowhere and the next read would hand back the old value.

A field in its own component

A design system does not want the five attributes written at every call site — it wants a <TextField> that carries them once, with the label, the message and the class that turns red. A component that takes a field needs one thing from the form, and Field is it:

import { Field, type FieldNode } from "@ramonda/form";

class TextField extends Component<{ of: FieldNode<string>; label: string }> {
  f = this.use(Field<string>, () => ({ of: this.props.of }));

  render() {
    return (
      <label className={this.f.error ? "field field--invalid" : "field"}>
        <span className="field__label">{this.props.label}</span>
        <input
          name={this.f.name}
          value={this.f.inputValue}
          oninput={this.f.oninput}
          onblur={this.f.onblur}
          aria-invalid={this.f.invalid}
        />
        {this.f.error}
      </label>
    );
  }
}

And the call site hands over one prop, typed by the schema:

<TextField of={f.email} label="E-mail" />
<TextField of={f.address.street} label="Street" />

Field is required, not an optimisation. Without it such a component never re-renders: a field node is one cached object for the life of the form — deliberately, so oninput keeps its identity — so the component's props never change and the diff skips it. Its message would never appear, and a write from anywhere else would never reach its input.

Field answers everything a node's $ does — value, error, errors, touched, dirty, name, inputValue, invalid, oninput, onblur, set, reset, and the list members for an array field — so a component written against FieldApi<T> needs nothing new to learn. Name the type at the use: FieldNode<T> is a conditional type, so T cannot be recovered from it by inference, and Field<string> is the same pin Query<Todo> takes.

The wrapper is the one you were going to write

The <label> is the component's own markup, so there is no extra node in the DOM. What comes out is what you would have written by hand:

<label class="field">
  <span class="field__label">E-mail</span>
  <input name="email" value="">
</label>

That is where the class, the label and the message belong anyway — and the class sits on the element it styles, so it follows the message on every render without any work.

Defaults come from the class, variants from a component

There is no defaultProps, and none is needed — a getter with a fallback is one:

class TextField extends Component<{ of: FieldNode<string>; label?: string }> {
  protected get labelText(): string {
    return this.props.label ?? "Field";
  }
}

A variant is a component that fills the props in, and it costs nothing: what lands on the page is what TextField's render returned, with no wrapper element around it.

class EmailField extends Component<{ of: FieldNode<string> }> {
  render() {
    return <TextField of={this.props.of} label="E-mail" />;
  }
}

One keystroke, one field

Because the subscription is per path, an edit wakes the fields that changed and no others. Measured over 300 rows, one keystroke rebuilds one row; without a per-field subscription the same keystroke rebuilds all 300, at 45 ms. Inside a list the node arrives already — list(rows, (item) => <Row item={item} />) hands each row its own — so a row component is the same shape:

import { Field, type Row } from "@ramonda/form";

class Line extends Component<{ item: Row<Contact> }> {
  f = this.use(Field<string>, () => ({ of: this.props.item.field.value }));

  render() {
    return (
      <input
        aria-label="Contact"
        name={this.f.name}
        value={this.f.inputValue}
        oninput={this.f.oninput}
        onblur={this.f.onblur}
        aria-invalid={this.f.invalid}
      />
    );
  }
}

A watcher hears only about what it reads

Field records which members you actually read and ignores anything else. A component rendering a list reads rows — and a row's id, index and field do not move when a value inside that row does, so it sleeps through a keystroke in any of its rows. Each row watches its own field and wakes on its own.

That is what makes the container worth watching too:

import { Field, type FieldNode, type Row } from "@ramonda/form";

/** One row, watching its own field — the same shape as `TextField` above. */
declare class Line extends Component<{ item: Row<Contact> }> {}

class Rows extends Component<{ of: FieldNode<Contact[]> }> {
  f = this.use(Field<Contact[]>, () => ({ of: this.props.of }));

  render() {
    return <div>{list(this.f.rows, (item) => <Line key={item.id} item={item} />)}</div>;
  }
}

It wakes when a row is added, removed or moved, and not otherwise. Measured at 300 rows, one keystroke: 45 ms and every row rebuilt with no per-field subscription at all, 1.9 ms and one row once each row watched its own field, 0.6 ms once the container watched the array as well — because then the three hundred list items are never diffed.

error is the one that reads two things: a message is held back until the field has been touched, so it wakes on a blur as well as on a message. Nothing is lost by not reading a member — the first render that does read it subscribes from then on.

The owner cannot opt out

The component that owns the form re-renders on every change, and not because of anything it reads: @state on a hook holds the owning component's rebuild from the moment it is created. So keep that component thin — hand the fields out and let it build a handful of vnodes whose props have not changed. The diff stops there.

A button that watches the form

isValid, isSubmitting and submitCount belong to the form rather than to any field, and reading one in the owner's render is what ties the owner to every keystroke. FormState is the hook for them, and it takes no props — the form publishes itself on the context, so this works at any depth, through layouts that know nothing about forms:

import { FormState } from "@ramonda/form";

class SaveButton extends Component {
  private form = this.use(FormState);

  render() {
    return (
      <button disabled={!this.form.isValid || this.form.isSubmitting}>
        {this.form.isSubmitting ? "Saving…" : "Save"}
      </button>
    );
  }
}

It wakes on an answer that MOVED, not on an event. A form that was invalid before a keystroke and invalid after it has not changed its answer, so the button sleeps through the typing and wakes the moment validity flips or a submit starts or ends. isDirty is the expensive one — a comparison of the whole value against the baseline — and the form computes it only while something reads it.

Two forms nested behave the way you would want without saying anything: the button watches the nearest form above it.

Two forms side by side are two components, and that is the only way to write them: a component publishes the form context once, so a second Form on the same component throws (RMD056) rather than quietly handing every button below it the second form. Give each form the subtree it belongs to — a component that renders this.props.children is enough — and a plain this.use(FormState) inside each finds its own with nothing passed down. See Context.

With no form above it at all, every fact reads as its default and core reports RMD003 when the component mounts.

The recipe for a big form

Put together, the three pieces mean the owner of the form reads nothing — and then its render can be cached:

/** The two from above: one watches an array, the other watches the form. */
declare class Rows extends Component<{ of: FieldNode<Contact[]> }> {}
declare class SaveButton extends Component {}

class Page extends Component {
  private form = this.use(Form<typeof schema>, () => ({ schema, defaultValues, onSubmit }));

  @compute get body() {
    return (
      <form onsubmit={this.form.submit}>
        <Rows of={this.form.fields.contacts} />
        <SaveButton />
      </form>
    );
  }

  render() {
    return this.body;
  }
}

this.form.fields.contacts is navigation through a proxy, not a read, so the @compute depends on nothing and is built once for the life of the form. The owner is still woken on every change — it cannot opt out — but it hands the diff back the same tree, and the diff stops immediately.

Measured at 300 rows, one keystroke: 45 ms with no per-field subscription, 1.9 ms with each row watching its own field, 0.65 ms with the container watching the array, 0.48 ms with the body cached. The last step is small here because the owner's render is two vnodes; it is worth much more when a render builds a lot inline — 4.35 ms against 0.19 ms for one building 300 children.

A @compute body pays off only while it reads nothing that moves. Any field read inside it — a disabled={!this.form.isValid} written there instead of in a button — puts the form's counter in its dependencies, and it is rebuilt on every keystroke again.

Labels, ids and accessibility

name is what a form posts under, and what a <label for> cannot use. The simplest correct thing is to wrap the input:

const email = f.email.$;

<label>
  Email
  <input
    name={email.name}
    value={email.inputValue}
    oninput={email.oninput}
    onblur={email.onblur}
    aria-invalid={email.invalid}
  />
</label>;

A wrapping label needs no id at all. If your design cannot wrap, add an id and a htmlFor yourself — the form does not generate them, because an id has to be unique across the whole page and only you know what else is on it.

aria-invalid={x.invalid} follows the same rule the visible message does: it is true only once the message is ready to be seen. To connect the message itself, add aria-describedby pointing at your own element.

Next

  • Validation — the errors a field shows, and the moment they appear.
  • Array fields — the same tree where a row can be inserted or removed.
  • Refs — for reaching the element itself.