react-luna-form 0.0.81 → 0.0.82

package/docs/events/change.md

@@ -0,0 +1,391 @@
+# Change Event Documentation
+
+The `change` event in Luna Form allows you to trigger a sequence of actions whenever the value of a specific field is modified. A `change` event is configured as an array of objects, where each object defines a distinct action.
+
+Luna Form evaluates the array sequentially, applying the declared updates or conditions.
+
+## Value Interpolation
+
+In many actions (like `value`, `source`, and `state`), you may want to use the value of the field that triggered the change. You can use the special string `{value}` to capture and inject this value dynamically into strings or objects.
+
+Placeholders also support format filters with pipe syntax (`{value | filter:arg}`) for locale-aware formatting of currency, dates, percentages, and durations. See [Format Filters](../interpolation/format-filters.md) for the full reference.
+
+### Passing a structure rather than text
+
+A placeholder is normally replaced _inside_ a string, so what comes out is text. When the template is **nothing but one placeholder** and the value behind it is an object or an array, the `value` action hands that value over untouched instead:
+
+```json
+{
+  "action": "value",
+  "value": { "rows": "{preset_rows}" }
+}
+```
+
+If the triggering field's data carries `preset_rows` as an array, `rows` receives the array itself — not `"[object Object]"`, and not the literal `"{preset_rows}"`.
+
+Three cases do **not** qualify and stay text, exactly as before:
+
+- text around the placeholder — `"rows: {preset_rows}"`;
+- a format filter — `"{preset_rows | currency:USD}"`, which formats into text by definition;
+- a scalar behind the placeholder — `{value}` over the number `25` is still `"25"`.
+
+This is what makes an array of rows expressible in a definition at all, and it is how a `list` gets filled. See [Targeting a list](#targeting-a-list).
+
+## Target Resolution in Lists
+
+When working with fields inside a `list`, targets are resolved globally (from the form root) by default. To target another field within the **same list item**, use the following syntax:
+
+`"listName/fieldName"`
+
+This tells Luna Form to find the current iteration of `listName` and update the `fieldName` within that specific row.
+
+**Example:**
+If you have a list named `users` and you want one field to update another field called `nickname` in same row:
+
+```json
+{
+  "name": "fullname",
+  "event": {
+    "change": [
+      {
+        "action": "value",
+        "value": {
+          "users/nickname": "{value}"
+        }
+      }
+    ]
+  }
+}
+```
+
+If you specify `"nickname"` (without the list prefix and slash), it will attempt to update a field named `nickname` at the root of the form.
+
+## Supported Actions
+
+The `change` event array supports three action types, indicated by the `action` property: `value`, `state`, and `source`.
+
+---
+
+### 1. Value Action (`ValueEvent`)
+
+The `value` action is used to explicitly set or update the value of one or more fields elsewhere in the form when the current field changes.
+
+**Properties:**
+
+- `action` (string): Must be set to `"value"`.
+- `value` (object): A key-value mapping where each key represents a target field name, and the value is the new data to apply to that field. You can use string interpolation like `{value}` to pass the changed value.
+- `onlyIfTargetEmpty` (boolean, optional): If `true`, the target field's value will only be updated if it is currently empty. Useful for applying default or propagated values without overwriting user input. Ignored when the target is a `list` — a list has no single value to call empty.
+
+**Example:**
+
+```json
+{
+  "event": {
+    "change": [
+      {
+        "action": "value",
+        "onlyIfTargetEmpty": true,
+        "value": {
+          "billingAddress": "{value}",
+          "hasProvidedAddress": true
+        }
+      }
+    ]
+  }
+}
+```
+
+#### Targeting a list
+
+A `list` is a valid target. Give it an array of objects and it becomes exactly those rows — one object per row, each key matching a field name inside the list:
+
+```json
+{
+  "label": "Preset",
+  "name": "preset",
+  "type": "select",
+  "advanced": { "transient": true },
+  "source": [
+    { "label": "Empty", "value": "empty", "preset_rows": [] },
+    {
+      "label": "Two rows",
+      "value": "two",
+      "preset_rows": [
+        { "key": "alpha", "amount": "1" },
+        { "key": "beta", "amount": "2" }
+      ]
+    }
+  ],
+  "event": {
+    "change": [{ "action": "value", "value": { "rows": "{preset_rows}" } }]
+  }
+}
+```
+
+Points worth knowing:
+
+- **It assigns, it does not add.** The list ends up with the rows you gave it and nothing else; the values of the rows that went away are discarded. To append, send the current array plus the new element — the sender is the one that knows what is already there.
+- **`advanced.length` still applies.** A shorter array leaves the remainder standing and empty up to `min` and anything past `max` is dropped — the same clamp an initial `value` gets at mount, so a list holds the same rows however they arrived.
+- **Rows that survive keep their identity.** They are matched by position, so growing a list does not remount the rows already on screen, and a caret sitting in one of them stays put.
+- **A row that only carries some of the keys leaves the rest empty**, rather than keeping what the previous row in that position had.
+- **Assigning what is already there does nothing.** No rebuild, and no report to the consumer. Deduplication is still the sender's job, though: this only recognises an assignment that matches the list as a whole, and by the time it does the event has already been raised.
+
+A **nested** list works the same way, reached with the relative syntax described in [Target Resolution in Lists](#target-resolution-in-lists). A field inside a row of `group` fills the `items` list in its own row with `"group/items"`; the plain name would not reach it, because once rendered a nested list is called by its path (`group.0.items`).
+
+#### Rows that hold rows
+
+A row's key can name a field that is itself a `list`, in which case its value is that list's rows rather than a value. The whole tree is assigned in one event, as deep as the lists go:
+
+```json
+{
+  "action": "value",
+  "value": {
+    "groups": [
+      {
+        "name": "First",
+        "checks": [
+          { "key": "alpha", "amount": "1" },
+          { "key": "beta", "amount": "2" }
+        ]
+      },
+      { "name": "Second", "checks": [{ "key": "gamma", "amount": "3" }] }
+    ]
+  }
+}
+```
+
+Every rule above holds one level down as well: an inner list assigns rather than adds, honours its own `advanced.length`, and keeps the identity of the rows that survive. Two more only come up here:
+
+- **A row that names an inner list without giving it rows empties it.** `"checks": []`, a `checks` key holding something that is not rows, and no `checks` key at all all mean the same thing — none — rather than leaving behind what the row in that position had.
+- **The consumer is told once for the whole tree**, under the outer list's name, with the inner rows already in it. The inner lists then report their own paths (`groups.0.checks`) as they take their rows, the same way they do when a row is added or removed by hand.
+
+This is what the relative syntax cannot do. `"groups/checks"` reaches the inner list of the row the sender is sitting in, and `"groups.0.checks"` reaches the first one; neither can say "every group", so a control that appends a group has to assign the outer list and carry the inner rows along with it.
+
+The picker above is marked [`transient`](#transient-controls) because its job is to fill the list, not to hold a value of its own.
+
+#### Transient controls
+
+A field whose entire job is to write somewhere else can declare `"advanced": { "transient": true }`. It fires its change events and keeps nothing: it is not stored, and the consumer is never told about it.
+
+Without it, the control also saves whatever it emitted, and a value the user can neither see nor edit ends up in the submitted form and in whatever the consumer persists.
+
+Two consequences to expect:
+
+- **It shows nothing back**, because there is no value to show. On a visible text input, typing will not stick.
+- **Choosing the same value twice in a row acts twice**, where an ordinary field treats the repeat as a no-op. For a command that is the point — pressing a button again is meant to do the thing again.
+
+It does not go with `required` or `validation`, which would demand a value that by definition never arrives and block the submit with nothing on screen to explain why.
+
+---
+
+### 2. State Action (`StateEvent`)
+
+The `state` action modifies the interactive state or visibility of other fields based on the changed value.
+
+**Properties:**
+
+- `action` (string): Must be set to `"state"`.
+- `target` (string | array of strings): The field name, or an array of field names, that the state modifications should be applied to.
+- `state` (object): An object containing the new state to apply. Properties are independent of field names — the form may safely contain a field whose `name` is `"description"`, `"disabled"` or `"hidden"`; `target` identifies the field, the keys inside `state` configure it.
+  - `disabled` (boolean, optional): Whether the field should be disabled.
+  - `hidden` (boolean, optional): Whether the field should be hidden from view. **Note:** When a field becomes hidden (`hidden: true`), its current value is automatically cleared from the form state to ensure no non-applicable data is submitted.
+  - `description` (string | object, optional): A new description to render for the target field. Supports interpolation, format filters, and **Markdown** (specifically links). e.g. `"Check our [terms](https://example.com) for details."`.
+- `when` (string | array of strings | [Condition object](#the-condition-object), optional): A condition that specifies when this state should be applied.
+  - If a **string** is provided, it matches exactly against the field's new value.
+  - If an **array of strings** is provided, it performs an **OR match** (the state is applied if the field's new value matches _any_ string in the array).
+  - If a **Condition object** is provided, it evaluates complex logic.
+
+**Example:**
+
+```json
+{
+  "event": {
+    "change": [
+      {
+        "action": "state",
+        "target": ["creditCardNumber", "cvvCode"],
+        "state": {
+          "disabled": false,
+          "hidden": false
+        },
+        "when": "credit_card"
+      },
+      {
+        "action": "state",
+        "target": "paypalEmail",
+        "state": {
+          "hidden": false
+        },
+        "when": {
+          "operator": "eq",
+          "value": "paypal"
+        }
+      }
+    ]
+  }
+}
+```
+
+**Updating description with interpolation and filters:**
+
+```json
+{
+  "label": "Price",
+  "name": "price",
+  "type": "input/text",
+  "event": {
+    "change": [
+      {
+        "action": "state",
+        "target": "price",
+        "state": {
+          "description": "Total to pay: {value | currency:USD}"
+        },
+        "when": {
+          "operator": "neq",
+          "value": ""
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 3. Source Action (`SourceEvent`)
+
+The `source` action dispatches a request to a remote data source to fetch and populate data into a target field. This is commonly used for cascading selections (e.g., selecting a Country fetches its related States).
+
+**Properties:**
+
+- `action` (string): Must be set to `"source"`.
+- `target` (string): The target field that will receive the data resolved from the source request (like a "select" field for States).
+- `source` (DataSource object): The configuration object for fetching remote data (typically includes `url`, mapping keys, namespace, etc.).
+
+**Example:**
+
+```json
+{
+  "event": {
+    "change": [
+      {
+        "action": "source",
+        "target": "stateField",
+        "source": {
+          "url": "/api/states?countryId={value}"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## When a change event runs at mount
+
+A `change` event does not only fire when the user edits the field. A field that
+mounts already holding something — either a `value` passed to the form or its
+own `defaultValue` — runs its `change` events **once**, at mount.
+
+This is usually what you want: a form reopened on saved data arrives with the
+same fields revealed, the same targets cleared and the same sources fetched as
+when it was filled in. It is worth knowing about because it means the actions
+below run before the user has touched anything.
+
+Two details:
+
+- **It happens once.** Re-rendering does not fire it again.
+- **A select waits for its options.** For a field whose options come from a
+  `source`, the initial run is held until the data has loaded, so an action
+  keyed on the selected entity sees the entity rather than a bare value. Text
+  and date fields run as soon as the value is valid.
+
+A field that mounts empty and has no `defaultValue` does not run anything until
+it is edited.
+
+## Sequencing Actions
+
+Because `change` takes an array, multiple different events can be sequenced together to build complex logic flows.
+
+**Chained Example:**
+
+```json
+{
+  "name": "paymentMethod",
+  "type": "radio",
+  "event": {
+    "change": [
+      {
+        "action": "value",
+        "value": {
+          "transactionFee": "0.00"
+        }
+      },
+      {
+        "action": "state",
+        "target": "creditCardGroup",
+        "state": {
+          "hidden": true
+        },
+        "when": ["paypal", "bank_transfer"]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## The `Condition` Object
+
+In the `state` action (and potentially other areas), the `when` property can be defined as a `Condition` object for more complex logical evaluations, rather than a simple equality check.
+
+### Properties:
+
+- `operator` (string, optional): The logical operator to apply. Defaults to `"eq"` (equals). Supported operators are:
+  - `"eq"`: Equals
+  - `"neq"`: Not equals
+  - `"in"`: In array (value is within the specified list)
+  - `"nin"`: Not in array
+  - `"gt"`: Greater than
+  - `"gte"`: Greater than or equal
+  - `"lt"`: Less than
+  - `"lte"`: Less than or equal
+- `value` (string | number | array): The target value to compare against the field's current value.
+- `field` (string, optional): If specified, the condition evaluates the value of _another_ field instead of the field that triggered the change event.
+
+### Examples of Conditions
+
+**1. Greater Than Operator (`gt`):**
+Enable a "Discount Code" field only if the "Total Amount" is greater than 100.
+
+```json
+{
+  "action": "state",
+  "target": "discountCode",
+  "state": { "disabled": false },
+  "when": {
+    "operator": "gt",
+    "value": 100
+  }
+}
+```
+
+**2. Not In Array Operator (`nin`):**
+Hide a "State/Province" field if the selected "Country" is not in a specific list.
+
+```json
+{
+  "action": "state",
+  "target": "stateProvince",
+  "state": { "hidden": true },
+  "when": {
+    "operator": "nin",
+    "value": ["US", "CA", "MX"]
+  }
+}
+```
+
+---

package/docs/fields/custom-inputs.md

@@ -0,0 +1,128 @@
+# Custom Inputs
+
+A field `type` that this library does not ship can be implemented by the host
+application and registered under its own name. This is how a form gets a people
+picker, a credential selector, or any control that only makes sense inside one
+product.
+
+## Registering
+
+```ts
+import {
+  defineConfig,
+  defineCustomInput,
+  defineInput,
+} from 'react-luna-form/config'
+import { PeoplePicker } from './components/people-picker'
+
+export default defineConfig({
+  inputs: [
+    defineInput(Input),
+    defineCustomInput('people/picker', PeoplePicker),
+  ],
+})
+```
+
+`defineCustomInput(types, component)` takes one name or an array of names. Every
+name becomes a key in `config.inputs`.
+
+**The lookup is an exact string match.** There is no prefix resolution: naming a
+field `people/picker` does not fall back to `people`, and naming it
+`select/mine` does not fall back to `select`. `defineConfig` writes one entry per
+registered string, and rendering reads `config.inputs[field.type]` directly.
+
+**A type nothing registers renders nothing at all.** The lookup returns
+`undefined`, the field is skipped, and the form renders without it — on the
+server and on the client alike. There is no error, no warning and no
+placeholder, so a typo in a `type` looks exactly like a field somebody chose not
+to include. Check the spelling against your `defineConfig` when a field does not
+appear.
+
+## What your component receives
+
+Props are applied in this order:
+
+```tsx
+<Component
+  {...commonProps} // id, name, placeholder, disabled, required
+  {...ariaAttributes} // aria-invalid, aria-errormessage
+  {...dataAttributes} // data-invalid, data-readonly
+  {...extraProps} // whatever the field family adds
+  {...inputProps} // the prepared value or defaultValue
+  onBlur={onBlur}
+  onChange={onChange}
+/>
+```
+
+`onChange` and `onBlur` are applied **last**, after every spread. A component
+that forwards its props unchanged gets them for free. A component that declares
+its own handlers must call the ones it received, or the form never learns the
+value changed: validation will not run, and neither will any `change` event the
+field declares.
+
+## Forwarding `id` is what gives the field its name
+
+The label is rendered by this library, outside your component, as
+`<label htmlFor={field.name}>`. The matching `id` arrives in your props.
+
+If your component does not put that `id` on the element the user actually
+focuses, the label points at nothing. The field still works with a mouse, so
+nothing looks broken — but it has no accessible name, screen readers announce it
+as unlabelled, and a test that reaches fields by their label cannot find it.
+
+```tsx
+// Correct: the id reaches the real input.
+function PeoplePicker({ ...props }: React.ComponentProps<'input'>) {
+  return <input {...props} />
+}
+
+// Wrong: the id lands on a wrapper the label does not point to.
+function PeoplePicker({ id, ...props }: React.ComponentProps<'input'>) {
+  return (
+    <div id={id}>
+      <input {...props} />
+    </div>
+  )
+}
+```
+
+The same applies when you build on a component library: whatever primitive
+renders the focusable element is where the `id` belongs.
+
+## Clearing a value on a select-family type
+
+If you register a custom input under a `select` variant, be aware that an
+`onChange('')` is **discarded**, not applied. Radix and similar components
+re-emit `onChange("")` when a trigger remounts, and an empty string is never a
+real selection, so the library drops it rather than wipe a value the user
+already chose.
+
+The consequence for a custom input: emitting an empty string to clear the field
+does nothing. Emit a sentinel value your own code recognises, and translate it
+back where you read the form.
+
+This applies only to select-family fields. Text fields pass an empty string
+through unchanged.
+
+## Change events are debounced on text fields
+
+For `input/*` and `textarea`, a declared `change` event fires 300 ms after the
+last keystroke, not on every one. If you are testing a custom text input that
+triggers a change event, wait for that window rather than asserting immediately.
+
+Select-family fields dispatch straight away.
+
+## Server and client
+
+The same registered component is used by both render paths. If your custom
+input needs browser APIs, state or effects, mark it `'use client'` as you would
+any other component — the library does not do it for you.
+
+## Checklist
+
+Before shipping a custom input:
+
+- Its `type` string matches `defineCustomInput` exactly, character for character
+- The `id` it receives reaches the focusable element
+- It forwards or calls the `onChange` and `onBlur` it receives
+- If it is a select variant, it does not rely on `''` to clear

package/docs/fields/input.md

@@ -0,0 +1,175 @@
+# Input Fields (`input/*`, `textarea`, `checkbox`)
+
+The `input/*` field types in Luna Form map to standard HTML `<input>` elements. These fields are used for capturing text, numbers, dates, times, and other generic data values from the user.
+
+## Supported Types
+
+- `input`: Same as `input/text`. The rendered `type` is taken from the part after the last `/`, and a bare `input` falls back to `text`.
+- `input/text`: Standard text input (`<input type="text">`).
+- `input/email`: Email address input with built-in format validation (`<input type="email">`).
+- `input/password`: Password input with text masked (`<input type="password">`).
+- `input/number`: Numeric input (`<input type="number">`).
+- `input/tel`: Telephone number input (`<input type="tel">`).
+- `input/date`: Date picker component.
+- `input/time`: Time picker component.
+
+---
+
+## Core Properties
+
+Luna Form's input fields inherit the standard logical properties available to all fields:
+
+- **`name`** _(string, required)_: The unique identifier for the field in the form output.
+- **`type`** _(string, required)_: Evaluates the type of input to render (e.g., `"input/text"`, `"input/password"`).
+- **`label`** _(string, optional)_: The human-readable label shown to the user.
+- **`defaultValue`** _(any, optional)_: The initial value of the field when the form is mounted and no external value is provided.
+- **`description`** _(string | object, optional)_: Help text or extra context for the form field. Supports **Markdown** (specifically links).
+  - Can be a direct string.
+  - Or an object payload: `{ title: string, message: string, collapsed?: boolean }`.
+- **`placeholder`** _(string, optional)_: The temporary placeholder text shown when the input is empty.
+- **`required`** _(boolean, optional)_: If `true`, standard browser/HTML5 validation makes the field mandatory.
+- **`disabled`** _(boolean, optional)_: If `true`, the field is non-interactive and blocked from events.
+- **`readonly`** _(boolean, optional)_: If `true`, the field's value is locked and cannot be modified by the user.
+- **`hidden`** _(boolean, optional)_: If `true`, the field is hidden from the user interface.
+- **`order`** _(number, optional)_: A numeric order determining the field's position relative to adjacent fields.
+
+---
+
+## Advanced Configuration (`advanced` object)
+
+The `advanced` property dictates finer HTML details, interactive structures, and native HTML attributes.
+
+### Common Options
+
+- **`autocomplete`** _(string)_: Standard HTML autocomplete attribute (e.g., `"username"`, `"off"`).
+- **`cols`** _(number)_: Layout column span for CSS grid alignment.
+- **`horizontal`** _(boolean)_: Overrides configuration layout to render label and input horizontally.
+- **`reverse`** _(boolean)_: If `true`, reverses the flex direction.
+- **`aria`** _(object)_: Map of specific ARIA attributes for screen readers (e.g., `{ "aria-label": "Custom label" }`).
+- **`data`** _(object)_: Map of specific HTML data attributes (e.g., `{ "data-test-id": "my-field" }`).
+- **`transient`** _(boolean)_: If `true`, the field fires its change events and keeps nothing of its own — it is neither stored nor reported to the consumer. For a control whose whole job is to write to _another_ field. See [Transient controls](../events/change.md#transient-controls).
+
+### Text & Numeric Options (`input/text`, `input/email`, `input/tel`, `input/password`, `input/number`)
+
+These basic field types support extra manipulation properties inside the `advanced` block:
+
+- **`length`** _({ min?: number, max?: number })_: Applies HTML structural limits (`minlength` / `maxlength`, or `min` / `max` depending on the input type).
+- **`transform`** _(string | string[])_: Safely intercepts user inputs and manipulates content dynamically. Options include:
+  - `"lowercase"`
+  - `"uppercase"`
+  - `"remove-space"`
+  - `"remove-accent"`
+
+### Temporal Options (`input/date`, `input/time`)
+
+Date and time inputs omit transformations and instead expose a `format` property directly under `advanced` for displaying values properly:
+
+- **Date format** _(used with `input/date`)_: `"yyyy-MM-dd"`, `"MM/dd/yyyy"`, `"dd/MM/yyyy"`, or `"MMMM d, yyyy"`.
+- **Time format** _(used with `input/time`)_: `"HH:mm"`, `"HH:mm:ss"`, `"hh:mm a"`, or `"hh:mm:ss a"`.
+
+---
+
+## Validation (`validation` object)
+
+The `validation` object resolves form errors overriding generic defaults, mapping the constraint rule name directly to the specific error message string.
+
+- **`required`** _(string)_: Specifies the error message exposed when the element is marked exactly as `required: true` and the field is empty.
+- **`email`** _(string)_: Error message specifically asserting an invalid email format.
+- **`length`** _({ min?: string, max?: string })_: Specific string messages shown when input lengths are breached.
+- **`custom`** _(CustomValidation | CustomValidation[])_: Powerful conditional-based logic blocks. An array specifying:
+  - `field`: Optional target reference string.
+  - `operator`: Logical evaluation operations (e.g., `eq`, `neq`, `gt`, `lt`).
+  - `message`: The resulting validation string.
+- **`requiredWhen`** _(WhenRule | WhenRule[])_: Makes the field required only when a condition over a sibling field holds.
+- **`pattern`** _(PatternRule)_: Validates the value against a regular expression (with optional interpolation bypass).
+- **`rules`** _(AssertRule[])_: A list of gated assertions (`oneOf`, `min`/`max`, `pattern`, …).
+
+_See the full [Validation reference](../validation/overview.md) for `requiredWhen`, `pattern`, `rules`, the operator vocabulary, and headless (server-side) validation._
+
+---
+
+## Events (`event` object)
+
+You can attach logic-rich cascading events seamlessly directly inside the field schema.
+
+- **`event.change`** _(ChangeEvent[])_: Triggers actions when logic runs. Common actions include emitting `value`, interacting with dependencies (`state`), or triggering data refetches (`source`). _Refer to the [Change Event Documentation](../events/change.md) for robust logic breakdowns._
+
+---
+
+## Complete Example Reference
+
+```json
+{
+  "name": "username",
+  "type": "input/text",
+  "label": "User Nickname",
+  "placeholder": "e.g. john_doe",
+  "required": true,
+  "description": {
+    "title": "Rule",
+    "message": "No spaces. No special characters.",
+    "collapsed": true
+  },
+  "advanced": {
+    "transform": ["lowercase", "remove-space"],
+    "length": {
+      "min": 4,
+      "max": 20
+    }
+  },
+  "validation": {
+    "required": "You must provide a nickname to continue.",
+    "length": {
+      "min": "Your nickname needs at least 4 letters."
+    }
+  }
+}
+```
+
+---
+
+## `textarea`
+
+Multi-line text. It takes the same core properties as an `input/*` field, and
+two of the `advanced` options above apply to it: `length` and `autocomplete`.
+Everything else in `advanced` is ignored for this type.
+
+```json
+{
+  "name": "notes",
+  "type": "textarea",
+  "label": "Notes",
+  "advanced": {
+    "length": { "max": 500 }
+  }
+}
+```
+
+`length.min` and `length.max` are emitted as the `minLength` and `maxLength`
+attributes on the rendered element.
+
+Like the `input/*` family, a declared `change` event on a `textarea` is
+debounced: it fires 300 ms after the last keystroke, not on every one.
+
+---
+
+## `checkbox`
+
+A single boolean. It is the one field family whose value is not carried by
+`value`: the rendered element receives `checked` instead.
+
+```json
+{
+  "name": "accepted",
+  "type": "checkbox",
+  "label": "I accept the terms",
+  "required": true
+}
+```
+
+A checkbox reads its state by truthiness, not by presence. `defaultValue: true`
+starts it checked; `false`, an omitted value, `null` and `0` all start it clear.
+A value passed to the form is read the same way, and both render paths agree.
+
+For a group of options rather than a single flag, use `chips` or `radio` — see
+[select.md](select.md).