react-luna-form 0.0.80 → 0.0.82

package/docs/interpolation/format-filters.md

@@ -0,0 +1,128 @@
+# Format Filters
+
+Format filters transform interpolated values into locale-aware strings using a pipe syntax inspired by Vue and Angular.
+
+## Where filters can be used
+
+Filters work in any string passed through Luna Form's interpolation engine, including:
+
+- Field `description` (static or applied via a `state` change action)
+- Field `label`
+- `value` event payloads
+- `source.url` and `source.body`
+
+## Syntax
+
+```
+{key | filter:arg1:arg2}
+```
+
+- `key` is the value to look up in the interpolation context. Supports dot notation (`{user.amount}`).
+- After `|` comes one or more filters separated by additional `|` pipes.
+- Each filter accepts optional positional arguments separated by `:`.
+
+Multiple filters can be chained; the output of the previous filter becomes the input of the next.
+
+## Locale resolution
+
+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).
+
+```ts
+const config = {
+  env: {
+    locale: 'es-ES',
+  },
+  // ...
+}
+```
+
+## Fallback rules
+
+- **Unknown filter name**: the entire placeholder is preserved literally (`{value | foo}` stays as `{value | foo}`).
+- **Invalid input** (NaN for numeric filters, unparseable date for date filters): the filter returns `String(value)` and the surrounding template still renders.
+- **Missing key**: the placeholder is preserved literally.
+
+## Reference
+
+### `currency`
+
+Formats a number as currency.
+
+- **Syntax**: `{value | currency:CODE}`
+- **Args**:
+  - `CODE` (string, default `"USD"`) — ISO 4217 currency code.
+- **Backend**: `Intl.NumberFormat(locale, { style: 'currency', currency: CODE })`.
+- **Examples**:
+  - `1234.56` with `currency:USD` and `locale: en-US` → `$1,234.56`.
+  - `1234.56` with `currency:EUR` and `locale: es-ES` → `1234,56 €`.
+
+### `percent`
+
+Formats a fractional number as a percentage.
+
+- **Syntax**: `{value | percent}`
+- **Backend**: `Intl.NumberFormat(locale, { style: 'percent' })`.
+- **Examples**:
+  - `0.25` with `locale: en-US` → `25%`.
+- **Note**: input is interpreted as a fraction (`1` is `100%`).
+
+### `number`
+
+Formats a number with locale-aware thousands separators.
+
+- **Syntax**: `{value | number}`
+- **Backend**: `Intl.NumberFormat(locale)`.
+- **Examples**:
+  - `1234567` with `locale: en-US` → `1,234,567`.
+  - `1234567` with `locale: es-ES` → `1.234.567`.
+
+### `date`
+
+Formats a date or ISO string with a named style.
+
+- **Syntax**: `{value | date:STYLE}`
+- **Args**:
+  - `STYLE` (string, default `"short"`) — one of `short`, `medium`, `long`, `full`, `relative`. Any other value is passed directly to `date-fns`'s `format` as a pattern.
+- **Backend**: `date-fns` (`format`, `formatDistanceToNow` for `relative`).
+- **Accepts**: `Date`, ISO string, or numeric timestamp (ms).
+- **Examples**:
+  - `"2026-05-10"` with `date:long` and `locale: en-US` → `May 10, 2026`.
+  - A future date with `date:relative` and `locale: en-US` → `in 7 days`.
+
+### `duration`
+
+Produces a localized human-readable duration in years, months, days, hours, minutes, and seconds.
+
+- **Syntax**: `{value | duration}` or `{value | duration:UNIT}`
+- **Args**:
+  - `UNIT` (string, default `"ms"`) — input unit when the value is a number. One of `ms`, `s`, `min`, `h`, `d`.
+- **Backend**: `date-fns` (`formatDistanceToNow`, `formatDuration`, `intervalToDuration`).
+- **Behavior depends on input type**:
+  - **Number** (or numeric string): treated as a duration in `UNIT` units, converted to milliseconds, then formatted as a breakdown (`"1 day 2 hours"`).
+  - **`Date` or non-numeric ISO string**: distance between the date and "now" with a suffix (`"3 months ago"`, `"in 2 days"`).
+- **Multipliers to milliseconds**:
+
+  | Unit  | Multiplier |
+  | ----- | ---------- |
+  | `ms`  | 1          |
+  | `s`   | 1,000      |
+  | `min` | 60,000     |
+  | `h`   | 3,600,000  |
+  | `d`   | 86,400,000 |
+
+- **Examples**:
+  - `{age | duration:s}` with `3600` → `1 hour`.
+  - `{wait | duration:min}` with `90` → `1 hour 30 minutes`.
+  - `{ms | duration}` with `93_600_000` → `1 day 2 hours`.
+  - `{createdAt | duration}` with an ISO date in the past → `3 months ago`.
+
+## Supported locales
+
+Out of the box, the following locales map to a `date-fns/locale` bundle for `date` (relative and pattern styles) and `duration`:
+
+- `en`, `en-US` → `enUS`
+- `es`, `es-ES`, `es-MX` → `es`
+
+Other locale codes match by language prefix (e.g. `es-AR` → `es`). If no match is found, `enUS` is used as fallback.
+
+`Intl`-backed filters (`currency`, `percent`, `number`) accept any well-formed BCP 47 locale tag supported by the runtime.

