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

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

@@ -0,0 +1,115 @@
+renderView:
+  - type: Markdown
+    content: |
+      # DateField
+
+      The `DateField` component is a thin convenience wrapper around [`Input`](/docs/core/element/form/Input) 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.
+
+  - type: Markdown
+    content: |
+      ## 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
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "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`."
+      - term:
+          code: defaultFieldValue
+          after: "(string, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string or View props, optional)"
+        details: "Field label text (supports template evaluation and View rendering). A wrapper `<div>` is added automatically when a label is present."
+      - term:
+          code: storageFormat
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            Binds the field to a fixed-format **storage string** instead of the raw input value. Accepts `"date"` or `"datetime"`. See [Storage format](#storage-format) below. When omitted, the raw `YYYY-MM-DD` value is stored unchanged (original behavior).
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the wrapper `<div>` (or to the input itself when there is no wrapper)."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the `<input>` element (e.g. `class`, `id`, `min`, `max`)."
+      - term:
+          code: labelAttributes
+          after: "(object, optional)"
+        details: "Attributes applied to the label (`htmlFor` is managed automatically)."
+      - term:
+          code: forceWrapper
+          after: "(boolean, optional)"
+        details: "Forces the presence (`true`) or absence (`false`) of the wrapper `<div>`. If omitted, the wrapper appears only when a label is present."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions and conditional reactions to execute based on field state (hide, tooltip, setData, …)."
+
+  - type: Markdown
+    content: |
+      ## 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`](/docs/core/element/form/DateTimeField) instead.
+
+  - type: RjBuildDescriber
+    title: "Default behavior (raw YYYY-MM-DD)"
+    description: "Without storageFormat, the raw input value is stored as-is."
+    toDescribe:
+      renderView:
+        - type: DateField
+          dataLocation: ~.startDate
+          label: "Start date:"
+        - type: div
+          content:
+            - type: strong
+              content: "Stored value: "
+            - ~.startDate
+      data:
+        startDate: "2027-03-15"
+
+  - type: RjBuildDescriber
+    title: "storageFormat: datetime"
+    description: "The date input drives a datetime storage string (time anchored at midnight)."
+    toDescribe:
+      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"
+
+templates: {}
+data:

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

@@ -0,0 +1,60 @@
+# DateTimeField
+
+The `DateTimeField` component is a thin convenience wrapper around [`Input`](Input.md) that renders an HTML `datetime-local` input (`<input type="datetime-local">`). It inherits every `Input` option and adds an optional `storageFormat` for binding to a fixed-format storage string.
+
+## Basic Syntax
+
+```yaml
+- type: DateTimeField
+  dataLocation: ~.meetingAt
+  label: "Meeting date and time:"
+```
+
+By default the raw value of the HTML `datetime-local` input (`YYYY-MM-DDTHH:MM`) is stored as-is.
+
+## 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-DDTHH:MM` 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`, `step`).
+- `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 `datetime-local` input reads and writes `YYYY-MM-DDTHH:MM` — **without seconds** (browsers omit the `:00` seconds unless a sub-minute `step` is set, and even then behavior varies). A backend datetime field that validates against a fixed format such as Drupal's `Y-m-d\TH:i:s` therefore rejects the raw value.
+
+Set `storageFormat` to bridge the two. It applies **two conversions**:
+
+- **On read** — the date + time part of the stored value is shown (a stored `2016-11-29T23:00:00` displays as `2016-11-29T23:00`).
+- **On write** — the value is re-serialized to the target storage format:
+  - `storageFormat: datetime` → `YYYY-MM-DDTHH:MM:SS` (seconds appended; `00` when the input has no time)
+  - `storageFormat: date` → `YYYY-MM-DD` (time dropped)
+
+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.
+
+## Example
+
+### `storageFormat: datetime`
+
+The `datetime-local` input drives a datetime storage string, with seconds:
+
+```yaml
+renderView:
+  - type: DateTimeField
+    dataLocation: ~.closeDate
+    label: "Close date and time:"
+    storageFormat: datetime
+  - type: div
+    content:
+      - type: strong
+        content: "Stored value: "
+      - ~.closeDate
+
+data:
+  closeDate: "2016-11-29T23:00:00"
+```

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

@@ -0,0 +1,97 @@
+renderView:
+  - type: Markdown
+    content: |
+      # DateTimeField
+
+      The `DateTimeField` component is a thin convenience wrapper around [`Input`](/docs/core/element/form/Input) that renders an HTML `datetime-local` input (`<input type="datetime-local">`). It inherits every `Input` option and adds an optional `storageFormat` for binding to a fixed-format storage string.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: DateTimeField
+        dataLocation: ~.meetingAt
+        label: "Meeting date and time:"
+      ```
+
+      By default the raw value of the HTML `datetime-local` input (`YYYY-MM-DDTHH:MM`) is stored as-is.
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "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`."
+      - term:
+          code: defaultFieldValue
+          after: "(string, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string or View props, optional)"
+        details: "Field label text (supports template evaluation and View rendering). A wrapper `<div>` is added automatically when a label is present."
+      - term:
+          code: storageFormat
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            Binds the field to a fixed-format **storage string** instead of the raw input value. Accepts `"date"` or `"datetime"`. See [Storage format](#storage-format) below. When omitted, the raw `YYYY-MM-DDTHH:MM` value is stored unchanged (original behavior).
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the wrapper `<div>` (or to the input itself when there is no wrapper)."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the `<input>` element (e.g. `class`, `id`, `min`, `max`, `step`)."
+      - term:
+          code: labelAttributes
+          after: "(object, optional)"
+        details: "Attributes applied to the label (`htmlFor` is managed automatically)."
+      - term:
+          code: forceWrapper
+          after: "(boolean, optional)"
+        details: "Forces the presence (`true`) or absence (`false`) of the wrapper `<div>`. If omitted, the wrapper appears only when a label is present."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions and conditional reactions to execute based on field state."
+
+  - type: Markdown
+    content: |
+      ## Storage format
+
+      An HTML `datetime-local` input reads and writes `YYYY-MM-DDTHH:MM` — **without seconds** (browsers omit the `:00` seconds unless a sub-minute `step` is set, and even then behavior varies). A backend datetime field that validates against a fixed format such as Drupal's `Y-m-d\TH:i:s` therefore rejects the raw value.
+
+      Set `storageFormat` to bridge the two. It applies **two conversions**:
+
+      - **On read** — the date + time part of the stored value is shown (a stored `2016-11-29T23:00:00` displays as `2016-11-29T23:00`).
+      - **On write** — the value is re-serialized to the target storage format:
+        - `storageFormat: datetime` → `YYYY-MM-DDTHH:MM:SS` (seconds appended; `00` when the input has no time)
+        - `storageFormat: date` → `YYYY-MM-DD` (time dropped)
+
+      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.
+
+  - type: RjBuildDescriber
+    title: "storageFormat: datetime"
+    description: "The datetime-local input drives a datetime storage string, with seconds."
+    toDescribe:
+      renderView:
+        - type: DateTimeField
+          dataLocation: ~.closeDate
+          label: "Close date and time:"
+          storageFormat: datetime
+        - type: div
+          content:
+            - type: strong
+              content: "Stored value: "
+            - ~.closeDate
+      data:
+        closeDate: "2016-11-29T23:00:00"
+
+templates: {}
+data:

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

@@ -569,4 +569,4 @@ renderView:
       - Integrated label is limited: for conditional actions, prefer separated label
 
 templates: {}
-data: {}
+data:

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
 
@@ -248,5 +282,5 @@ renderView:
       - Empty string handling requires explicit `allowEmptyStringAsValue` for semantic distinction
 
 templates: {}
-data: {}
+data:
 

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

@@ -135,5 +135,5 @@ renderView:
       - Template evaluation for `rows` should return a number
 
 templates: {}
-data: {}
+data:
 

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)

package/public/rjbuild/docs/core/element/html/Html.yaml

@@ -74,6 +74,53 @@ renderView:
         class: ""
         txt: Hello world!
 
+  - type: Markdown
+    content: |
+      ## URL attributes
+
+      The URL attributes (`href`, `src`, `action`, `formAction`, `poster`) accept an array of segments, in the format of the `src` of `additionalDataSource` (see *Dynamic URLs with `src` as Array* in [RjBuild structure](../../getting-started/rjbuild-structure)). The references are evaluated in the current template context, so each item of a `Switch` gets its own URL:
+
+      ```yaml
+      - type: a
+        attributes:
+          href:
+            - "/article/"
+            - ~.year
+            - "/"
+            - segment: ~.slug
+              required: true
+        content: ~.title
+      ```
+
+      When a required segment is empty, the attribute is omitted. An array in another attribute is evaluated as before (each item separately).
+
+  - type: Markdown
+    content: |
+      ## Form controls
+
+      `input`, `textarea` and `select` elements are rendered as **controlled** React elements: their `value` defaults to `""`.
+
+      A checkbox or radio `input` is controlled by its `checked` attribute, which defaults to `false`. Without a binding, the input never shows as checked, whatever its reactions do to the data. Bind it to the data:
+
+      - a boolean: `checked: ~.isSelected` (a falsy value leaves the input unchecked);
+      - a comparison or a list membership: an `attributeTransforms` entry setting `checked`, with a condition (`is`, `contains`...).
+
+      ```yaml
+      - type: input
+        attributes:
+          type: checkbox
+          value: ~.label
+        attributeTransforms:
+          - what: setAttributeValue
+            name: checked
+            mode: replace
+            value: true
+            when: ~~.lead.sessions
+            contains: ~.label
+      ```
+
+      A warning is logged when a checkbox or radio has event reactions (`on: change`...) but neither a `checked` attribute nor an attribute transform on `checked`. To store a value or a list of values, prefer [CheckBoxField](../form/CheckBoxField), which binds `checked` itself.
+
   - type: Markdown
     content: |
       ## Limitations

package/public/rjbuild/docs/core/element/html/Join.yaml

@@ -110,4 +110,4 @@ renderView:
       - No per-item formatting; all elements are joined as plain strings.
 
 templates: {}
-data: {}
+data: