@ea-lab/reactive-json-docs 2.8.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.8.0",
+  "version": "2.11.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.8.0",
+    "@ea-lab/reactive-json": "^2.11.1",
     "@ea-lab/reactive-json-chartjs": "^1.1.1",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

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

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

@@ -22,8 +22,9 @@ The `SelectField` component provides a native HTML select dropdown with automati
 - `dataLocation` (string, optional): Path to bind the field value in the data context.
 - `defaultFieldValue` (any, optional): Default value when no data is present.
 - `label` (string or View props, optional): Field label text (supports template evaluation and View component rendering).
-- `options` (array, optional): Static array of option objects with `label` and `value` properties.
-- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableCategories`). Takes precedence over `options` if both are provided.
+- `options` (array, optional): Static array of option objects with `label` and `value` properties (both support template evaluation).
+- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableCategories`). 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`) override the item's keys.
 - `allowEmptyStringAsValue` (boolean, optional): Preserve empty strings as `""` instead of converting to `undefined` (default: `false`).
 - `attributes` (object, optional): Attributes applied to the container div (or merged with inputAttributes if no wrapper).
 - `inputAttributes` (object, optional): Attributes applied directly to the select element.
@@ -109,20 +110,22 @@ The `label` property supports both simple strings and View component rendering,
   dynamicOptions: ~.categories
 ```
 
-## Option Labels
+## Option Labels and Values
 
-Option labels support template evaluation, allowing dynamic content:
+The `label` and the `value` of each option support template evaluation: a string that is a whole template reference (`~.key`, `~~.key`, `~>key`...) is replaced by the referenced data. Text around a reference is not interpolated (`"Item: ~.itemName"` is displayed as is).
 
 ```yaml
 - type: SelectField
-  dataLocation: ~.item
+  dataLocation: ~.owner
   options:
-    - label: "Item: ~.itemName"
-      value: "item1"
-    - label: ["Count: ", ~.count]
-      value: "item2"
+    - label: "Nobody"
+      value: ""
+    - label: ~~.currentUser.name
+      value: ~~.currentUser.id
 ```
 
+Inside a template (a `Switch` item, for example), `~.` reads the item data, so each item can offer its own option.
+
 ## Empty Options Handling
 
 If `options` is empty or not an array, the component displays a single option: "No options available". This is useful for conditional rendering scenarios where options may be loaded dynamically.
@@ -211,6 +214,29 @@ data:
   selectedCategory: ""
 ```
 
+### Dynamic Options with a Mapping
+
+Use `optionMapping` when the items of the list do not have `label` / `value` keys:
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.stage
+    label: "Stage:"
+    dynamicOptions: ~.stages
+    optionMapping:
+      label: ~.title
+      value: ~.id
+
+data:
+  stages:
+    - id: "new"
+      title: "New"
+    - id: "won"
+      title: "Won"
+  stage: ""
+```
+
 ### Custom Attributes
 
 ```yaml
@@ -369,7 +395,7 @@ data:
 - **Automatic synchronization**: Unlike raw HTML elements that require manual setData actions
 - **Flexible wrapper**: Avoids unnecessary HTML when not needed
 - **Intelligent value handling**: Automatic conversion of boolean and null strings
-- **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`
 - **Label flexibility**: Supports both simple strings and View component rendering
 - **Empty state handling**: Gracefully handles empty options
 

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

@@ -43,13 +43,19 @@ renderView:
           after: "(array, optional)"
         details:
           type: Markdown
-          content: "Static array of option objects with `label` and `value` properties."
+          content: "Static array of option objects with `label` and `value` properties (both support template evaluation)."
       - term:
           code: dynamicOptions
           after: "(string, optional)"
         details:
           type: Markdown
-          content: "Template path to dynamic options array (e.g., `~.availableCategories`). Takes precedence over `options` if both are provided."
+          content: "Template path to dynamic options array (e.g., `~.availableCategories`). 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`) override the item's keys."
       - term:
           code: allowEmptyStringAsValue
           after: "(boolean, optional)"
@@ -222,6 +228,34 @@ renderView:
             value: "science"
         selectedCategory: ""
 
+  - type: RjBuildDescriber
+    title: "Dynamic Options with a Mapping"
+    description: "optionMapping reads the keys of items that have no label / value keys"
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.stage
+          label: "Stage:"
+          dynamicOptions: ~.stages
+          optionMapping:
+            label: ~.title
+            value: ~.id
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Selected stage: "
+            - ~.stage
+      data:
+        stages:
+          - id: "new"
+            title: "New"
+          - id: "qualified"
+            title: "Qualified"
+          - id: "won"
+            title: "Won"
+        stage: "new"
 
   - type: Markdown
     content: |
@@ -234,7 +268,7 @@ renderView:
       - **Automatic synchronization**: Unlike raw HTML elements that require manual setData actions
       - **Flexible wrapper**: Avoids unnecessary HTML when not needed
       - **Intelligent value handling**: Automatic conversion of boolean and null strings
-      - **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`
       - **Label flexibility**: Supports both simple strings and View component rendering
       - **Empty state handling**: Gracefully handles empty options
 

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

@@ -95,6 +95,38 @@ const onChange = (e) => {
 
 This ensures consistent behavior across TextField, NumberField, SelectField, CheckBoxField, TextAreaField, and DateField components.
 
+## evaluateFieldOptions Function
+
+This utility returns the evaluated options of an option-based component (`SelectField`, `CheckBoxField`, `LabelFromValue`). Use it in a custom component that reads `options` / `dynamicOptions` / `optionMapping`, so that it supports the same option sources as the core components.
+
+### Parameters
+
+- `props` (object): The component props. The function reads `dynamicOptions`, `options` and `optionMapping`.
+- `globalDataContext` (object): The global data context object
+- `templateContext` (object): The template context object
+
+### Return Value
+
+An array of option objects with evaluated `label` and `value` (empty when the source is not an array):
+
+- The source is `props.dynamicOptions` (a template reference, takes precedence) or the static `props.options` array.
+- With `props.optionMapping`, the mapping is evaluated for each item, the item being the template context (`~`). The mapped keys override the item keys.
+- Without `props.optionMapping`, the `label` and `value` of each item are evaluated in the component's template context. A scalar item is used as both label and value.
+
+### Usage Example
+
+```javascript
+const options = evaluateFieldOptions({ props, globalDataContext, templateContext });
+
+return (
+    <ul>
+        {options.map((option, index) => (
+            <li key={index} data-value={option.value}>{option.label}</li>
+        ))}
+    </ul>
+);
+```
+
 ## Limitations
 
 - Template data modification may not be the ideal approach (noted in code comments)