react-luna-form 0.0.83 → 0.0.84

package/docs/index.md

@@ -9,21 +9,27 @@ field descriptors is the single source for what renders **and** for the Zod
 schema that validates it. Most mistakes come from assuming otherwise.
 
 Start at [setup.md](setup.md) if you are wiring the form up for the first
-time: entry points, `defineConfig`, and the difference between the client and
-server `Form`.
+time: installing, styling, entry points, `defineConfig`, and the difference
+between the client and server `Form`.
 
 ## Where to look
 
 | You are                                                                      | Read                                                               |
 | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Grouping fields into a titled, collapsible or numbered section               | [structure/sections.md](structure/sections.md)                     |
+| Putting fields side by side, or a label beside its control                   | [structure/layout.md](structure/layout.md)                         |
+| Reusing one piece of JSON across the form                                    | [structure/definition.md](structure/definition.md)                 |
 | Declaring a text, number, date or password field                             | [fields/input.md](fields/input.md)                                 |
 | Declaring a `select`, `radio` or `chips` field, or filling one from a source | [fields/select.md](fields/select.md)                               |
 | Declaring a repeatable group of fields                                       | [fields/list.md](fields/list.md)                                   |
 | Looking for a date range, a color or another ready-made picker               | [fields/specialized-selectors.md](fields/specialized-selectors.md) |
 | Implementing a field type this library does not ship                         | [fields/custom-inputs.md](fields/custom-inputs.md)                 |
+| Filling a `select` from an API                                               | [fields/data-source.md](fields/data-source.md)                     |
 | Making a field required, or validating against another field                 | [validation/overview.md](validation/overview.md)                   |
+| Handling the submit, a server action or the error summary                    | [forms/submit.md](forms/submit.md)                                 |
 | Showing, hiding, clearing or filling a field when another one changes        | [events/change.md](events/change.md)                               |
-| Formatting an interpolated value inside a label or a message                 | [interpolation/format-filters.md](interpolation/format-filters.md) |
+| Writing a `{placeholder}` in a label, a description or an event              | [interpolation/overview.md](interpolation/overview.md)             |
+| Formatting an interpolated value as currency, a date or a duration           | [interpolation/format-filters.md](interpolation/format-filters.md) |
 
 ## Three things that surprise people
 

package/docs/interpolation/format-filters.md

@@ -2,6 +2,8 @@
 
 Format filters transform interpolated values into locale-aware strings using a pipe syntax inspired by Vue and Angular.
 
+This page is the filter reference. What a placeholder resolves against in the first place — and it is not the same set everywhere — is [Interpolation](overview.md).
+
 ## Where filters can be used
 
 Filters work in any string passed through Luna Form's interpolation engine, including:
