react-luna-form 0.0.83 → 0.0.85

package/docs/forms/submit.md

@@ -0,0 +1,129 @@
+# Submitting
+
+What happens between the user pressing the button and your code receiving an
+object. This page is about the client `Form` — the server one renders fields and
+has no submit path of its own.
+
+## Nothing submits without a control
+
+The library renders no button. Whatever you pass as `children` becomes the
+form's control area:
+
+```tsx
+<Form sections={sections} config={config} action={save}>
+  {({ isPending }) => (
+    <button type="submit" disabled={isPending}>
+      {isPending ? 'Saving…' : 'Save'}
+    </button>
+  )}
+</Form>
+```
+
+A plain node works as well; the function form is what gets `isPending`, which is
+true from the moment the action starts until it settles.
+
+## The pipeline
+
+On submit, in this order:
+
+1. **The form data becomes an object.** A name that appears more than once
+   arrives as an array; everything else as a single value.
+2. **Date fields are normalized.** A date input holds its value in the display
+   format the field declares, and it is converted back to a native date before
+   validation, so the schema and your action see one shape whatever
+   `advanced.format` says.
+3. **It is validated** against the schema built from the fields that are
+   currently mounted.
+4. **Dotted names are un-flattened.** `basicAuth.username` becomes
+   `{ basicAuth: { username } }`, and a numeric segment becomes an array index,
+   so `rules.0.value` rebuilds the list — with the gaps of removed rows closed
+   up.
+5. **Your `action` is awaited** with that object and the schema.
+6. **`onSuccess` is called** with what the action returned, and the form clears
+   itself.
+
+## Only mounted fields are validated
+
+The client schema is assembled from the fields on screen. A field hidden by a
+[`state` action](../events/change.md#2-state-action-stateevent) is unmounted, so
+it is absent from the schema and from the submitted object — which is the point:
+a rule that does not apply cannot block a submit.
+
+The consequence is that the browser check is narrower than the
+[headless one](../validation/overview.md#headless-validation).
+`buildFormSchema` walks the whole tree, item-scoped rules and list lengths
+included. A server that re-validates with it is not repeating the client's work;
+it is doing the part the client structurally cannot.
+
+## What `action` receives and returns
+
+```ts
+type FormState<T> = {
+  data: T | null
+  error: {
+    title: string
+    description?: string
+    details?: string[] | Record<string, string[]>
+  } | null
+  success: boolean
+}
+
+async function save(
+  data: Payload,
+  schema?: ZodSchema
+): Promise<FormState<Saved>> {
+  const stored = await api.save(data)
+  return { data: stored, error: null, success: true }
+}
+```
+
+The schema is handed over with the data so a server action can re-parse the same
+rules rather than reconstructing them.
+
+Three ways it can end:
+
+- **`success: true`** — `onSuccess` receives `data`, and the form clears.
+- **`success: false`** — the `error` you return is rendered by the form's
+  [alert](../setup.md#style-alert-env), untouched. This is where a server-side
+  failure ("that email is already registered") belongs.
+- **It throws** — the error is caught and logged, and the alert shows a generic
+  title with the thrown message as its detail. A rejection is a bug report, not
+  a message for the user; return `success: false` for anything you want them to
+  read.
+
+## The form empties on a successful submit
+
+Once the action succeeds the values are cleared and the inputs come back blank.
+For the usual "submit and move on" this is what you want, and for a form that
+should keep what was submitted it is a surprise.
+
+If the values have to survive, hold them outside the form: mirror
+`onValueChange` into your own state and feed it back through `value` — see
+[`withDeclaredFields`](../setup.md#withdeclaredfields) for the part that trips
+people, which is that a key you stop sending is not the same as a key you send
+empty.
+
+A **failed** validation is the opposite: the submitted values are handed back to
+the form, so the user's typing is still on screen next to the errors.
+
+## Turning submit validation off
+
+`defineConfig({ validation: { submit: false, ... } })` skips the parse
+entirely. The action is called with the raw `FormData` and the schema, and
+nothing is checked, reported or cleared on the way — for a form whose action
+does its own parsing. With no action at all, submitting does nothing.
+
+Remember that this object [replaces the defaults rather than merging](../setup.md#validation),
+so pass the keys you still want.
+
+## The error summary
+
+When a validation fails, two things happen at once: each field is told about its
+own errors, and the form reports a summary. The summary renders only when
+`validation.showError` is on and a component is registered as `alert`; without
+one, the per-field messages are all the user sees.
+
+Its three strings — the title, the "correct the errors" description, and the
+title used when an action throws — are
+[shipped translations](../fields/list.md#built-in-translations), so `lang` alone
+localizes them.

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.