react-luna-form 0.0.82 → 0.0.84

package/docs/fields/data-source.md

@@ -0,0 +1,113 @@
+# Data Sources
+
+The options of a `select`, `radio` or `chips` can be written in the schema or
+fetched. This page is the fetched half: the shape of a `DataSource`, when a
+request is actually made, and what happens when one is not.
+
+Declaring options inline is covered in [select.md](select.md#1-static-options),
+and mapping a fetched row onto `{ label, value }` in
+[Property Mapping Reference](select.md#property-mapping-reference).
+
+## The shape
+
+```json
+{
+  "name": "country",
+  "type": "select",
+  "label": "Country",
+  "source": {
+    "url": "/api/countries",
+    "method": "GET",
+    "namespace": "data.results",
+    "headers": { "X-Tenant": "acme" },
+    "cache": "no-store"
+  }
+}
+```
+
+| Key         | Type                 | Does                                               |
+| ----------- | -------------------- | -------------------------------------------------- |
+| `url`       | `string`, required   | relative or absolute                               |
+| `method`    | `string`             | defaults to `GET`                                  |
+| `namespace` | `string`             | dot path to the array inside the response          |
+| `headers`   | `HeadersInit`        | merged over `Accept: application/json`             |
+| `body`      | `object \| BodyInit` | query parameters on a `GET`, a JSON body otherwise |
+| `cache`     | `RequestCache`       | passed through to `fetch`                          |
+
+## `body` changes meaning with the method
+
+On a `GET`, each key of `body` is appended to the URL as a query parameter, and
+keys holding `undefined` are dropped rather than sent as the string
+`"undefined"`. On anything else the body is serialized as JSON and
+`Content-Type: application/json` is added for you.
+
+## `namespace` reaches into the response
+
+An API that answers with the array itself needs nothing. One that wraps it needs
+the dot path to it:
+
+```json
+{ "url": "/api/countries", "namespace": "data.results" }
+```
+
+If the response is already an array, `namespace` is ignored. If the path does
+not lead to an array, the field renders with no options — the same outcome as an
+empty response.
+
+## When a request is made, and when it is not
+
+Four ways to end up with an empty field and no request:
+
+- **The source is an array.** Inline options are used as they are.
+- **The URL still holds a placeholder.** A cascading source keyed on another
+  field is not fetched until that placeholder resolves. This is deliberate and
+  it is also what a typo produces — see
+  [Interpolation](../interpolation/overview.md#an-unresolved-placeholder-cancels-a-request).
+- **The URL is blocked** by [`fetcher.remotePatterns`](../setup.md#fetcherremotepatterns).
+  This one is logged; the others are silent. Relative URLs are internal and
+  always allowed.
+- **The field is disabled.** Nothing is fetched, and a disabled `select` whose
+  value is an object renders that object as its only option — so a saved
+  selection is still readable on a form that cannot be edited.
+
+Requests are keyed by the source itself, so two fields declaring the same one
+share a single request and its cache entry.
+
+## Failures
+
+A non-2xx response throws with the parsed body, and the error is logged rather
+than rendered: the field shows an empty list. A response that is not JSON fails
+the same way, since the body is always parsed as JSON.
+
+A URL containing the literal `null` or `undefined` in a path or query segment is
+rejected before the request goes out — the usual sign that a placeholder
+resolved to nothing.
+
+## Changing a source at run time
+
+A [`source` change event](../events/change.md#3-source-action-sourceevent)
+installs a new `DataSource` on another field, with `{value}` and the rest of the
+selected option interpolated into its `url` and `body`.
+
+Several events aimed at the same target **merge** rather than replace: query
+parameters from each URL are combined, `body` and `headers` are merged key by
+key, and for anything else the most recent event wins. Two fields can each
+contribute a parameter to one dependent source that way.
+
+Options that arrive from a source are data, not authored copy, so they are not
+resolved against the dictionary — see
+[Translating Options](select.md#translating-options).
+
+## Sharing one source between fields
+
+A source used in more than one place belongs in a
+[definition](../structure/definition.md), named once and referenced:
+
+```json
+{
+  "source": { "$ref": "#/definition/sources.countries" }
+}
+```
+
+A reference that does not resolve is left as written, and a `source` that is
+still a `$ref` is never fetched.

package/docs/fields/input.md

@@ -44,7 +44,7 @@ The `advanced` property dictates finer HTML details, interactive structures, and
 - **`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.
+- **`reverse`** _(boolean)_: `checkbox` only, and it exists to turn a default **off**. A checkbox renders its box first and its label after it; `reverse: false` swaps them, `true` changes nothing, and on any other field type the key is not read. See [Layout](../structure/layout.md#advancedreverse-checkbox-only).
 - **`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).

package/docs/fields/list.md

@@ -18,6 +18,9 @@ The `list` field type in Luna Form acts as an iterative array structure, enablin
 
 The `advanced` property customizes structural interaction rules and layout rendering for the collection container.
 
+- **`title`** _(string)_: Names one item of the collection. The header of the second row then reads `Contact 2` and its controls announce `Collapse Contact 2` and `Remove Contact 2`.
+  It falls back to the list's `label`, and then to its `name`, so a list called `contacts` with neither captions its rows `contacts 1`. A [`preview.label`](#collapsed-previews-preview-object) replaces the caption where it resolves; this stays the fallback for the rows where it does not.
+  Like `action`, it is copy the form declares, so it is translated through the dictionary — see [Localization](#localization).
 - **`action`** _(string)_: A custom label applied strictly to the generic "Add item" button rendering at the end of the collection (e.g. `"Add email address"`).
   A custom label has to be translated by the form; the built-in `Add item` default is already translated by the library — see [Localization](#localization).
 - **`length`** _({ min?: number, max?: number })_: Configures restrictions on how many items can be generated. Enforces boundary conditions where minimum instances ensure permanent default items and maximum instances automatically disable insertion toggles. The matching error messages are declared under the list's `validation.length` — see the [Validation reference](../validation/overview.md#list-length).
@@ -65,7 +68,7 @@ For example, if you want a field inside the list to update another field **in th
     {
       "name": "role",
       "type": "select",
-      "options": [
+      "source": [
         { "value": "admin", "label": "Admin" },
         { "value": "user", "label": "User" }
       ],
@@ -215,7 +218,7 @@ Left untranslated, the template fills in to the same English text it replaced.
     {
       "name": "status",
       "type": "select",
-      "options": [
+      "source": [
         { "value": "active", "label": "Currently Employed" },
         { "value": "past", "label": "Past Job" }
       ]

package/docs/fields/select.md

@@ -36,7 +36,7 @@ Each option consists of:
 
 ### 2. Remote Data Source
 
-You can fetch options from a remote API by providing a `DataSource` configuration.
+You can fetch options from a remote API by providing a `DataSource` configuration. Its full shape, and when a request is and is not made, are in [data-source.md](data-source.md).
 
 ```json
 "source": {
@@ -79,6 +79,52 @@ Inside `advanced.options`, you can map:
 
 ---
 
+### `advanced.entity`
+
+`advanced.options` decides what the user sees and what the field submits.
+`advanced.entity` decides how a value is matched **back** to the row it came
+from, and it defaults to `value`.
+
+That default is right for options shaped `{ label, value }` and wrong for
+everything else, which is why it belongs next to `options`: whenever
+`options.value` names a key other than `value`, `entity` has to name the same
+key.
+
+```json
+{
+  "name": "user_selection",
+  "type": "select",
+  "source": { "url": "/api/users" },
+  "advanced": {
+    "entity": "id",
+    "options": { "value": "id", "label": "name" }
+  },
+  "event": {
+    "change": [{ "action": "value", "value": { "contact_email": "{email}" } }]
+  }
+}
+```
+
+It does two things, both of them a lookup by that key:
+
+- **A change event gets the whole row.** The library finds the source row whose
+  `entity` key equals the current selection and hands that object to the
+  event, which is what makes `{email}` — a key that is neither the label nor
+  the value — resolvable. Without `entity` the lookup matches nothing, the
+  event falls back to `{ value }`, and every other placeholder is left literal.
+  See [Event payloads](../interpolation/overview.md#event-payloads).
+- **An object value is read through it.** A form whose value for this field is
+  the whole record rather than the id — `{ "id": 101, "name": "John" }` — shows
+  the right option, because `entity` says which key of that object is the
+  value. Without it the field looks for a `value` key, finds none, and mounts
+  empty.
+
+The comparison is made on the text of both sides, so a numeric `id` in the
+source matches the string the select reports.
+
+`entity` is not read for `chips`: an array selection answers to no single row,
+so a `chips` change carries the array itself.
+
 ## Translating Options
 
 When the options are declared inline as an array, `label` and `description` are resolved against the form dictionary, exactly like a field's own `label`. Missing keys fall back to the key itself.
@@ -139,6 +185,8 @@ Specialized selectors carry their own built-in labels and are not resolved again
 - **`multiple`** _(boolean, optional)_: (Available for `chips`) Allows selecting more than one option. Defaults to `true`.
 - **`preselected`** _(boolean, optional)_: For specialized selectors like `select/month`, determines if the current value (e.g., current month) should be selected by default.
 - **`horizontal`** _(boolean, optional)_: Renders the options or selector horizontally.
+- **`entity`** _(string, optional)_: The key that identifies an option row, defaulting to `value`. Set it whenever `options.value` names a different key — see [`advanced.entity`](#advancedentity).
+- **`options`** _({ label, value, description }, optional)_: Maps the keys of a remote row onto the option shape — see [Property Mapping Reference](#property-mapping-reference).
 
 ### A chips value is always an array
 

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.