react-luna-form 0.0.80 → 0.0.82

package/docs/fields/list.md

@@ -0,0 +1,230 @@
+# List Field (`list`)
+
+The `list` field type in Luna Form acts as an iterative array structure, enabling users to add, edit, and remove a repeating set of fields dynamically. It's particularly useful when capturing a collection of identical data objects—like a list of addresses, multiple users, or repeated configurations.
+
+---
+
+## Core Properties
+
+- **`name`** _(string, required)_: The unique identifier. The resulting form state binds to an array containing objects referencing the child elements.
+- **`type`** _(string, required)_: Evaluates the type definition exactly to `"list"`.
+- **`label`** _(string, optional)_: The human-readable label (typically rendered as a fieldset legend).
+- **`description`** _(string | object, optional)_: Help text or extra context shown globally just under the legend. Supports **Markdown** (specifically links).
+- **`fields`** _(Array<Field | Column | List>, required)_: The nested structure defining what underlying standard HTML inputs are repeated for each iteration in the array. A `list` among them is a list nested inside this one: each row gets its own, named by its path (`groups.0.checks`).
+
+---
+
+## Advanced Configuration (`advanced` object)
+
+The `advanced` property customizes structural interaction rules and layout rendering for the collection container.
+
+- **`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).
+  Both bounds apply to the rows a list opens with, not only to the ones added by hand: an initial `value` shorter than `min` leaves the remainder standing and empty, and one longer than `max` stops at `max`. A [`value` event](../events/change.md#targeting-a-list) assigning rows is clamped the same way.
+- **`collapsed`** _(boolean)_: When enabled, list items default to a visually collapsed representation upon mounting or adding.
+
+### Collapsed Previews (`preview` object)
+
+If list items render into structural wrappers (e.g., when they contain multiple fields and become automatically collapsible), the **`preview`** object handles mapping internal field values outward toward the unexpanded accordion headers directly.
+
+- **`label`** _(string | PreviewItem)_: Targets a primary field to replace the list element's fallback title string.
+- **`badge`** _(string | PreviewItem)_: Extracts a selected field mapping dynamically as an isolated badge indicator beside the label.
+- **`tags`** _(PreviewItem[])_: Defines an array pointing to additional fields inside the iteration mapping, injected strictly below the label row simulating tag clouds.
+
+**`PreviewItem` Definition:**
+Previews can map seamlessly pointing out the desired child `name` simply as strings format, or strictly defined mapping condition rules optionally:
+
+- **`field`** _(string)_: The child layout field name.
+- **`label`** _(string)_: Provides contextual prefix naming before mapping the preview value statically.
+- **`when`** _(string | string[] | Condition)_: Standard complex logical operators dictating runtime evaluation rules. When an **array** is provided, it performs an **OR match** against the field's current value.
+
+---
+
+## Filling a list from another field
+
+A `list` can be the target of a `value` change event. Aim one at the list's own name and give it an array of objects, and the list becomes exactly those rows — one object per row, each key matching a field name inside it.
+
+It assigns rather than adds: the rows you send are the rows that remain, `advanced.length` still bounds the result, and rows that survive are matched by position so they are not remounted.
+
+A row's key can name a nested `list` instead of a field, in which case its value is that list's rows and the whole tree is assigned in one event. The full rules and worked examples are in [Targeting a list](../events/change.md#targeting-a-list) and [Rows that hold rows](../events/change.md#rows-that-hold-rows).
+
+---
+
+## Interaction Targeting in Events
+
+When interacting internally inside specific items belonging directly to iterators (`list`), Target Actions (like configuring cross dependencies over Change events) inherit relative pathing resolution logically overriding direct top-level values leveraging `"list_name/field_name"` resolution strings.
+
+For example, if you want a field inside the list to update another field **in the same iteration/row**, you must prefix the target field's name with the list's name:
+
+```json
+{
+  "name": "users",
+  "type": "list",
+  "fields": [
+    {
+      "name": "role",
+      "type": "select",
+      "options": [
+        { "value": "admin", "label": "Admin" },
+        { "value": "user", "label": "User" }
+      ],
+      "event": {
+        "change": [
+          {
+            "action": "value",
+            "value": {
+              "users/access_level": "full_access"
+            },
+            "when": "admin"
+          }
+        ]
+      }
+    },
+    {
+      "name": "access_level",
+      "type": "input/text"
+    }
+  ]
+}
+```
+
+See [Change Events](../events/change.md#target-resolution-in-lists) structure definitions closely outlining array value mapping techniques cleanly.
+
+---
+
+## Localization
+
+Every piece of copy a list renders goes through the `translations` dictionary, keyed by its English source text. The keys split into two groups by who owns the text.
+
+**Declared by the form**, so only the form can translate them:
+
+- `label` and `description`, rendered as the fieldset legend and its help text.
+- `advanced.action`, the custom add-button label.
+- `advanced.title`, which supplies the caption of each item (`Contact 1`, `Contact 2`, …) and feeds the accessible names of its controls.
+
+**Owned by the library**, so `lang` alone is enough — see [built-in translations](#built-in-translations):
+
+- `Add item`, the add-button label when no `action` is declared.
+- `Expand {label} {index}`, `Collapse {label} {index}` and `Remove {label} item {index}`, the accessible names of the item controls.
+
+```json
+{
+  "lang": "es",
+  "translations": {
+    "es": {
+      "contact_label": "Contacto"
+    }
+  },
+  "sections": [
+    {
+      "fields": [
+        {
+          "label": "contact_label",
+          "name": "contacts",
+          "type": "list",
+          "fields": [
+            { "name": "name", "label": "Nombre", "type": "input/text" },
+            { "name": "email", "label": "Correo", "type": "input/email" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+The list renders as `Contacto`, its add button as `Añadir elemento`, and its controls announce `Contraer Contacto 1` and `Eliminar Contacto 1` — the form only had to name its own label.
+
+### Built-in translations
+
+The library ships translations for the copy it renders on its own behalf, because a form cannot name those strings in its schema. Today that covers **Spanish**; any other `lang` falls back to the English source text.
+
+Beyond the list keys above, the built-in set also covers the `(Optional)` label suffix, the `Yes`/`No` options of [`select/active`](specialized-selectors.md#5-activebinary-selector-selectactive), and the summary the form shows above itself when a submit fails: `There were validation errors submitting the form.`, `Please correct the errors and try again.`, and `An unexpected error occurred submitting the form.` (plus `Unknown error` for a thrown action carrying no message).
+
+The built-ins are layered _under_ the form's own block, so declaring a key still overrides them:
+
+```json
+{
+  "lang": "es",
+  "translations": { "es": { "Add item": "Agregar contacto" } }
+}
+```
+
+Regional tags resolve to their base language, so `es-MX` and `es-419` both get the Spanish defaults. A form's own entries keep matching on the exact tag, unchanged.
+
+### Accessible name templates
+
+The accessible names are single keys carrying `{label}` and `{index}` placeholders rather than separate words, so a translation can reorder the parts — or drop one. The Spanish default for `Remove {label} item {index}` is `Eliminar {label} {index}`, without the English `item` filler:
+
+```json
+{
+  "translations": {
+    "fr": { "Remove {label} item {index}": "Supprimer {label} {index}" }
+  }
+}
+```
+
+Left untranslated, the template fills in to the same English text it replaced.
+
+---
+
+## Complete Example Reference
+
+```json
+{
+  "label": "Working Experiences",
+  "name": "experiences",
+  "type": "list",
+  "description": "Please detail your previous relevant jobs.",
+  "advanced": {
+    "action": "Add Experience Record",
+    "collapsed": true,
+    "length": {
+      "min": 1,
+      "max": 3
+    },
+    "preview": {
+      "label": "company",
+      "badge": "status",
+      "tags": [
+        "title",
+        {
+          "field": "internal_review",
+          "label": "Checked",
+          "when": {
+            "operator": "eq",
+            "value": true
+          }
+        }
+      ]
+    }
+  },
+  "fields": [
+    {
+      "name": "company",
+      "label": "Company Name",
+      "type": "input/text",
+      "required": true
+    },
+    {
+      "name": "title",
+      "label": "Job Title",
+      "type": "input/text"
+    },
+    {
+      "name": "status",
+      "type": "select",
+      "options": [
+        { "value": "active", "label": "Currently Employed" },
+        { "value": "past", "label": "Past Job" }
+      ]
+    },
+    {
+      "name": "internal_review",
+      "type": "checkbox",
+      "hidden": true
+    }
+  ]
+}
+```

package/docs/fields/select.md

@@ -0,0 +1,194 @@
+# Select Fields (`select`, `radio`, `chips`)
+
+Luna Form provides several field types for selecting one or more values from a set of options. These fields share a common way of managing their data source.
+
+## Supported Types
+
+- `select`: A standard dropdown menu (`<select>`).
+- `radio`: A group of radio buttons where only one can be selected.
+- `chips`: Interactive buttons (tags) for selecting values. Supports single or multiple selection.
+
+> **Tip:** Luna Form also includes **[Specialized Selectors](specialized-selectors.md)** with built-in sources for months, years, days, timezones, and more.
+
+---
+
+## The `source` Property
+
+Unlike input fields, selectors require a list of options. This is managed via the `source` property.
+
+### 1. Static Options
+
+You can provide an array of objects directly in the schema.
+
+```json
+"source": [
+  { "label": "Apple", "value": "apple" },
+  { "label": "Banana", "value": "banana" },
+  { "label": "Orange", "value": "orange", "description": "High in Vitamin C" }
+]
+```
+
+Each option consists of:
+
+- **`label`** _(string)_: The text displayed to the user.
+- **`value`** _(string | number | boolean)_: The technical value submitted in the form.
+- **`description`** _(string, optional)_: Additional help text for the specific option.
+
+### 2. Remote Data Source
+
+You can fetch options from a remote API by providing a `DataSource` configuration.
+
+```json
+"source": {
+  "url": "/api/v1/categories",
+  "method": "GET"
+}
+```
+
+If your API returns objects with different keys, you can map them using the `advanced.options` property. This is useful when your data doesn't match the default `{ label, value }` structure.
+
+### Example: Mapping a User Object
+
+Suppose your source returns an array of user objects with properties like `id`, `name`, `lastname`, and `age`:
+`[{ "id": 101, "name": "John", "lastname": "Doe", "age": 25 }]`
+
+You can use the `options` mapping to decide which properties are used for the selector's value, label, and (optional) description:
+
+```json
+{
+  "name": "user_selection",
+  "type": "select",
+  "source": { "url": "/api/users" },
+  "advanced": {
+    "options": {
+      "value": "id",
+      "label": "name",
+      "description": "age"
+    }
+  }
+}
+```
+
+### Property Mapping Reference
+
+Inside `advanced.options`, you can map:
+
+- **`label`**: The key to use for the display text (e.g., `"name"`).
+- **`value`**: The key to use for the technical value (e.g., `"id"`).
+- **`description`** _(optional)_: The key to use for additional help text (e.g., `"age"`).
+
+---
+
+## 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.
+
+```json
+{
+  "lang": "es",
+  "translations": {
+    "es": {
+      "fruit_apple": "Manzana",
+      "fruit_banana": "Plátano"
+    }
+  },
+  "sections": [
+    {
+      "fields": [
+        {
+          "name": "fruit",
+          "type": "select",
+          "source": [
+            { "value": "apple", "label": "fruit_apple" },
+            { "value": "banana", "label": "fruit_banana" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+This applies to `select`, `radio` and `chips`, works with `advanced.options` mapping, and reaches the collapsed preview of a list.
+
+Three rules bound the behavior:
+
+- **`value` is never translated.** It is the technical value submitted with the form, so the payload stays identical in every language.
+- **Only array sources are translated.** A remote `DataSource` returns data, not authored copy, so its labels are rendered as fetched. The same applies when a `source` change event replaces the array with a remote source at runtime.
+- **Only object options are translated.** In a bare string array (`["apple", "banana"]`) the string is both the label and the value, so translating it would change what the form submits.
+
+Specialized selectors carry their own built-in labels and are not resolved against the dictionary. See [Specialized Selectors](specialized-selectors.md#localization).
+
+---
+
+---
+
+## Core Properties
+
+- **`name`** _(string, required)_: The unique identifier.
+- **`type`** _(string, required)_: One of the supported select types.
+- **`label`** _(string, optional)_: Human-readable label.
+- **`defaultValue`** _(any, optional)_: The initial selected value. Matches the `value` of one of the options.
+  For `chips`, it must be an **array** — see below.
+- **`required`** _(boolean, optional)_: If `true`, a value must be selected.
+
+---
+
+## Advanced Configuration (`advanced` object)
+
+- **`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.
+
+### A chips value is always an array
+
+Whatever `multiple` says, a `chips` field holds an array. The value is coerced
+on the way in: anything that is not an array becomes `[]`.
+
+The consequence is a scalar `defaultValue`. This looks reasonable and does
+nothing:
+
+```json
+{ "name": "method", "type": "chips", "defaultValue": "GET" }
+```
+
+`"GET"` is not an array, so the field mounts with nothing selected. Nothing
+throws and nothing warns. Write it as an array, single selection or not:
+
+```json
+{ "name": "method", "type": "chips", "defaultValue": ["GET"] }
+```
+
+Setting `advanced.multiple` to `false` limits what a user can pick. It does not
+change the shape of the value, so it does not make a scalar default work.
+
+---
+
+## Validation
+
+- **`required`** _(string)_: Custom error message when no value is selected.
+
+---
+
+## Complete Example
+
+```json
+{
+  "name": "notification_preference",
+  "type": "radio",
+  "label": "How should we contact you?",
+  "defaultValue": "email",
+  "source": [
+    { "label": "Email", "value": "email" },
+    { "label": "SMS", "value": "sms" },
+    {
+      "label": "Push Notification",
+      "value": "push",
+      "description": "Requires mobile app"
+    }
+  ],
+  "validation": {
+    "required": "Please select a notification method."
+  }
+}
+```

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                              |