@ea-lab/reactive-json-docs 2.7.0 → 2.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.7.0",
+  "version": "2.10.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^2.5.1",
+    "@ea-lab/reactive-json": "^2.10.0",
     "@ea-lab/reactive-json-chartjs": "^1.1.1",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/advanced-concepts/forward-update.yaml

@@ -176,4 +176,4 @@ renderView:
 
 templates:
 
-data: {} 
+data:

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.yaml

@@ -225,4 +225,4 @@ renderView:
 
 templates:
 
-data: {} 
+data:

package/public/rjbuild/docs/advanced-concepts/plugins/index.yaml

@@ -26,4 +26,4 @@ renderView:
 
 templates:
 
-data: {} 
+data:

package/public/rjbuild/docs/core/action/CustomEventListener.yaml

@@ -155,4 +155,4 @@ renderView:
 
 templates:
 
-data: {}
+data:

package/public/rjbuild/docs/core/element/form/AutocompleteField.yaml

@@ -222,4 +222,4 @@ renderView:
       - No built-in keyboard navigation for the dropdown.
 
 templates: {}
-data: {}
+data:

package/public/rjbuild/docs/core/element/form/CheckBoxField.md

@@ -24,14 +24,15 @@ The `CheckBoxField` component provides checkbox and radio button groups with aut
 - `label` (string or View props, optional): Field label text (supports template evaluation and View component rendering).
 - `options` (array, optional): Static array of option objects, each with:
   - `label` (string, optional): Display text for the option (supports template evaluation).
-  - `value` (any, required): Value stored when this option is selected.
+  - `value` (any, required): Value stored when this option is selected (supports template evaluation, like `label`).
   - `attributes` (object, optional): Attributes applied to the option's container div.
-- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided.
+- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided. The items can be `{label, value}` objects, scalars (each scalar is used as both label and value), or objects of any shape mapped with `optionMapping`.
+- `optionMapping` (object, optional): Builds each option from an item of the options list. It is evaluated once per item, **with the item as the template context**: `~.title` reads the item's `title`, `~` is the whole item, `~~.` still reads the global data. The mapped keys (`label`, `value`, `attributes`) override the item's keys. See [Data-driven checkbox lists](#data-driven-checkbox-lists).
 - `controlType` (string, optional): Type of control - `"checkbox"` (default) or `"radio"`.
-- `multiple` (boolean, optional): Whether multiple selections are allowed. Defaults to `true` if more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`.
+- `multiple` (boolean, optional): Whether multiple selections are allowed. Defaults to `true` when the bound data is an array or when more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`.
 - `attributes` (object, optional): Attributes applied to the wrapper div (or container div if no wrapper).
 - `inputAttributes` (object, optional): Attributes applied directly to each input element.
-- `labelAttributes` (object, optional): Attributes applied to the main label (htmlFor is automatically managed).
+- `labelAttributes` (object, optional): Attributes applied to the field label and to each option label (`htmlFor` is automatically managed). An `id` is only applied to the field label.
 - `forceWrapper` (boolean, optional): Forces the presence (true) or absence (false) of the wrapper div. If omitted, wrapper is automatic only if label is present.
 - `actions` (array, optional): Actions to execute based on field state.
 
@@ -43,6 +44,8 @@ The component automatically synchronizes its value with the global data context.
 - **Single checkbox**: Stores a boolean (`true`) or the option's value when checked, `false` when unchecked.
 - **Multiple checkboxes**: Stores an array of selected option values.
 
+The mode is chosen as follows: radio when `controlType: "radio"`; otherwise `multiple` when set; otherwise **multiple when the bound data is already an array** or when there is more than one option. Initializing the data as an array (`[]`) is therefore enough to get a list of values, even with a single option.
+
 When `dataLocation` is used, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.
 
 ## Selection Modes
@@ -69,7 +72,7 @@ Radio buttons allow only one selection at a time. Set `controlType: "radio"`:
 
 ### Single Checkbox
 
-A single checkbox stores a boolean or the option's value:
+A single checkbox (one option, data not initialized as an array) stores a boolean or the option's value:
 
 ```yaml
 - type: CheckBoxField
@@ -83,6 +86,8 @@ A single checkbox stores a boolean or the option's value:
 
 **Data stored**: `true` when checked, `false` when unchecked (or the option's value if different from `true`)
 
+Several single checkboxes bound to the same data location overwrite each other's value, so they check and uncheck together. When they have different values, the component logs a warning: initialize the data as an array, or set `multiple: true`.
+
 ### Multiple Checkboxes
 
 Multiple checkboxes allow selecting several options simultaneously:
@@ -118,17 +123,15 @@ You can override the default behavior using the `forceWrapper` property. Setting
 
 **With label (automatic wrapper):**
 ```html
-<div>
-  <label>Select options:</label>
+<div role="group" aria-labelledby="checkbox-abc123-label">
+  <label id="checkbox-abc123-label">Select options:</label>
   <div>
-    <div>
-      <input type="checkbox" id="checkbox-abc123-0" value="opt1" />
-      <label htmlFor="checkbox-abc123-0">Option 1</label>
-    </div>
-    <div>
-      <input type="checkbox" id="checkbox-abc123-1" value="opt2" />
-      <label htmlFor="checkbox-abc123-1">Option 2</label>
-    </div>
+    <input type="checkbox" id="checkbox-abc123-0" value="opt1" />
+    <label for="checkbox-abc123-0">Option 1</label>
+  </div>
+  <div>
+    <input type="checkbox" id="checkbox-abc123-1" value="opt2" />
+    <label for="checkbox-abc123-1">Option 2</label>
   </div>
 </div>
 ```
@@ -138,7 +141,7 @@ You can override the default behavior using the `forceWrapper` property. Setting
 <div>
   <div>
     <input type="checkbox" id="checkbox-xyz789-0" value="opt1" />
-    <label htmlFor="checkbox-xyz789-0">Option 1</label>
+    <label for="checkbox-xyz789-0">Option 1</label>
   </div>
 </div>
 ```
@@ -186,6 +189,102 @@ Each option can have its own attributes applied to its container div:
 
 The component automatically generates unique IDs for each checkbox/radio button. If you provide an `id` in `inputAttributes`, it will be used as the base ID, and each option will have an index appended (e.g., `"my-id-0"`, `"my-id-1"`).
 
+## Accessibility
+
+- Each option label is associated with its input (`for` / `id`).
+- When a field `label` names several options, the element containing the options gets `role="group"` and `aria-labelledby` pointing to the field label (id from `labelAttributes.id`, or `<base id>-label`). Assistive technologies announce the field label when entering the group.
+- When a field `label` comes with a single option without its own label, the field label is directly associated with the input.
+- The radios of a field share a `name` (the base ID), so they form a native radio group: one tab stop, arrow keys navigation. Set `inputAttributes.name` to group radios rendered by several fields (one per `Switch` item, for example).
+- `attributes` can override `role` and `aria-labelledby`.
+
+## Data-driven checkbox lists
+
+To let users check items of a list held in the data (sessions, tags, recipients...), prefer, in this order:
+
+### 1. One field fed by the list (recommended)
+
+Use `dynamicOptions` on the list and `optionMapping` to read the keys of the items. The items can have any shape: here, a list of `{label}` objects typed by an editor.
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~~.lead.sessions
+    label: "Sessions"
+    dynamicOptions: ~~.sessions
+    optionMapping:
+      label: ~.label
+      value: ~.label
+
+data:
+  sessions:
+    - label: "20 octobre"
+    - label: "17 novembre"
+    - label: "15 décembre"
+  lead:
+    sessions: []
+```
+
+Checking "17 novembre" then "20 octobre" stores `lead.sessions: ["17 novembre", "20 octobre"]`. The options are a labelled group for assistive technologies. With a list of scalars (`sessions: ["20 octobre", "17 novembre"]`), `optionMapping` is not needed: each scalar is both the label and the value.
+
+### 2. One field per Switch item
+
+When each item needs its own markup around the checkbox, render one single-option field per item. The option `value` is evaluated in the item context, and the data initialized as an array keeps the fields independent:
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~~.sessions
+    singleOption:
+      load: sessionItem
+
+templates:
+  sessionItem:
+    - type: CheckBoxField
+      dataLocation: ~~.lead.sessions
+      options:
+        - label: ~.label
+          value: ~.label
+
+data:
+  sessions:
+    - label: "20 octobre"
+    - label: "17 novembre"
+  lead:
+    sessions: []
+```
+
+Keep `lead.sessions: []` in the data (or set `multiple: true` on the field): without an array, each field is a single checkbox that overwrites the shared value, and a warning is logged. For a single choice, use `controlType: radio` with a shared `inputAttributes.name`; the data then holds the selected value.
+
+### 3. Raw `input` elements (last resort)
+
+A raw `type: input` checkbox is a controlled input: its `checked` attribute must be bound, otherwise it is forced to `false` and never shows as checked (a warning is logged when it has event reactions). Bind a boolean with `checked: ~.isSelected`, or the membership in a list with an attribute transform:
+
+```yaml
+- type: input
+  attributes:
+    type: checkbox
+    value: ~.label
+  attributeTransforms:
+    - what: setAttributeValue
+      name: checked
+      mode: replace
+      value: true
+      when: ~~.lead.sessions
+      contains: ~.label
+```
+
+To store the list of checked values, add a [toggleData](../../reaction/toggleData.md) reaction: it adds the value when absent, and removes it when present.
+
+```yaml
+  actions:
+    - what: toggleData
+      on: change
+      path: ~~.lead.sessions
+      value: ~.label
+```
+
+Prefer patterns 1 and 2, which also handle the labels and the accessibility of the group.
+
 ## Empty Options Handling
 
 If `options` is empty or not an array, the component returns `null` and renders nothing. This is useful for conditional rendering scenarios.
@@ -297,6 +396,31 @@ data:
   selectedItems: []
 ```
 
+### Dynamic Options with a Mapping
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.recipients
+    label: "Recipients:"
+    dynamicOptions: ~.users
+    optionMapping:
+      label: ~.displayName
+      value: ~.uid
+      attributes:
+        class: ~.role
+
+data:
+  users:
+    - uid: 12
+      displayName: "Ada Lovelace"
+      role: "admin"
+    - uid: 27
+      displayName: "Alan Turing"
+      role: "editor"
+  recipients: []
+```
+
 ### With Actions
 
 ```yaml
@@ -347,11 +471,11 @@ data:
 
 - **Flexible selection modes**: Supports radio buttons, single checkbox, and multiple checkboxes
 - **Automatic data synchronization**: Values are automatically stored in the correct format
-- **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+- **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`, from a list of any shape with `optionMapping`
 - **Per-option customization**: Each option can have its own attributes
 - **Label flexibility**: Supports both simple strings and View component rendering
 - **Wrapper control**: Flexible wrapper system for styling control
-- **Accessibility**: Automatic label association with htmlFor attributes
+- **Accessibility**: Automatic label association, labelled group of options, native radio groups
 - **Empty state handling**: Gracefully handles empty options
 
 ## Limitations

package/public/rjbuild/docs/core/element/form/CheckBoxField.yaml

@@ -46,14 +46,20 @@ renderView:
           content: |
             Static array of option objects, each with:
             - `label` (string, optional): Display text for the option (supports template evaluation)
-            - `value` (any, required): Value stored when this option is selected
+            - `value` (any, required): Value stored when this option is selected (supports template evaluation, like `label`)
             - `attributes` (object, optional): Attributes applied to the option's container div
       - term:
           code: dynamicOptions
           after: "(string, optional)"
         details:
           type: Markdown
-          content: "Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided."
+          content: "Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided. The items can be `{label, value}` objects, scalars (each scalar is used as both label and value), or objects of any shape mapped with `optionMapping`."
+      - term:
+          code: optionMapping
+          after: "(object, optional)"
+        details:
+          type: Markdown
+          content: "Builds each option from an item of the options list. It is evaluated once per item, **with the item as the template context**: `~.title` reads the item's `title`, `~` is the whole item, `~~.` still reads the global data. The mapped keys (`label`, `value`, `attributes`) override the item's keys. See *Data-driven checkbox lists* below."
       - term:
           code: controlType
           after: "(string, optional)"
@@ -61,7 +67,7 @@ renderView:
       - term:
           code: multiple
           after: "(boolean, optional)"
-        details: "Whether multiple selections are allowed. Defaults to `true` if more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`."
+        details: "Whether multiple selections are allowed. Defaults to `true` when the bound data is an array or when more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`."
       - term:
           code: attributes
           after: "(object, optional)"
@@ -73,7 +79,7 @@ renderView:
       - term:
           code: labelAttributes
           after: "(object, optional)"
-        details: "Attributes applied to the main label (htmlFor is automatically managed)."
+        details: "Attributes applied to the field label and to each option label (`htmlFor` is automatically managed). An `id` is only applied to the field label."
       - term:
           code: forceWrapper
           after: "(boolean, optional)"
@@ -93,6 +99,8 @@ renderView:
       - **Single checkbox**: Stores a boolean (`true`) or the option's value when checked, `false` when unchecked
       - **Multiple checkboxes**: Stores an array of selected option values
 
+      The mode is chosen as follows: radio when `controlType: "radio"`; otherwise `multiple` when set; otherwise **multiple when the bound data is already an array** or when there is more than one option. Initializing the data as an array (`[]`) is therefore enough to get a list of values, even with a single option.
+
       When `dataLocation` is used, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.
 
       ## Selection Modes
@@ -105,10 +113,12 @@ renderView:
 
       ### Single Checkbox
 
-      A single checkbox stores a boolean or the option's value:
+      A single checkbox (one option, data not initialized as an array) stores a boolean or the option's value:
 
       **Data stored**: `true` when checked, `false` when unchecked (or the option's value if different from `true`)
 
+      Several single checkboxes bound to the same data location overwrite each other's value, so they check and uncheck together. When they have different values, the component logs a warning: initialize the data as an array, or set `multiple: true`.
+
       ### Multiple Checkboxes
 
       Multiple checkboxes allow selecting several options simultaneously:
@@ -195,6 +205,121 @@ renderView:
             value: "item4"
         selectedItems: []
 
+  - type: Markdown
+    content: |
+      ## Accessibility
+
+      - Each option label is associated with its input (`for` / `id`).
+      - When a field `label` names several options, the element containing the options gets `role="group"` and `aria-labelledby` pointing to the field label (id from `labelAttributes.id`, or `<base id>-label`). Assistive technologies announce the field label when entering the group.
+      - When a field `label` comes with a single option without its own label, the field label is directly associated with the input.
+      - The radios of a field share a `name` (the base ID), so they form a native radio group: one tab stop, arrow keys navigation. Set `inputAttributes.name` to group radios rendered by several fields (one per `Switch` item, for example).
+      - `attributes` can override `role` and `aria-labelledby`.
+
+      ## Data-driven checkbox lists
+
+      To let users check items of a list held in the data (sessions, tags, recipients...), prefer, in this order:
+
+      ### 1. One field fed by the list (recommended)
+
+      Use `dynamicOptions` on the list and `optionMapping` to read the keys of the items. The items can have any shape: here, a list of `{label}` objects typed by an editor. With a list of scalars, `optionMapping` is not needed: each scalar is both the label and the value.
+
+  - type: RjBuildDescriber
+    title: "One field fed by the list"
+    description: "dynamicOptions + optionMapping: the items only have a label, which is also the stored value"
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~~.lead.sessions
+          label: "Sessions"
+          dynamicOptions: ~~.sessions
+          optionMapping:
+            label: ~.label
+            value: ~.label
+        - type: div
+          content:
+            - type: strong
+              content: "Selected: "
+            - type: Join
+              content: ~~.lead.sessions
+              separator: ", "
+      data:
+        sessions:
+          - label: "20 octobre"
+          - label: "17 novembre"
+          - label: "15 décembre"
+        lead:
+          sessions: []
+
+  - type: Markdown
+    content: |
+      ### 2. One field per Switch item
+
+      When each item needs its own markup around the checkbox, render one single-option field per item. The option `value` is evaluated in the item context, and the data initialized as an array keeps the fields independent.
+
+      Keep `lead.sessions: []` in the data (or set `multiple: true` on the field): without an array, each field is a single checkbox that overwrites the shared value, and a warning is logged. For a single choice, use `controlType: radio` with a shared `inputAttributes.name`; the data then holds the selected value.
+
+  - type: RjBuildDescriber
+    title: "One field per Switch item"
+    description: "Each item renders its own single-option CheckBoxField, all bound to the same array"
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~~.sessions
+          singleOption:
+            load: sessionItem
+        - type: div
+          content:
+            - type: strong
+              content: "Selected: "
+            - type: Join
+              content: ~~.lead.sessions
+              separator: ", "
+      templates:
+        sessionItem:
+          - type: CheckBoxField
+            dataLocation: ~~.lead.sessions
+            options:
+              - label: ~.label
+                value: ~.label
+      data:
+        sessions:
+          - label: "20 octobre"
+          - label: "17 novembre"
+          - label: "15 décembre"
+        lead:
+          sessions: []
+
+  - type: Markdown
+    content: |
+      ### 3. Raw `input` elements (last resort)
+
+      A raw `type: input` checkbox is a controlled input: its `checked` attribute must be bound, otherwise it is forced to `false` and never shows as checked (a warning is logged when it has event reactions). Bind a boolean with `checked: ~.isSelected`, or the membership in a list with an attribute transform:
+
+      ```yaml
+      - type: input
+        attributes:
+          type: checkbox
+          value: ~.label
+        attributeTransforms:
+          - what: setAttributeValue
+            name: checked
+            mode: replace
+            value: true
+            when: ~~.lead.sessions
+            contains: ~.label
+      ```
+
+      To store the list of checked values, add a [toggleData](../../reaction/toggleData) reaction: it adds the value when absent, and removes it when present.
+
+      ```yaml
+        actions:
+          - what: toggleData
+            on: change
+            path: ~~.lead.sessions
+            value: ~.label
+      ```
+
+      Prefer patterns 1 and 2, which also handle the labels and the accessibility of the group.
 
   - type: Markdown
     content: |
@@ -202,11 +327,11 @@ renderView:
 
       - **Flexible selection modes**: Supports radio buttons, single checkbox, and multiple checkboxes
       - **Automatic data synchronization**: Values are automatically stored in the correct format
-      - **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+      - **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`, from a list of any shape with `optionMapping`
       - **Per-option customization**: Each option can have its own attributes
       - **Label flexibility**: Supports both simple strings and View component rendering
       - **Wrapper control**: Flexible wrapper system for styling control
-      - **Accessibility**: Automatic label association with htmlFor attributes
+      - **Accessibility**: Automatic label association, labelled group of options, native radio groups
       - **Empty state handling**: Gracefully handles empty options
 
       ## Limitations
@@ -218,5 +343,5 @@ renderView:
       - For radio buttons, `multiple` is automatically set to `false` regardless of the `multiple` property
 
 templates: {}
-data: {}
+data:
 

package/public/rjbuild/docs/core/element/form/DateField.md

@@ -0,0 +1,79 @@
+# DateField
+
+The `DateField` component is a thin convenience wrapper around [`Input`](Input.md) that renders an HTML `date` input (`<input type="date">`). It inherits every `Input` option (label, wrapper, attributes, actions, data binding) and adds an optional `storageFormat` for binding to a fixed-format storage string.
+
+## Basic Syntax
+
+```yaml
+- type: DateField
+  dataLocation: ~.startDate
+  label: "Start date:"
+```
+
+By default the raw value of the HTML `date` input (`YYYY-MM-DD`) is stored as-is — identical to any other `Input` wrapper.
+
+## Properties
+
+- `dataLocation` (string, optional): Path to bind the field value in the data context. Without it, the value is stored in the template context under the component's `datafield`.
+- `defaultFieldValue` (string, optional): Default value when no data is present.
+- `label` (string or View props, optional): Field label text (supports template evaluation and View rendering). A wrapper `<div>` is added automatically when a label is present.
+- `storageFormat` (string, optional): Binds the field to a fixed-format **storage string** instead of the raw input value. Accepts `"date"` or `"datetime"` (see [Storage format](#storage-format)). When omitted, the raw `YYYY-MM-DD` value is stored unchanged (original behavior).
+- `attributes` (object, optional): Attributes applied to the wrapper `<div>` (or to the input itself when there is no wrapper).
+- `inputAttributes` (object, optional): Attributes applied directly to the `<input>` element (e.g. `class`, `id`, `min`, `max`).
+- `labelAttributes` (object, optional): Attributes applied to the label (`htmlFor` is managed automatically).
+- `forceWrapper` (boolean, optional): Forces the presence (`true`) or absence (`false`) of the wrapper `<div>`. If omitted, the wrapper appears only when a label is present.
+- `actions` (array, optional): Actions and conditional reactions to execute based on field state.
+
+## Storage format
+
+An HTML `date` input can only read and write `YYYY-MM-DD`. Backends often store dates in a fixed, stricter format — for example Drupal datetime fields validate against `Y-m-d` (date-only field) or `Y-m-d\TH:i:s` (datetime field). Feeding such a value straight to a `date` input leaves it blank (the input rejects a value carrying a time), and writing back `YYYY-MM-DD` is rejected by a datetime field.
+
+Set `storageFormat` to bridge the two. It applies **two conversions**:
+
+- **On read** — only the date part of the stored value is shown, so a datetime value like `2016-11-29T23:00:00` displays as `2016-11-29` instead of leaving the input empty.
+- **On write** — the value is re-serialized to the target storage format:
+  - `storageFormat: date` → `YYYY-MM-DD`
+  - `storageFormat: datetime` → `YYYY-MM-DDT00:00:00` (the time is anchored at midnight, since a `date` input carries no time)
+
+An empty input stores an empty string (clears the field). When `storageFormat` is omitted, no conversion happens and the raw input value is stored — so existing usages are unaffected.
+
+> For editing a value that also carries a **time** the user should see and change, use [`DateTimeField`](DateTimeField.md) instead.
+
+## Examples
+
+### Default behavior (raw `YYYY-MM-DD`)
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.startDate
+    label: "Start date:"
+  - type: div
+    content:
+      - type: strong
+        content: "Stored value: "
+      - ~.startDate
+
+data:
+  startDate: "2027-03-15"
+```
+
+### `storageFormat: datetime`
+
+The `date` input drives a datetime storage string (time anchored at midnight):
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.closeDate
+    label: "Close date:"
+    storageFormat: datetime
+  - type: div
+    content:
+      - type: strong
+        content: "Stored value: "
+      - ~.closeDate
+
+data:
+  closeDate: "2016-11-29T23:00:00"
+```