package/docs/setup.md

@@ -0,0 +1,165 @@
+# Setup
+
+How a form is configured and rendered. The pages under `fields/`,
+`validation/` and `events/` describe the JSON; this one describes the code
+around it.
+
+## Entry points
+
+| Import                   | Contains                                                                                  |
+| ------------------------ | ----------------------------------------------------------------------------------------- |
+| `react-luna-form`        | `Form` (client), `withDeclaredFields`, and the `Sections`, `Source` and `ZodSchema` types |
+| `react-luna-form/server` | `Form` (server) and `Fallback`                                                            |
+| `react-luna-form/config` | `defineConfig` and the `define*` registration helpers                                     |
+| `react-luna-form/schema` | `buildFormSchema` and `collectIssues`                                                     |
+
+## Configuring
+
+`defineConfig` is called once, usually in a `luna.config.ts` at the root of the
+application, and its result is passed to every `Form`.
+
+```ts
+import { defineConfig, defineInput, defineSelect } from 'react-luna-form/config'
+
+export default defineConfig({
+  inputs: [defineInput(Input), defineSelect(Select)],
+})
+```
+
+### `inputs` (required)
+
+The components that render each field type. Registration is by exact type
+string; a type nothing registers renders nothing at all. The helpers cover the
+types this library ships:
+
+| Helper              | Registers                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `defineInput`       | `input`, `input/date`, `input/email`, `input/number`, `input/password`, `input/tel`, `input/text`, `input/time` |
+| `defineSelect`      | `select`, `select/active`, `select/day`, `select/month`, `select/timezone`, `select/year`                       |
+| `defineChips`       | `chips`, `chips/day`, `chips/month`                                                                             |
+| `defineRadio`       | `radio`                                                                                                         |
+| `defineCheckbox`    | `checkbox`                                                                                                      |
+| `defineTextArea`    | `textarea`                                                                                                      |
+| `defineCustomInput` | whatever names you give it — see [fields/custom-inputs.md](fields/custom-inputs.md)                             |
+
+### `validation`
+
+When to validate and whether to summarise errors. All four default to `true`.
+
+```ts
+validation: { blur: true, change: true, showError: true, submit: true }
+```
+
+**This object replaces the defaults, it does not merge into them.** Passing
+`{ change: false }` also turns off `blur`, `submit` and `showError`, so the form
+stops validating on blur and loses its error summary with no indication why.
+Pass every key you still want.
+
+### `fetcher.remotePatterns`
+
+Which hosts a field's remote `source` may call. The rules:
+
+| Value   | Effect                               |
+| ------- | ------------------------------------ |
+| omitted | **every host is allowed**            |
+| `[]`    | every external URL is blocked        |
+| a list  | an external URL must match one entry |
+
+A pattern may constrain `protocol`, `hostname` and `port`; every part is
+optional and an omitted part matches anything. Relative URLs count as internal
+and are always allowed.
+
+```ts
+fetcher: {
+  remotePatterns: [{ protocol: 'https', hostname: 'api.example.com' }]
+}
+```
+
+A blocked URL is not an error. The library logs
+`URL blocked by remotePatterns: <url>` and the field renders with no options at
+all, which on screen looks like an empty select rather than a rejected request.
+Check the console when a remote source comes back empty.
+
+### `style`, `alert`, `env`
+
+- `style` takes `compact`, `horizontal` and `showOptionalLabel`.
+- `alert` is the component that renders the error summary, when `showError`
+  is on.
+- `env` is a flat record of values available to interpolation, in labels and in
+  descriptions. Its `locale` key is also what those two read to format values.
+
+## Rendering
+
+### `Form` from `react-luna-form`
+
+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                                         |
+
+### `Form` from `react-luna-form/server`
+
+The same descriptors rendered without client state. It accepts the same props
+minus the interactive ones: there is no `action`, `onSuccess` or
+`onValueChange`. Use it for a form that only needs to be displayed.
+
+### `Fallback`
+
+A `Suspense` boundary whose fallback is the form itself in `readOnly` mode:
+
+```tsx
+<Fallback config={config} sections={sections}>
+  <SomethingAsync />
+</Fallback>
+```
+
+The placeholder is the real layout rather than a generic skeleton, so nothing
+shifts when the content arrives.
+
+## `withDeclaredFields`
+
+A form treats a name missing from its `value` object as a field the caller did
+not mention, and leaves that input showing whatever it was showing. That is
+correct while values are only ever being added, and wrong the moment one is
+lost: reverting to an earlier state does not empty a key, it removes it, and the
+input goes on displaying text that exists nowhere else.
+
+```tsx
+import { withDeclaredFields } from 'react-luna-form'
+
+;<Form
+  sections={sections}
+  config={config}
+  value={withDeclaredFields(sections, value)}
+/>
+```
+
+Naming the field is the difference between saying nothing about it and saying it
+holds nothing, and only the second empties the input. Wrapping the value is the
+opt-in: pass the result and the object becomes the form's state.
+
+Absence is resolved with the same lookup the form uses, so a name that is a path
+(`basicAuth.username` against a nested object) is handled correctly rather than
+shadowed by a flat key.
+
+## `react-luna-form/schema`
+
+`buildFormSchema(sections)` derives the Zod schema from the same descriptors
+that render the form, which is what keeps the rendered fields and the validated
+shape from drifting apart. `collectIssues(error)` flattens a Zod error into
+`{ path, message }` entries.
+
+Use them to validate on the server against the same rules the form applies in
+the browser.

