react-luna-form 0.0.81 → 0.0.83

package/docs/fields/specialized-selectors.md

@@ -0,0 +1,175 @@
+# Specialized Selectors
+
+Specialized selectors in Luna Form come with pre-defined data sources, such as months, years, or timezones. These allow you to quickly implement common form fields without manually defining a `source` array.
+
+## Date & Time Selectors
+
+### 1. Month Selector (`select/month`)
+
+Renders a dropdown with the 12 months of the year.
+
+```json
+{
+  "name": "expiry_month",
+  "type": "select/month",
+  "label": "Expiration Month",
+  "required": true
+}
+```
+
+### 2. Year Selector (`select/year`)
+
+Renders a dropdown with a range of years.
+
+- **Default behavior**: Shows the current year plus the next 5 years.
+- **Customization**: Use `advanced.length.min` and `advanced.length.max` to define the start and end years relative to the current year.
+
+```json
+{
+  "name": "expiry_year",
+  "type": "select/year",
+  "label": "Expiration Year",
+  "advanced": {
+    "length": {
+      "min": 0,
+      "max": 10
+    }
+  }
+}
+```
+
+### 3. Day Selector (`select/day`)
+
+Renders a dropdown with days 1 through 31.
+
+```json
+{
+  "name": "birth_day",
+  "type": "select/day",
+  "label": "Day"
+}
+```
+
+### 4. Timezone Selector (`select/timezone`)
+
+Provides a comprehensive list of global timezones.
+
+```json
+{
+  "name": "user_timezone",
+  "type": "select/timezone",
+  "label": "Your Timezone",
+  "defaultValue": "America/New_York"
+}
+```
+
+---
+
+## Utility Selectors
+
+### 5. Active/Binary Selector (`select/active`)
+
+A simple binary toggle, typically rendered as "Yes" and "No".
+
+```json
+{
+  "name": "is_active",
+  "type": "select/active",
+  "label": "Account Active?",
+  "defaultValue": "true"
+}
+```
+
+---
+
+## specialized Chips
+
+These types render as buttons (tags) instead of dropdowns.
+
+### 6. Day Chips (`chips/day`)
+
+Renders chips for the 7 days of the week.
+
+```json
+{
+  "name": "available_days",
+  "type": "chips/day",
+  "label": "Select Days",
+  "advanced": {
+    "multiple": true
+  }
+}
+```
+
+### 7. Month Chips (`chips/month`)
+
+Renders chips for the 12 months of the year.
+
+```json
+{
+  "name": "subscription_months",
+  "type": "chips/month",
+  "label": "Subscription Months"
+}
+```
+
+---
+
+## Localization
+
+The option labels of these selectors are produced by the framework, not written in the schema, so most of them are resolved through the form's `lang` rather than against the `translations` dictionary the way an inline [array source](select.md#translating-options) is.
+
+- `select/month`, `select/day`, `chips/day` and `chips/month` take their names from the form's `lang`, resolved through `Intl`. Without `lang` they fall back to the runtime locale, and a malformed tag (`es_MX`, `español`) falls back too rather than failing.
+- `select/year` renders plain numbers.
+- `select/timezone` renders its region groups and zone names in English.
+- `select/active` is the exception: `Yes` and `No` are authored copy rather than locale data, so they **are** resolved against the dictionary, using their English text as the key — the same way the built-in `(Optional)` suffix is. The library ships the Spanish for both, so `lang: "es"` alone is enough; see [built-in translations](list.md#built-in-translations).
+
+```json
+{
+  "lang": "es",
+  "sections": [
+    {
+      "fields": [{ "name": "month", "type": "select/month" }]
+    }
+  ]
+}
+```
+
+The dropdown lists `enero` through `diciembre`, while the submitted value stays the month number. Setting `lang` also keeps the server and client renders on the same locale; without it each side resolves its own default, which can differ.
+
+`select/active` instead reads its two labels from the dictionary, and the library already ships the Spanish for them:
+
+```json
+{
+  "lang": "es",
+  "sections": [
+    {
+      "fields": [{ "name": "active", "type": "select/active" }]
+    }
+  ]
+}
+```
+
+The dropdown lists `Sí` and `No`, while the submitted value stays the boolean. A `lang` with no built-in dictionary renders them in English, and a form that wants different wording declares the keys itself:
+
+```json
+{
+  "lang": "es",
+  "translations": { "es": { "Yes": "Activo", "No": "Inactivo" } }
+}
+```
+
+To control the wording further — or to localize any of the locale-driven selectors — declare an explicit `source`. It overrides the built-in options and, being an array, its labels go through the dictionary:
+
+```json
+{
+  "name": "active",
+  "type": "select/active",
+  "source": [
+    { "value": "true", "label": "active_yes" },
+    { "value": "false", "label": "active_no" }
+  ]
+}
+```
+
+For `select/timezone` the override must keep the group shape (`{ "label": "...", "items": [...] }`) that the grouped selector expects.

package/docs/index.md

@@ -0,0 +1,53 @@
+# react-luna-form
+
+Reference for the JSON that drives a luna form. These files ship inside the
+published package, so what you are reading always describes the version you have
+installed.
+
+Forms are declared as data, not composed as components: a `sections` array of
+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`.
+
+## Where to look
+
+| You are                                                                      | Read                                                               |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| 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)                 |
+| Making a field required, or validating against another field                 | [validation/overview.md](validation/overview.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) |
+
+## Three things that surprise people
+
+Read the relevant page before writing the field, not after debugging it.
+
+- **A field type nothing implements renders nothing at all.** `config.inputs`
+  is an exact map, with no prefix resolution: a `type` that was never
+  registered resolves to `undefined` and the field is skipped, on the server
+  and on the client alike. No error, no placeholder — the field is simply
+  absent from the form.
+- **`defineConfig({ validation })` replaces the defaults, it does not merge.**
+  Passing `{ change: false }` also turns off `blur`, `submit` and
+  `showError` — the form loses its error summary and nothing says why. Pass
+  every key you still want.
+- **A `change` event also runs at mount.** A field that arrives with a value or
+  a `defaultValue` fires its `change` events once, so anything they reveal,
+  clear or fetch happens before the user touches the form. See
+  [events/change.md](events/change.md).
+
+## Entry points
+
+| Import                   | Use                                                                                         |
+| ------------------------ | ------------------------------------------------------------------------------------------- |
+| `react-luna-form`        | The `Form` component and client hooks                                                       |
+| `react-luna-form/config` | `defineConfig`, `defineInput`, `defineCustomInput` and the rest of the registration helpers |
+| `react-luna-form/schema` | Building and inspecting the Zod schema derived from `sections`                              |
+| `react-luna-form/server` | Server-safe helpers, usable under the `react-server` condition                              |

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.