react-luna-form 0.0.82 → 0.0.84

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-[...]`.

package/docs/structure/sections.md

@@ -0,0 +1,187 @@
+# Sections
+
+`sections` is the top level of a form. Every other page describes what goes
+inside one; this page describes the section itself.
+
+A section is a **visual grouping and nothing else**. It draws a legend, sets the
+spacing around its fields and can collapse them out of the way, but it does not
+scope names: every field in the form shares one flat namespace, whichever
+section it was declared in. Two fields called `email` in two different sections
+are one field with two renderings, and
+[`buildFormSchema`](../validation/overview.md#headless-validation) produces one
+key for them.
+
+## The shape
+
+| Key                    | Type               | Does                                          |
+| ---------------------- | ------------------ | --------------------------------------------- |
+| `fields`               | `Fields`           | what the section renders                      |
+| `title`                | `string`           | the legend                                    |
+| `description`          | `string`           | help text under the legend                    |
+| `id`                   | `string \| number` | the `id` attribute of the rendered `fieldset` |
+| `order`                | `number`           | position among the other sections             |
+| `advanced.compact`     | `boolean`          | tighter spacing between this section's fields |
+| `advanced.collapsible` | `boolean`          | render the section closed, behind a toggle    |
+| `advanced.separator`   | `boolean`          | draw a rule after the section                 |
+
+```json
+{
+  "sections": [
+    {
+      "id": "payment",
+      "title": "Payment Method",
+      "description": "All transactions are secure and encrypted",
+      "advanced": { "separator": true },
+      "fields": [{ "name": "name", "type": "input/text", "label": "Name" }]
+    }
+  ]
+}
+```
+
+## A section with no title and no description draws nothing
+
+There is no empty legend and no wrapper to style around it: the section's fields
+join the flow of the form as if they had been declared without one. This is the
+form to reach for when you want the grouping only for `compact` spacing or for
+`order`.
+
+Declaring `advanced.collapsible` on such a section does nothing either — with no
+title there is nothing to click, so the fields render open.
+
+## Title and description are translated, not interpolated
+
+Both are resolved against the [`translations`](../fields/list.md#localization)
+dictionary and both render `[text](url)` markdown links. Neither is passed
+through interpolation: a `{context.name}` in a section title stays on screen as
+the literal text `{context.name}`.
+
+This is the one place the rule differs. A field's `label` and `description`
+_are_ interpolated, and so is a [column's description](layout.md#description).
+If a section heading has to carry a value, put the value in a field description
+or in a column instead.
+
+## `advanced.compact`
+
+Spacing between the fields of this section, tight instead of loose. It is
+declared per section:
+
+```json
+{
+  "title": "Connection",
+  "advanced": { "compact": true },
+  "fields": [{ "name": "host", "type": "input/text" }]
+}
+```
+
+A section that declares nothing inherits `style.compact` from
+[`defineConfig`](../setup.md#style-alert-env), so the form-wide default holds
+and a section only has to speak up to differ from it — including to opt out,
+with `"compact": false` under a compact form.
+
+## `advanced.separator`
+
+Draws a horizontal rule **after** the section, between it and whatever follows.
+On the last section it draws a trailing rule, which is rarely what you want.
+
+## `advanced.collapsible`
+
+Renders the section closed, with its title as the toggle:
+
+```json
+{
+  "title": "Advanced options",
+  "advanced": { "collapsible": true },
+  "fields": [{ "name": "timeout", "type": "input/number" }]
+}
+```
+
+Three things to know before using it:
+
+- **It always starts closed.** There is no key that opens it, and reopening the
+  form does not remember that the user had expanded it.
+- **The fields inside stay mounted.** Collapsing hides them; it does not unmount
+  them. They keep their values, they still validate, and they are still
+  submitted. That is the opposite of what a [`state` action](../events/change.md#what-clearing-a-hidden-target-means)
+  does when it hides a field, which unmounts it and clears the value.
+- **The description moves inside.** It renders with the fields rather than under
+  the title, so it is not visible while the section is closed.
+
+A collapsible section also renders no step number, whatever `advanced.step` says.
+
+## `advanced.step` numbers the sections
+
+Declared on the **form**, not on a section, it puts a numbered badge beside each
+section's legend, counting the sections in the order they render:
+
+```tsx
+<Form advanced={{ step: true }} sections={sections} config={config} />
+```
+
+It is a numbering, not a wizard: every section is on screen at once, and the
+library ships nothing that shows them one at a time. The badge appears only on
+sections that draw a legend — a section with no title and no description has
+nowhere to put it, and a collapsible one does not take it.
+
+## `order`, and what disappears
+
+`sections` renders in array order unless a section declares `order`. Sections
+carrying one sort ascending; sections without one keep their relative order and
+follow the rest. The same rule applies to the entries inside a section, so a
+field and a column can be interleaved by `order` — see
+[layout.md](layout.md#ordering-fields-and-columns).
+
+Two kinds of section never render at all:
+
+- **One with no fields.** `"fields": []` is dropped before rendering, legend
+  included.
+- **One whose fields are all hidden.** Hidden by `hidden: true` in the JSON or
+  by a [`state` action](../events/change.md#2-state-action-stateevent) at run
+  time, it makes no difference: when nothing inside a section is visible the
+  section goes with it, and it comes back when one of them is shown again. A
+  column counts as hidden when every field in it is.
+
+A section has **no visibility flag of its own**. Writing `"hidden": true` on a
+section is accepted and ignored; hide its fields instead, or leave the section
+out of the array.
+
+## `id`
+
+Lands on the rendered `<fieldset>` as its `id` attribute, for an anchor link or
+a test selector. It is not a name and nothing resolves against it: fields are
+addressed by their own `name` from anywhere in the form.
+
+## Complete example
+
+```json
+{
+  "advanced": { "step": true },
+  "sections": [
+    {
+      "id": "contact",
+      "title": "Contact",
+      "description": "How we reach you about this order",
+      "advanced": { "separator": true },
+      "fields": [
+        { "name": "email", "type": "input/email", "label": "Email" },
+        { "name": "phone", "type": "input/tel", "label": "Phone" }
+      ]
+    },
+    {
+      "title": "Delivery",
+      "advanced": { "compact": true },
+      "fields": [
+        { "name": "street", "type": "input/text", "label": "Street" },
+        { "name": "city", "type": "input/text", "label": "City" }
+      ]
+    },
+    {
+      "title": "Advanced options",
+      "advanced": { "collapsible": true },
+      "order": 99,
+      "fields": [
+        { "name": "notes", "type": "textarea", "label": "Delivery notes" }
+      ]
+    }
+  ]
+}
+```

package/docs/validation/overview.md

@@ -251,7 +251,7 @@ if (!result.success) {
 }
 ```
 