package/docs/validation/overview.md

@@ -0,0 +1,318 @@
+# Validation
+
+Luna Form derives a [Zod](https://zod.dev) schema directly from the form JSON, so the **form definition is the single source of truth for validation**. Each field carries a `validation` object that maps a constraint to its error message; the builder turns those declarations into a runnable schema.
+
+The same schema powers two paths:
+
+- **In the browser**, the rendered `<Form>` validates on blur/submit.
+- **On the server (or any headless caller)**, `react-luna-form/schema` exposes `buildFormSchema(sections)` so you can run the _exact same_ validation without React — see [Headless validation](#headless-validation).
+
+This page documents every key of the `validation` object plus the shared operator vocabulary. Per-field basics also appear in each field's own page (e.g. [Input](../fields/input.md), [Select](../fields/select.md), [List](../fields/list.md)).
+
+---
+
+## The `validation` object
+
+`validation` lives on a field and maps a constraint name to a message (or a rule declaration):
+
+- **`required`** _(string)_: Message shown when a field marked `required: true` is empty.
+- **`email`** _(string)_: Message for an invalid email format (`input/email`).
+- **`length`** _({ min?: string, max?: string })_: Messages when the value's length breaches `advanced.length`.
+- **`custom`** _(CustomValidation | CustomValidation[])_: Cross-field comparison. See [Custom (cross-field)](#custom-cross-field).
+- **`requiredWhen`** _(WhenRule | WhenRule[])_: Conditionally required. See [requiredWhen](#requiredwhen).
+- **`pattern`** _(PatternRule)_: Regex/format check. See [pattern](#pattern).
+- **`rules`** _(AssertRule[])_: General gated assertions. See [rules](#rules).
+
+> Emptiness is normalized for validation: an empty string, a whitespace-only string, `null`/`undefined`, and an empty array all count as "no value". So `pattern` and format rules never fire on an empty field — that is `required`/`requiredWhen`'s job.
+
+---
+
+## `requiredWhen`
+
+Makes a field required **only when a condition over sibling data holds**. This is the declarative replacement for wiring "required" to visibility by hand.
+
+A `WhenRule` is:
+
+- **`field`** _(string, required)_: The sibling field whose value is tested.
+- **`operator`** _(Operator, optional)_: How to compare. Defaults to `eq`. See [Operators](#operators).
+- **`value`** _(string | number | boolean | Array, optional)_: The value to compare against (ignored by the unary operators `exists` / `empty` / `truthy`).
+- **`message`** _(string, optional)_: The error message. Falls back to `validation.required` when omitted.
+
+Provide a single rule or an array. **An array is OR** — the field is required if _any_ rule's condition holds.
+
+```json
+{
+  "name": "token",
+  "type": "input/text",
+  "validation": {
+    "requiredWhen": {
+      "field": "authType",
+      "operator": "eq",
+      "value": "bearer",
+      "message": "Provide the access token"
+    }
+  }
+}
+```
+
+### Item scope inside lists
+
+When a `requiredWhen` field lives inside a [`list`](../fields/list.md), its `field` reference resolves **within the same item**, not the form root. This lets each row validate against its own siblings:
+
+```json
+{
+  "name": "rules",
+  "type": "list",
+  "fields": [
+    { "name": "operator", "type": "select" },
+    {
+      "name": "value",
+      "type": "input/text",
+      "validation": {
+        "requiredWhen": {
+          "field": "operator",
+          "operator": "nin",
+          "value": ["truthy", "exists"],
+          "message": "Enter the value to compare against"
+        }
+      }
+    }
+  ]
+}
+```
+
+Here `value` is required unless this row's `operator` is `truthy` or `exists`. Item-scoped `requiredWhen` is resolved by the [headless builder](#headless-validation).
+
+---
+
+## `pattern`
+
+Validates a string value against a regular expression.
+
+- **`regex`** _(string, required)_: The pattern source (compiled with `new RegExp`).
+- **`flags`** _(string, optional)_: Regex flags, e.g. `"i"`.
+- **`message`** _(string, optional)_: The error message.
+- **`allowInterpolation`** _(boolean, optional)_: When `true`, the check is **skipped** if the value is dynamic and only resolved at run time — either an interpolation template (contains `{...}`) or a reference beginning with `@` (e.g. `@Trigger.url`), the convention applications built on this library use for a value resolved elsewhere. Use this for fields that accept dynamic values, e.g. a URL like `{step.url}` or `@step.url`.
+
+```json
+{
+  "name": "url",
+  "type": "input/text",
+  "validation": {
+    "pattern": {
+      "regex": "^https?://",
+      "allowInterpolation": true,
+      "message": "The web address must start with http:// or https://"
+    }
+  }
+}
+```
+
+`pattern` never fires on an empty value — pair it with `required`/`requiredWhen` when the field is mandatory.
+
+---
+
+## `rules`
+
+An escape hatch that keeps complex validation **in JSON**: an array of gated assertions evaluated in order.
+
+Each `AssertRule` is:
+
+- **`assert`** _(string, required)_: What to check — one of `required`, `minItems`, `maxItems`, `min`, `max`, `oneOf`, `pattern`.
+- **`value`** _(depends on `assert`)_: The bound the assertion checks against (a number, an array for `oneOf`, or a `PatternRule` for `pattern`).
+- **`message`** _(string, required)_: The error shown when the assertion fails.
+- **`when`** _(WhenClause, optional)_: Only run the assertion when this condition holds. Omit to always run it.
+
+### Assertions
+
+| `assert`   | Passes when                                         | `value`       |
+| ---------- | --------------------------------------------------- | ------------- |
+| `required` | The field has a value                               | —             |
+| `minItems` | Array length ≥ value                                | number        |
+| `maxItems` | Array length ≤ value                                | number        |
+| `min`      | Size ≥ value (number value, or string/array length) | number        |
+| `max`      | Size ≤ value                                        | number        |
+| `oneOf`    | Value is one of the listed values                   | array         |
+| `pattern`  | Value matches the pattern                           | `PatternRule` |
+
+### `when` clause
+
+A `when` gate can be a single rule, an array, or an all/any object:
+
+- A single **`WhenRule`** — runs when that condition holds.
+- An **array of `WhenRule`** — **AND**: every condition must hold.
+- **`{ all?: WhenRule[]; any?: WhenRule[] }`** — `all` requires every rule, `any` requires at least one; both must be satisfied when present.
+
+```json
+{
+  "name": "port",
+  "type": "input/number",
+  "validation": {
+    "rules": [
+      {
+        "when": { "field": "kind", "operator": "eq", "value": "custom" },
+        "assert": "required",
+        "message": "Port is required for custom connections"
+      },
+      {
+        "assert": "oneOf",
+        "value": ["eq", "neq", "gt"],
+        "message": "Choose a valid operator"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## `custom` (cross-field)
+
+Compares this field's value against **another field's value** using an operator. Provide one rule or an array (all are checked).
+
+- **`field`** _(string)_: The other field to compare against.
+- **`operator`** _(Operator, optional)_: Defaults to `eq`.
+- **`message`** _(string)_: The error shown when the comparison fails.
+
+```json
+{
+  "name": "confirmPassword",
+  "type": "input/text",
+  "required": true,
+  "validation": {
+    "custom": {
+      "field": "password",
+      "operator": "eq",
+      "message": "Passwords must match"
+    }
+  }
+}
+```
+
+---
+
+## Operators
+
+Operators are shared across `custom`, `requiredWhen`, `rules` gates, and [change-event conditions](../events/change.md). Each compares a `current` value against a `value`:
+
+| Operator     | True when                                      | Notes                       |
+| ------------ | ---------------------------------------------- | --------------------------- |
+| `eq`         | `current === value`                            | default                     |
+| `neq`        | `current !== value`                            |                             |
+| `in`         | `value` (array) contains `current`             |                             |
+| `nin`        | `value` (array) does **not** contain `current` |                             |
+| `gt` / `gte` | `current > value` / `>=`                       | numeric                     |
+| `lt` / `lte` | `current < value` / `<=`                       | numeric                     |
+| `contains`   | `current` (string/array) contains `value`      |                             |
+| `exists`     | `current` has a value                          | **unary** — `value` ignored |
+| `empty`      | `current` has no value (inverse of `exists`)   | **unary** — `value` ignored |
+| `truthy`     | `current` is truthy                            | **unary** — `value` ignored |
+
+`contains`, `exists`, `empty`, and `truthy` are the newest additions; the rest have always been available.
+
+---
+
+## List length
+
+A [`list`](../fields/list.md) can require a minimum/maximum number of items. The bounds live on `advanced.length`, and the messages on `validation.length`:
+
+```json
+{
+  "name": "rules",
+  "type": "list",
+  "advanced": { "length": { "min": 1, "max": 5 } },
+  "validation": {
+    "length": {
+      "min": "Add at least one condition",
+      "max": "You can add up to five conditions"
+    }
+  },
+  "fields": [{ "name": "label", "type": "input/text" }]
+}
+```
+
+A missing list key is treated as an empty list, so `length.min` still fails on an absent value rather than silently passing. List length is enforced by the [headless builder](#headless-validation).
+
+---
+
+## Headless validation
+
+The server-safe entry `react-luna-form/schema` exposes the builder with **no React dependency**, so a backend can validate a stored configuration with the same rules the form uses:
+
+```ts
+import { buildFormSchema, collectIssues } from 'react-luna-form/schema'
+
+const schema = buildFormSchema(sections) // sections: the form JSON
+const result = schema.safeParse(config)
+
+if (!result.success) {
+  const issues = collectIssues(result.error)
+  // [{ path: 'rules.0.value', message: 'Enter the value to compare against' }]
+}
+```
+
+- **`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.
+- **`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
+
+| Rule                                          | Rendered `<Form>` submit | `buildFormSchema` (headless) |
+| --------------------------------------------- | ------------------------ | ---------------------------- |
+| `required`, `email`, `length` (field)         | ✅                       | ✅                           |
+| `custom`                                      | ✅                       | ✅                           |
+| `requiredWhen` (top-level)                    | ✅                       | ✅                           |
+| `pattern`                                     | ✅                       | ✅                           |
+| `rules` (top-level)                           | ✅                       | ✅                           |
+| `requiredWhen` **inside a list** (item scope) | —                        | ✅                           |
+| List `length`                                 | —                        | ✅                           |
+
+The headless builder is the superset: item-scoped conditions and list length require the nested tree it produces.
+
+### Nested (dotted) field names
+
+A field whose `name` contains a dot — e.g. `basicAuth.username` — is grouped into a **nested object** by `buildFormSchema`, matching the nested config the runtime persists (the `<Form>` submits flat keys and then un-flattens them). So `{ "name": "basicAuth.username" }` validates against `{ basicAuth: { username } }`, and its issue path is `basicAuth.username`. The nested group is optional as a whole: a config may omit it entirely (e.g. no `basicAuth` when auth is off) and rely on `requiredWhen` for the conditional requirement.
+
+### Hidden fields
+
+`buildFormSchema` treats a `hidden: true` field as **not structurally required**, even if it declares `required: true`. A hidden field is only shown once an event reveals it, so its requirement is conditional by nature — express it with [`requiredWhen`](#requiredwhen) (typically keyed on the same condition that reveals it). This keeps the headless schema from over-requiring fields the rendered form never mounts. `pattern`/format rules on a hidden field still fire when it holds a value.
+
+---
+
+## Complete example
+
+```json
+{
+  "sections": [
+    {
+      "fields": [
+        { "name": "authType", "type": "select" },
+        {
+          "name": "token",
+          "type": "input/text",
+          "validation": {
+            "requiredWhen": {
+              "field": "authType",
+              "operator": "eq",
+              "value": "bearer",
+              "message": "Provide the access token"
+            }
+          }
+        },
+        {
+          "name": "url",
+          "type": "input/text",
+          "required": true,
+          "validation": {
+            "required": "The web address is required",
+            "pattern": {
+              "regex": "^https?://",
+              "allowInterpolation": true,
+              "message": "Use a valid http(s) address"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-luna-form",
-  "version": "0.0.80",
+  "version": "0.0.82",
   "description": "A React library for building forms based on JSON",
   "main": "./dist/client/cjs/index.js",
   "module": "./dist/client/esm/index.js",
@@ -15,7 +15,8 @@
     "validation"
   ],
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "peerDependencies": {
     "date-fns": "^4.0.0",
@@ -34,7 +35,7 @@
     "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.80"
+    "@luna-form/core": "0.0.82"
   },
   "license": "Apache-2.0",
   "repository": {