@orkestrel/form

The environment-agnostic form document: a FormSchema stating what is asked, a Form holding the answers given against it, declarative FieldRule data stating what those answers must satisfy, acknowledged editing, and a terminal submit that settles the form exactly once.

A terminal prompt and a browser form ask the same thing in different places, so the core ships what they share. The browser entry binds native controls and renders neutral feedback. Its answer promise is the parking seam a server needs: hand the document out, wait, receive the answers back. A live form can take a field out and put it back with disable and enable, and exported budgets bound what one schema and its answers may retain, so a document that arrives from a wire costs a known maximum before anything decides to trust it. Built on @orkestrel/contract and @orkestrel/emitter, and part of the @orkestrel line.

Install

npm install @orkestrel/form

Requirements

• Node.js >= 22.18
• Host-independent: no node:*, no DOM. Ships dual ESM+CJS builds.

Usage

Declare what is asked, answer it, and settle it once:

import { createForm } from '@orkestrel/form'

const form = createForm({
	label: 'Sign up',
	fields: [
		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
		{
			control: 'password',
			name: 'secret',
			label: 'Password',
			rule: { required: true, minimum: 12 },
		},
		{ control: 'confirm', name: 'terms', label: 'I accept the terms', rule: { required: true } },
	],
})

// A task somewhere else parks on the answer.
const parked = form.answer

form.fill({ email: '[email protected]', secret: 'correct horse battery' })
form.errors // [{ field: 'terms', message: 'This field is required', rule: 'required' }]

form.fill('terms', true)
const result = form.submit()
result.success // true

await parked // { email: '[email protected]', secret: 'correct horse battery', terms: true }

Guide

See guides/form.md for the documented surface — the controls and their value shapes, the rule table and the custom cross-field seam, the presence model behind required, the lifecycle and its events, taking a field out of a live form with disable and enable, the budgets that bound what a schema and its answers may retain, the serialize/parse wire boundary, and the concept inventory of what this package leaves to the layer above.

Package

The . entry ships the host-independent core in ESM and CJS. The ./browser entry ships the native binding in ESM. Both include declarations. The binding supports password reveal, rule messages without duplicate native feedback, presented-control write notifications and touch, and optional blur deferral through footer presses. See Native binding.

Use control: 'list' for free-text tags or recipient arrays. Its required rule requires an entry, minimum and maximum count entries, and email: true checks each address. Bind it to a native select multiple for repeated FormData values and authored-option reset. See List fields.

Development

npm install
npm test

License

MIT © Orkestrel — see LICENSE.