@@ -27,6 +29,8 @@ Multiple filters can be chained; the output of the previous filter becomes the i
 
 Locale-aware filters read the locale from `config.env.locale`. If not set, filters fall back to the runtime default (typically the browser's locale).
 
+It applies wherever a filter is written — a label, a description, a `value` payload — so one setting keeps them consistent. See [Interpolation](overview.md#the-locale-filters-use).
+
 ```ts
 const config = {
   env: {

package/docs/interpolation/overview.md

@@ -0,0 +1,179 @@
+# Interpolation
+
+A `{placeholder}` in a form is resolved against a set of values that depends on
+**where the placeholder is written**. There are two of them, and most confusion
+about interpolation is one being read as the other.
+
+- **In rendered text** — a field's `label`, a field or column `description` —
+  the values are `context`, `env` and, in a description, that field's own
+  `value`.
+- **In an event payload** — what a [`value` action](../events/change.md#1-value-action-valueevent)
+  writes, and the `url` and `body` of a [`source` action](../events/change.md#3-source-action-sourceevent) —
+  the values are **the selected option itself**: `{value}`, `{label}` and every
+  other key the option carries.
+
+[Format filters](format-filters.md) work in both.
+
+## Where each namespace applies
+
+| Written in                        | Resolves against                        |
+| --------------------------------- | --------------------------------------- |
+| a field `label`                   | `context`, `env`                        |
+| a field `description`             | `context`, `env`, `value`               |
+| a column `description`            | `context`, `env`                        |
+| a `state` action's `description`  | `context`, `env`, `value` of the target |
+| a `value` action's payload        | the selected option                     |
+| a `source` action's `url`, `body` | the selected option                     |
+| a section `title`, `description`  | nothing — see below                     |
+
+## Rendered text
+
+`context` is a prop of the form and `env` is a key of
+[`defineConfig`](../setup.md#style-alert-env). Both are addressed by name, with
+dot notation for anything nested:
+
+```tsx
+<Form
+  sections={sections}
+  config={config}
+  context={{ user: { firstName: 'Jane' }, plan: 'pro' }}
+/>
+```
+
+```json
+{
+  "name": "greeting",
+  "type": "input/text",
+  "label": "Welcome {context.user.firstName}",
+  "description": "You are on the {context.plan} plan, billed in {env.currency}"
+}
+```
+
+Three details decide most of what you will hit:
+
+- **`{value}` is a description's, not a label's.** A description is rendered
+  with the field's current value in scope, so `{value}` there tracks what the
+  user typed. A label is not: the same placeholder in a `label` resolves to
+  nothing and stays on screen as the literal `{value}`.
+- **Interpolation runs first, translation second.** The resolved string is what
+  gets looked up in the [`translations`](../fields/list.md#localization)
+  dictionary, so a label written as `Welcome {context.user.firstName}` is
+  looked up as `Welcome Jane` — which is not a key anybody wrote. Translate the
+  whole sentence with the placeholder inside it (`"welcome_user": "Hola
+{context.user.firstName}"` keyed on the source text) rather than expecting the
+  key to survive.
+- **A section heading is not interpolated at all.** `title` and `description` on
+  a [section](../structure/sections.md#title-and-description-are-translated-not-interpolated)
+  are translated and take markdown links, but a placeholder in one is printed
+  as written. A column description is interpolated, so that is the place to put
+  one.
+
+## Event payloads
+
+What a change event carries is the **selected option**, not the form's values.
+For a field whose options are declared or fetched, that is the whole row behind
+the selection:
+
+```json
+{
+  "name": "country",
+  "type": "select",
+  "source": [
+    { "value": "cl", "label": "Chile", "dial": "+56" },
+    { "value": "mx", "label": "Mexico", "dial": "+52" }
+  ],
+  "event": {
+    "change": [
+      {
+        "action": "value",
+        "value": { "phone_prefix": "{dial}", "country_name": "{label}" }
+      }
+    ]
+  }
+}
+```
+
+Selecting Chile writes `+56` and `Chile`. The keys available are the keys of
+that option: there is no `{context.*}` or `{env.*}` here, and no way to read
+another field's value.
+
+Two shapes to keep in mind:
+
+- **A text, textarea or date field carries `{ value }` and nothing else.** There
+  is no option row behind it, so `{value}` is the only placeholder that resolves
+  in its events.
+- **A `chips` field carries its array** — see
+  [change.md](../events/change.md#when-a-change-event-runs-at-mount). `{value}`
+  is the array itself, and there is no `{label}` to read.
+
+When the option rows do not use `value` as their identifying key — a remote
+source mapped with `advanced.options` — the row is found through
+[`advanced.entity`](../fields/select.md#advancedentity). Without it the event
+sees only `{ value }` and every other placeholder stays literal.
+
+### A `state` description is interpolated by the field that shows it
+
+Unlike `value` and `source`, a [`state` action](../events/change.md#2-state-action-stateevent)
+stores its `description` as written and the **target** interpolates it when it
+renders. So `{value}` in that description is the target field's own value, not
+the value of the field whose change set it.
+
+Aimed at the field that raised the event — the common case — the two are the
+same thing, which is why this rarely comes up:
+
+```json
+{
+  "action": "state",
+  "target": "price",
+  "state": { "description": "Total to pay: {value | currency:USD}" }
+}
+```
+
+Aimed at a different field, `{value}` reads that other field, and it is empty
+until somebody fills it.
+
+## Resolution rules
+
+- **Dot notation walks objects.** `{context.user.firstName}`, `{env.branding.name}`.
+- **A key that resolves to nothing is left alone.** The placeholder stays in the
+  text exactly as written — `{context.missing}` renders as `{context.missing}`.
+  This is deliberate: a half-rendered sentence is easier to spot than a blank.
+- **So is a value that is not a scalar.** A placeholder standing for an object or
+  an array is left literal in text. The one exception is a `value` action, where
+  a template that is _nothing but_ the placeholder hands the structure over
+  untouched — that is what fills a
+  [list](../events/change.md#targeting-a-list).
+- **An unknown filter leaves the whole placeholder.** `{total | nope}` renders as
+  `{total | nope}` rather than dropping the value.
+- **Spaces are trimmed.** `{ value }` and `{value}` are the same placeholder, as
+  are `{total|currency:USD}` and `{total | currency:USD}`.
+
+## The locale filters use
+
+Locale-aware filters read `config.env.locale`:
+
+```ts
+defineConfig({ inputs: [...], env: { locale: 'es-ES', currency: 'EUR' } })
+```
+
+It reaches every filter the form renders — a label and a description format the
+same value the same way. With no `locale` set, filters fall back to the locale of
+whatever is running the code: the browser in the client form, the process in the
+server one, which are not always the same machine. Set it once in `env` and both
+renders agree.
+
+## An unresolved placeholder cancels a request
+
+A `source.url` still holding a `{placeholder}` after interpolation is **not
+fetched**. The field renders with no options, no request appears in the network
+panel, and nothing is logged: from the outside it looks exactly like an empty
+response.
+
+That is the intended behaviour — a cascading select should not call
+`/api/states?country={value}` before a country is picked — but it is also what a
+typo produces. A field that never fetches is worth checking for a placeholder
+that nothing resolves, before checking the network.
+
+A URL that _is_ fully resolved and still comes back empty is a different
+problem: see [`fetcher.remotePatterns`](../setup.md#fetcherremotepatterns),
+which does log when it blocks one.

package/docs/setup.md

@@ -4,6 +4,55 @@ How a form is configured and rendered. The pages under `fields/`,
 `validation/` and `events/` describe the JSON; this one describes the code
 around it.
 
+## Installing
+
+```bash
+pnpm add react-luna-form
+```
+
+The package carries no dependencies of its own: everything it needs is a peer
+dependency, so your application resolves one copy of React, Zod and the rest.
+
+| Peer                    | Version             | Used for                                    |
+| ----------------------- | ------------------- | ------------------------------------------- |
+| `react`, `react-dom`    | `^19.0.0`           | rendering, and `useActionState` on submit   |
+| `zod`                   | `^4.0.0`            | the schema derived from `sections`          |
+| `jotai`, `jotai-family` | `^2.0.0` / `^1.0.0` | the value, error and source stores          |
+| `swr`                   | `^2.0.0`            | fetching a field's remote `source`          |
+| `date-fns`              | `^4.0.0`            | date and time formatting, `duration` filter |
+| `fast-equals`           | `^6.0.0`            | change detection in the stores              |
+| `tailwind-merge`        | `^3.5.0`            | merging the classes the components render   |
+
+None of them is optional, and none is bundled. A package manager that installs
+peers automatically (npm 7+, or pnpm with `auto-install-peers=true`) brings
+them in for you; anywhere else, install them alongside the library. A missing
+peer surfaces as a module resolution error at import time, not as a form that
+renders badly.
+
+## Styling
+
+The components render Tailwind utility classes and **the build ships no CSS**.
+With [Tailwind CSS v4](https://tailwindcss.com) installed, point it at the
+package so the classes inside the published bundle are generated:
+
+```css
+@import 'tailwindcss';
+
+@source '../node_modules/react-luna-form';
+```
+
+Without that `@source` line every class the library renders is scanned out as
+unused: the markup is correct, the labels and inputs are all there, and none of
+the layout is — which reads as a broken build rather than a missing line of
+CSS.
+
+Every element also carries a `data-slot` attribute — `field`, `field-label`,
+`field-control`, `field-set`, `field-set-content`, `field-content`,
+`field-group`, `field-separator`, `column`, `list-item-card` — so a design
+system can restyle the structure without patching the library. The components
+you register yourself are yours to style; these slots cover the scaffolding
+around them.
+
 ## Entry points
 
 | Import                   | Contains                                                                                  |
@@ -57,7 +106,7 @@ Pass every key you still want.
 
 ### `fetcher.remotePatterns`
 
-Which hosts a field's remote `source` may call. The rules:
+Which hosts a field's remote `source` may call — the source itself is documented in [fields/data-source.md](fields/data-source.md). The rules:
 
 | Value   | Effect                               |
 | ------- | ------------------------------------ |
@@ -95,19 +144,21 @@ Check the console when a remote source comes back empty.
 The client form. It owns its own state, so it is the one to use for anything
 interactive.
 
-| Prop                                      | Purpose                                                                |
-| ----------------------------------------- | ---------------------------------------------------------------------- |
-| `sections`                                | the field descriptors — the form itself                                |
-| `config`                                  | the result of `defineConfig`                                           |
-| `value`                                   | the current values                                                     |
-| `action`                                  | server action invoked on submit, receives the form data and the schema |
-| `onSuccess`                               | called with the parsed data after `action` succeeds                    |
-| `onValueChange`                           | called with `{ name, value }` on every change                          |
-| `readOnly`                                | renders every field disabled                                           |
-| `translations`                            | per-locale strings for labels, options and messages                    |
-| `lang`                                    | the locale to resolve `translations` against                           |
-| `context`                                 | arbitrary values available to interpolation                            |
-| `definition`, `advanced.step`, `children` | multi-step and custom controls                                         |
+| Prop            | Purpose                                                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------- |
+| `sections`      | the field descriptors — the form itself                                                                         |
+| `config`        | the result of `defineConfig`                                                                                    |
+| `value`         | the current values                                                                                              |
+| `action`        | server action invoked on submit, receives the form data and the schema — see [forms/submit.md](forms/submit.md) |
+| `onSuccess`     | called with the parsed data after `action` succeeds                                                             |
+| `onValueChange` | called with `{ name, value }` on every change                                                                   |
+| `readOnly`      | renders every field disabled                                                                                    |
+| `translations`  | per-locale strings for labels, options and messages                                                             |
+| `lang`          | the locale to resolve `translations` against                                                                    |
+| `context`       | arbitrary values available to interpolation                                                                     |
+| `definition`    | the JSON that [`$ref`](structure/definition.md) entries resolve against                                         |
+| `advanced.step` | numbers the [sections](structure/sections.md#advancedstep-numbers-the-sections)                                 |
+| `children`      | the form's control area — see [forms/submit.md](forms/submit.md#nothing-submits-without-a-control)              |
 
 ### `Form` from `react-luna-form/server`
 

package/docs/structure/definition.md

@@ -0,0 +1,99 @@
+# Definition and `$ref`
+
+A definition names a piece of JSON once so the rest of the form can point at it.
+Anywhere inside `sections`, an object shaped `{ "$ref": "#/definition/<path>" }`
+is replaced by whatever `<path>` holds in the `definition` you pass alongside
+them.
+
+```tsx
+<Form sections={sections} definition={definition} config={config} />
+```
+
+```json
+{
+  "definition": {
+    "sources": {
+      "countries": { "url": "/api/countries", "namespace": "results" }
+    }
+  },
+  "sections": [
+    {
+      "fields": [
+        {
+          "name": "origin",
+          "type": "select",
+          "label": "Origin",
+          "source": { "$ref": "#/definition/sources.countries" }
+        },
+        {
+          "name": "destination",
+          "type": "select",
+          "label": "Destination",
+          "source": { "$ref": "#/definition/sources.countries" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## The path is dotted, not slashed
+
+Everything after `#/definition/` is a **dot path** into the definition object:
+`#/definition/sources.countries`, never `#/definition/sources/countries`. The
+prefix is the only part that uses slashes, and it looks enough like a JSON
+Pointer to be written the wrong way on the first try.
+
+## What can be a reference
+
+Any object in the tree. The `$ref` object is replaced whole, so a reference can
+stand for a `source`, an array of options, a whole field, or the `fields` of a
+section:
+
+```json
+{
+  "definition": {
+    "email": {
+      "name": "email",
+      "type": "input/email",
+      "label": "Email",
+      "required": true
+    }
+  },
+  "sections": [{ "fields": [{ "$ref": "#/definition/email" }] }]
+}
+```
+
+References inside a definition are resolved too, so one entry can be built out
+of others.
+
+## The rules
+
+- **Resolution happens once, before anything else.** The tree is resolved first,
+  and only then filtered and sorted, so an `order` or a `hidden` that arrives
+  through a reference behaves like one written in place.
+- **An unresolved path leaves the reference standing.** Nothing throws: the node
+  stays as the literal `{ "$ref": ... }` object. What that looks like on screen
+  depends on where it was — a field whose `source` is still a reference renders
+  with no options at all, which is the usual way a typo in the path is noticed.
+- **An empty or missing `definition` resolves nothing.** `definition={{}}` is
+  treated as absent, and every `$ref` in the form is left as written.
+- **A cycle stops instead of hanging.** Two entries pointing at each other
+  resolve until the loop closes and leave the reference that would repeat
+  unresolved.
+
+## Pass it everywhere the sections go
+
+`definition` is a prop of both the client and the server `Form`, and the third
+argument of the headless builder:
+
+```ts
+import { buildFormSchema } from 'react-luna-form/schema'
+
+const schema = buildFormSchema(sections, translations, definition)
+```
+
+A schema built without the definition sees `$ref` objects where the form sees
+fields — the rendered form and the validated shape drift apart, which is the one
+thing [the schema being derived from the same descriptors](../validation/overview.md#headless-validation)
+is meant to prevent.

package/docs/structure/layout.md

@@ -0,0 +1,189 @@
+# Layout
+
+Inside a section, fields stack one per row. Everything else — fields side by
+side, a label beside its control — is opt in, and this page is where those keys
+live.
+
+## Columns (`type: "column"`)
+
+A `column` is a grid that holds fields. It is declared among the fields of a
+section (or of a [list](../fields/list.md) row) and takes a `fields` array of
+its own:
+
+```json
+{
+  "type": "column",
+  "advanced": { "cols": 2 },
+  "fields": [
+    { "name": "first_name", "type": "input/text", "label": "First name" },
+    { "name": "last_name", "type": "input/text", "label": "Last name" }
+  ]
+}
+```
+
+A column has no `name` and holds no value. It groups its fields visually and
+nothing more: they keep the names they declare, and the submitted object is the
+same one you would get without it.
+
+| Key             | Type                   | Does                                       |
+| --------------- | ---------------------- | ------------------------------------------ |
+| `type`          | `"column"`             | required, exactly this string              |
+| `fields`        | `Array<Field \| List>` | what the grid holds                        |
+| `advanced.cols` | `1 \| 2 \| 3`          | how many columns the grid has, default `2` |
+| `description`   | `string \| object`     | help text under the grid                   |
+| `order`         | `number`               | position among the section's other entries |
+
+### `cols`, and the values that are not
+
+`cols` accepts `1`, `2` and `3`. **Anything else falls back to `2`** —
+`"cols": 4`, `"cols": 0`, a string, or the key left out entirely all produce the
+same two-column grid, with no error and no warning. A four-column layout is not
+something to reach for by writing `4`; it does not exist.
+
+The grid is one column below the `md` breakpoint and `cols` columns from there
+up, so a column layout stacks on a phone whatever it says.
+
+### A field's own `cols` is a span
+
+Inside a column, a field's `advanced.cols` says how many of the grid's columns
+that field takes:
+
+```json
+{
+  "type": "column",
+  "advanced": { "cols": 3 },
+  "fields": [
+    {
+      "name": "card_number",
+      "type": "input/text",
+      "label": "Card number",
+      "advanced": { "cols": 2 }
+    },
+    { "name": "cvc", "type": "input/text", "label": "CVC" }
+  ]
+}
+```
+
+The card number takes two of the three columns and the CVC takes the third.
+Spans of `1`, `2` and `3` are honoured and anything else is ignored, leaving the
+field at one cell — unlike the container's `cols`, an out-of-range span does not
+fall back to a default.
+
+The same key means different things in the two places, which is worth reading
+twice: on a `column` it is **how many columns the grid has**, on a field inside
+it, **how many of them the field covers**.
+
+A field's span outside a column does nothing at all. The class is emitted, the
+parent is not a grid, and the field goes on filling the width.
+
+### Description
+
+A column's `description` renders **under** the grid, not above it, and unlike a
+[section's description](sections.md#title-and-description-are-translated-not-interpolated)
+it goes through interpolation: `{context.*}`, `{env.*}` and
+[format filters](../interpolation/format-filters.md) all resolve. It also takes
+the `{ title, message, collapsed }` object form that a field description takes.
+
+### What a column can hold
+
+Fields and [lists](../fields/list.md). A column inside a list row is supported
+and keeps its grid; the fields inside it are named by the row's path like any
+other leaf.
+
+A column has no visibility of its own: `hidden` on a column is not read. Hide
+the fields it holds instead — and note that when every field in a column is
+hidden, the column counts as hidden for the
+[section's visibility](sections.md#order-and-what-disappears), while the grid
+element itself stays in the layout.
+
+### Labels truncate inside a grid
+
+A label that is longer than its cell is truncated to one line inside a column,
+where the same label wraps outside one. This keeps the inputs of a row aligned
+with each other instead of one sinking below its neighbour. Write the short
+version in the `label` and put the rest in the `description`.
+
+## Ordering fields and columns
+
+Every entry in a `fields` array — a field, a column, a list — sorts by `order`
+before rendering. Entries carrying one sort ascending; entries without one hold
+their relative position and follow the rest. Because a column sorts as a single
+entry, `order` interleaves whole columns with the plain fields around them, not
+the fields inside them.
+
+## Orientation (`advanced.horizontal`)
+
+By default a field renders its label above its control. `advanced.horizontal`
+puts them side by side from the `md` breakpoint up:
+
+```json
+{
+  "name": "timeout",
+  "type": "input/number",
+  "label": "Timeout",
+  "advanced": { "horizontal": true }
+}
+```
+
+A form that wants every field that way sets it once as
+`style.horizontal` in [`defineConfig`](../setup.md#style-alert-env). A field
+that declares nothing inherits it; one that declares `false` opts out of it.
+
+Two consequences:
+
+- **`radio` and `checkbox` are always horizontal**, whatever the key or the
+  form-wide style says. Their control belongs beside its label, so neither is
+  read for them.
+- **The description moves.** A vertical field renders its description after the
+  control; a horizontal one renders it under the label, in the label's own
+  column.
+
+The rendered field carries `data-orientation="horizontal"` or `"vertical"`,
+which is the attribute to key CSS on rather than the class names.
+
+## `advanced.reverse` (checkbox only)
+
+A `checkbox` renders its box first and its label after it. `reverse: false`
+swaps them:
+
+```json
+{
+  "name": "accepted",
+  "type": "checkbox",
+  "label": "I accept the terms",
+  "advanced": { "reverse": false }
+}
+```
+
+The default is the reversed order, so this key exists to turn it **off**, and
+`"reverse": true` changes nothing. It is read only for `checkbox`; on a `radio`,
+an `input/*` or anything else it is ignored.
+
+## Spacing
+
+Spacing between fields is a property of the section that holds them, not of the
+field: see [`advanced.compact`](sections.md#advancedcompact).
+
+## Styling hooks
+
+Every structural element carries a `data-slot`, so a design system can restyle
+the scaffolding without patching the library. The components you register in
+[`defineConfig`](../setup.md#inputs-required) are yours already; these are the
+parts around them.
+
+| `data-slot`         | Wraps                                                   |
+| ------------------- | ------------------------------------------------------- |
+| `field-set`         | one section, the rendered `<fieldset>`                  |
+| `field-set-content` | the body of a collapsible section                       |
+| `field-group`       | the stack of entries inside a section                   |
+| `field-separator`   | the rule drawn by `advanced.separator`                  |
+| `column`            | the grid of a `column`                                  |
+| `field`             | one field, with `data-orientation` on it                |
+| `field-label`       | the `<label>`                                           |
+| `field-content`     | the label and, when horizontal, the description with it |
+| `field-control`     | the form's own control area — where `children` renders  |
+| `list-item-card`    | one row of a [list](../fields/list.md)                  |
+
+A field also carries `data-invalid` while it holds an error and `data-readonly`
+while it is disabled, both readable from the descendants with
+`group-data-[...]`.