Skip to content

Schema form

A form described as data, one spec per field, drawn in Capsomer's fields and read back from a post.

<div data-mount="settings"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/schema-form.css";
import { parseJsonField, readSpec, readSpecs } from "capsomer/behavior/schema-form";

Usage

import { SettingsForm } from "capsomer/react/schema-form";
import { readSpecs } from "capsomer/behavior/schema-form";

<SettingsForm form={Form} specs={SPECS} values={loaderData.settings} errors={actionData?.errors} status={actionData?.saved ? "Settings saved." : null} pending={busy} />
// action: const { values, errors } = readSpecs(await request.formData(), SPECS);
<form class="cap-schema-form" method="post" novalidate>
  <div class="cap-schema-fields">
    <div class="cap-schema-cell"><div class="cap-field">...</div></div>
    <div class="cap-schema-cell" data-wide><div class="cap-field">...</div></div>
    <div class="cap-schema-cell" data-wide><div class="cap-field">... <textarea class="cap-input cap-schema-json" rows="6" spellcheck="false"></textarea></div></div>
  </div>
  <div class="cap-schema-actions">
    <button type="submit" class="cap-btn" data-variant="primary">Save</button>
    <p class="cap-schema-status" role="status">Settings saved.</p>
  </div>
</form>

Examples

After a post the server refused: the summary, and each message beside its field

<div data-mount="errors"></div>

Held in React state, with an app's own kind and read-only fields

<div data-mount="held"></div>

API reference

FieldFromSpec

PropTypeRequiredDoes
specFieldSpecYes
valueunknown
onChange(value: unknown) => void
errorReactNode
idPrefixstringThe control's id is specId(key, idPrefix): "field-title" by default.
renderersSpecRenderers

SchemaFields

PropTypeRequiredDoes
specsreadonly FieldSpec[]Yes
valuesRecord<string, unknown>
onChange(key: string, value: unknown) => voidControlled: the key and its new value. Left out, the fields post by name.
errorsreadonly SpecError[]
idPrefixstring
renderersSpecRenderers

JsonField

PropTypeRequiredDoes
namestringYes
valueunknownYes

SettingsForm

PropTypeRequiredDoes
specsreadonly FieldSpec[]Yes
valuesRecord<string, unknown>
errorsreadonly SpecError[]
statusReactNodeThe result of the last save, said in the status region ("Settings saved.").
pendingboolean
submitLabelstring
pendingLabelstring
formFormComponent | "form"
idPrefixstring
renderersSpecRenderers
childrenReactNodeHidden inputs (an intent) and anything else that posts with the fields.

And every attribute of <form>.

Functions

FunctionSignatureDoes
parseJsonField<T = unknown>(raw: FormDataEntryValue | null | undefined, valid?: (value: unknown) => value is T): T | nullA JSON value posted in one field (a hidden input an editor fills), or null when it is missing, does not parse, or does not pass valid. Null, never a fallback: an action that saved [] for a broken field would erase what is stored.
readSpec(form: FormData, spec: FieldSpec): { value: unknown; error?: string | undefined; }One field's value from a post, and the message when it does not do. Values: a string (text, email, url, textarea, date, select, choice), string[] (lines, multi), number (number, money in cents), boolean (checkbox), Date (datetime), unknown (json), or undefined for an empty field. A kind it does not know is read as text.
readSpecs(form: FormData, specs: readonly FieldSpec[]): { values: Record<string, unknown>; errors: SpecError[]; }Every field of a post by its spec: the values by key (an empty field is left out) and the errors in the form's order, for the error summary and the message beside each field.
specId(key: string, prefix?: string): stringThe control's id for a field key, so an error summary's link and a "needs info" link land on it.

Parts and data attributes

ClassIs
.cap-schema-actionsits own class
.cap-schema-cellits own class
.cap-schema-fieldsits own class
.cap-schema-formthe root
.cap-schema-jsonits own class
.cap-schema-readonlyits own class
.cap-schema-statusits own class
AttributeValues
data-widepresent or absent

Accessibility

Each field's own. Enter in a text field sends the form.

Each field is Capsomer's field part, with its label, help and error tied to the control; choices are fieldsets with a legend.