react-luna-form 0.0.81 → 0.0.83

package/docs/fields/input.md

@@ -0,0 +1,175 @@
+# Input Fields (`input/*`, `textarea`, `checkbox`)
+
+The `input/*` field types in Luna Form map to standard HTML `<input>` elements. These fields are used for capturing text, numbers, dates, times, and other generic data values from the user.
+
+## Supported Types
+
+- `input`: Same as `input/text`. The rendered `type` is taken from the part after the last `/`, and a bare `input` falls back to `text`.
+- `input/text`: Standard text input (`<input type="text">`).
+- `input/email`: Email address input with built-in format validation (`<input type="email">`).
+- `input/password`: Password input with text masked (`<input type="password">`).
+- `input/number`: Numeric input (`<input type="number">`).
+- `input/tel`: Telephone number input (`<input type="tel">`).
+- `input/date`: Date picker component.
+- `input/time`: Time picker component.
+
+---
+
+## Core Properties
+
+Luna Form's input fields inherit the standard logical properties available to all fields:
+
+- **`name`** _(string, required)_: The unique identifier for the field in the form output.
+- **`type`** _(string, required)_: Evaluates the type of input to render (e.g., `"input/text"`, `"input/password"`).
+- **`label`** _(string, optional)_: The human-readable label shown to the user.
+- **`defaultValue`** _(any, optional)_: The initial value of the field when the form is mounted and no external value is provided.
+- **`description`** _(string | object, optional)_: Help text or extra context for the form field. Supports **Markdown** (specifically links).
+  - Can be a direct string.
+  - Or an object payload: `{ title: string, message: string, collapsed?: boolean }`.
+- **`placeholder`** _(string, optional)_: The temporary placeholder text shown when the input is empty.
+- **`required`** _(boolean, optional)_: If `true`, standard browser/HTML5 validation makes the field mandatory.
+- **`disabled`** _(boolean, optional)_: If `true`, the field is non-interactive and blocked from events.
+- **`readonly`** _(boolean, optional)_: If `true`, the field's value is locked and cannot be modified by the user.
+- **`hidden`** _(boolean, optional)_: If `true`, the field is hidden from the user interface.
+- **`order`** _(number, optional)_: A numeric order determining the field's position relative to adjacent fields.
+
+---
+
+## Advanced Configuration (`advanced` object)
+
+The `advanced` property dictates finer HTML details, interactive structures, and native HTML attributes.
+
+### Common Options
+
+- **`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.
+- **`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).
+
+### Text & Numeric Options (`input/text`, `input/email`, `input/tel`, `input/password`, `input/number`)
+
+These basic field types support extra manipulation properties inside the `advanced` block:
+
+- **`length`** _({ min?: number, max?: number })_: Applies HTML structural limits (`minlength` / `maxlength`, or `min` / `max` depending on the input type).
+- **`transform`** _(string | string[])_: Safely intercepts user inputs and manipulates content dynamically. Options include:
+  - `"lowercase"`
+  - `"uppercase"`
+  - `"remove-space"`
+  - `"remove-accent"`
+
+### Temporal Options (`input/date`, `input/time`)
+
+Date and time inputs omit transformations and instead expose a `format` property directly under `advanced` for displaying values properly:
+
+- **Date format** _(used with `input/date`)_: `"yyyy-MM-dd"`, `"MM/dd/yyyy"`, `"dd/MM/yyyy"`, or `"MMMM d, yyyy"`.
+- **Time format** _(used with `input/time`)_: `"HH:mm"`, `"HH:mm:ss"`, `"hh:mm a"`, or `"hh:mm:ss a"`.
+
+---
+
+## Validation (`validation` object)
+
+The `validation` object resolves form errors overriding generic defaults, mapping the constraint rule name directly to the specific error message string.
+
+- **`required`** _(string)_: Specifies the error message exposed when the element is marked exactly as `required: true` and the field is empty.
+- **`email`** _(string)_: Error message specifically asserting an invalid email format.
+- **`length`** _({ min?: string, max?: string })_: Specific string messages shown when input lengths are breached.
+- **`custom`** _(CustomValidation | CustomValidation[])_: Powerful conditional-based logic blocks. An array specifying:
+  - `field`: Optional target reference string.
+  - `operator`: Logical evaluation operations (e.g., `eq`, `neq`, `gt`, `lt`).
+  - `message`: The resulting validation string.
+- **`requiredWhen`** _(WhenRule | WhenRule[])_: Makes the field required only when a condition over a sibling field holds.
+- **`pattern`** _(PatternRule)_: Validates the value against a regular expression (with optional interpolation bypass).
+- **`rules`** _(AssertRule[])_: A list of gated assertions (`oneOf`, `min`/`max`, `pattern`, …).
+
+_See the full [Validation reference](../validation/overview.md) for `requiredWhen`, `pattern`, `rules`, the operator vocabulary, and headless (server-side) validation._
+
+---
+
+## Events (`event` object)
+
+You can attach logic-rich cascading events seamlessly directly inside the field schema.
+
+- **`event.change`** _(ChangeEvent[])_: Triggers actions when logic runs. Common actions include emitting `value`, interacting with dependencies (`state`), or triggering data refetches (`source`). _Refer to the [Change Event Documentation](../events/change.md) for robust logic breakdowns._
+
+---
+
+## Complete Example Reference
+
+```json
+{
+  "name": "username",
+  "type": "input/text",
+  "label": "User Nickname",
+  "placeholder": "e.g. john_doe",
+  "required": true,
+  "description": {
+    "title": "Rule",
+    "message": "No spaces. No special characters.",
+    "collapsed": true
+  },
+  "advanced": {
+    "transform": ["lowercase", "remove-space"],
+    "length": {
+      "min": 4,
+      "max": 20
+    }
+  },
+  "validation": {
+    "required": "You must provide a nickname to continue.",
+    "length": {
+      "min": "Your nickname needs at least 4 letters."
+    }
+  }
+}
+```
+
+---
+
+## `textarea`
+
+Multi-line text. It takes the same core properties as an `input/*` field, and
+two of the `advanced` options above apply to it: `length` and `autocomplete`.
+Everything else in `advanced` is ignored for this type.
+
+```json
+{
+  "name": "notes",
+  "type": "textarea",
+  "label": "Notes",
+  "advanced": {
+    "length": { "max": 500 }
+  }
+}
+```
+
+`length.min` and `length.max` are emitted as the `minLength` and `maxLength`
+attributes on the rendered element.
+
+Like the `input/*` family, a declared `change` event on a `textarea` is
+debounced: it fires 300 ms after the last keystroke, not on every one.
+
+---
+
+## `checkbox`
+
+A single boolean. It is the one field family whose value is not carried by
+`value`: the rendered element receives `checked` instead.
+
+```json
+{
+  "name": "accepted",
+  "type": "checkbox",
+  "label": "I accept the terms",
+  "required": true
+}
+```
+
+A checkbox reads its state by truthiness, not by presence. `defaultValue: true`
+starts it checked; `false`, an omitted value, `null` and `0` all start it clear.
+A value passed to the form is read the same way, and both render paths agree.
+
+For a group of options rather than a single flag, use `chips` or `radio` — see
+[select.md](select.md).

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."
+  }
+}
+```