-- **`buildFormSchema(sections, translations?, definition?)`** — walks the form tree (sections → columns → lists → fields) and returns a Zod schema. Lists become arrays of objects, so nested `requiredWhen`/`rules` resolve in **item scope**. `translations` maps messages to localized strings; `definition` resolves `$ref` sources.
+- **`buildFormSchema(sections, translations?, definition?)`** — walks the form tree (sections → columns → lists → fields) and returns a Zod schema. Lists become arrays of objects, so nested `requiredWhen`/`rules` resolve in **item scope**. `translations` maps messages to localized strings; `definition` resolves [`$ref` entries](../structure/definition.md), and has to be the same one the form renders with.
 - **`collectIssues(error)`** — flattens a `ZodError` into `{ path, message }` entries with **dotted paths** (e.g. `rules.0.value`), including nested list issues.
 
 ### What each path validates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.82",
+  "version": "0.0.84",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -31,11 +31,11 @@
   },
   "devDependencies": {
     "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.4",
+    "@types/react-dom": "19.2.5",
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.1.1",
-    "eslint-plugin-react-refresh": "0.5.4",
-    "@luna-form/core": "0.0.82"
+    "eslint-plugin-react-refresh": "0.5.5",
+    "@luna-form/core": "0.0.84"
   },
   "license": "Apache-2.0",
   "repository": {