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

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/LabelFromValue.md

@@ -0,0 +1,159 @@
+# LabelFromValue
+
+The `LabelFromValue` component displays the **label** associated with a value, using an option-like structure as data source. It is the read-only counterpart of the form fields: the same `{label, value}` list feeding a [`SelectField`](../form/SelectField.md) or a [`CheckBoxField`](../form/CheckBoxField.md) can be reused to render the selected value as text.
+
+## Basic Syntax
+
+```yaml
+- type: LabelFromValue
+  dataLocation: ~.status
+  options:
+    - label: "Active"
+      value: 1
+    - label: "Inactive"
+      value: 2
+```
+
+With `status: 2` in the data, this renders `Inactive`.
+
+## Properties
+
+- `dataLocation` (string, optional): Path to the value to resolve. Without it, the value is read from the template context under the component's `datafield`.
+- `options` (array, optional): Array of `{label, value}` objects (both support template evaluation). Ignored when `dynamicOptions` is set.
+- `dynamicOptions` (any, optional): Template reference resolving to the options array (e.g. `~~.allStages`, typically options loaded from a backend). Takes precedence over `options`. 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, exactly like in `SelectField` and `CheckBoxField`. It is evaluated once per item, **with the item as the template context** (`~.title` reads the item's `title`, `~~.` still reads the global data). The mapped keys override the item's keys.
+- `defaultFieldValue` (any, optional): Value used when no data is present.
+- `loose` (boolean, optional): Matches the options by `String()`-coerced equality instead of the default strict one (see [Loose matching](#loose-matching)). Omitted or `false` = strict equality (original behavior).
+- `actions` (array, optional): Actions and conditional reactions to execute based on component state (hide, tooltip, …).
+
+The label is rendered through the `View` engine, so it can be a plain string or a full component structure (`{type: strong, content: …}`).
+
+## Loose matching
+
+By default an option matches the current value only on **strict** equality (`===`), so `1` (number) and `"1"` (string) are two different values and no label is found.
+
+This bites when the JS type of the same identifier is not guaranteed across sources. A typical case is a decoupled backend that renders an entity reference id as a **string** when reading the entity, but echoes it back as a **number** in its save response: the label is correct on load, then disappears right after a save — until a full reload restores the original type.
+
+Set `loose: true` to compare the values as strings instead:
+
+```yaml
+- type: LabelFromValue
+  dataLocation: ~.stage
+  dynamicOptions: ~~.allStages
+  loose: true
+```
+
+Nullish values are never coerced: an empty value (`null` / `undefined`) still matches nothing, so it cannot accidentally match an option whose value is the `"null"` string. `loose` is opt-in — omitted, the component behaves exactly as before, so existing usages are unaffected.
+
+## Examples
+
+### Display the label of a selected value
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.status
+    label: "Status"
+    options:
+      - label: "Active"
+        value: 1
+      - label: "Inactive"
+        value: 2
+      - label: "Pending"
+        value: 3
+  - type: div
+    content:
+      - type: strong
+        content: "Label: "
+      - type: LabelFromValue
+        dataLocation: ~.status
+        options:
+          - label: "Active"
+            value: 1
+          - label: "Inactive"
+            value: 2
+          - label: "Pending"
+            value: 3
+
+data:
+  status: 3
+```
+
+Renders: `Label: Pending`.
+
+### Options loaded from a backend, with loose matching
+
+```yaml
+renderView:
+  - type: LabelFromValue
+    dataLocation: ~~.deal.data.stage
+    dynamicOptions: ~~.allStages
+    loose: true
+
+data:
+  # allStages is typically fetched (additionalDataSource) as
+  # [{label: "Discovery", value: "12"}, {label: "Negotiation", value: "13"}, …]
+  deal:
+    data:
+      stage: 13
+```
+
+The value is a number while the option values are strings: without `loose`, nothing would be displayed.
+
+### Options of any shape, with a mapping
+
+```yaml
+renderView:
+  - type: LabelFromValue
+    dataLocation: ~~.deal.stage
+    dynamicOptions: ~~.stages
+    optionMapping:
+      label: ~.title
+      value: ~.id
+
+data:
+  stages:
+    - id: "new"
+      title: "New"
+    - id: "won"
+      title: "Won"
+  deal:
+    stage: "won"
+```
+
+Renders: `Won`. Use the same `optionMapping` as the `SelectField` editing the value.
+
+### Inside a template, against global data
+
+```yaml
+templates:
+  userCard:
+    type: div
+    content:
+      - "Admin: "
+      - type: LabelFromValue
+        dataLocation: ~~.isAdmin
+        options:
+          - label: "Yes"
+            value: true
+          - label: "No"
+            value: false
+
+renderView:
+  - load: userCard
+
+data:
+  isAdmin: true
+```
+
+## Notes
+
+- The first matching option wins; the options list is not deduplicated.
+- When no option matches the value (or the matched option carries no `label`), nothing is displayed — the value itself is not used as a fallback label.
+- An empty value (`null`, `undefined`, `""`) therefore renders nothing, unless an option explicitly declares that value.
+
+## Limitations
+
+- No support for grouped options or nested option structures.
+- No built-in formatting of the label (wrap the component if needed).
+- Multi-value data (an array of values) is not supported: the whole array is compared to each option value.

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

@@ -3,7 +3,23 @@ renderView:
     content: |
       # LabelFromValue
 
-      The `LabelFromValue` component displays the label associated with a value, using an option-like structure. It is useful for showing the display label of a value selected in a SelectField or any value/label mapping.
+      The `LabelFromValue` component displays the **label** associated with a value, using an option-like structure as data source. It is the read-only counterpart of the form fields: the same `{label, value}` list feeding a [`SelectField`](/docs/core/element/form/SelectField) or a [`CheckBoxField`](/docs/core/element/form/CheckBoxField) can be reused to render the selected value as text.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: LabelFromValue
+        dataLocation: ~.status
+        options:
+          - label: "Active"
+            value: 1
+          - label: "Inactive"
+            value: 2
+      ```
+
+      With `status: 2` in the data, this renders `Inactive`.
 
       ## Properties
 
@@ -11,22 +27,44 @@ renderView:
     content:
       - term:
           code: dataLocation
-          after: "(string, required)"
-        details: "Path to the value."
+          after: "(string, optional)"
+        details: "Path to the value to resolve. Without it, the value is read from the template context under the component's `datafield`."
       - term:
           code: options
           after: "(array, optional)"
         details:
           type: Markdown
-          content: "Array of `{label, value}` objects."
+          content: "Array of `{label, value}` objects (both support template evaluation). Ignored when `dynamicOptions` is set."
       - term:
           code: dynamicOptions
           after: "(any, optional)"
-        details: "Template value for dynamic options."
+        details:
+          type: Markdown
+          content: "Template reference resolving to the options array (e.g. `~~.allStages`, typically options loaded from a backend). Takes precedence over `options`. 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, exactly like in `SelectField` and `CheckBoxField`. It is evaluated once per item, **with the item as the template context** (`~.title` reads the item's `title`, `~~.` still reads the global data). The mapped keys override the item's keys."
       - term:
           code: defaultFieldValue
           after: "(any, optional)"
-        details: "Default value if none is set."
+        details: "Value used when no data is present."
+      - term:
+          code: loose
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: "Matches the options by `String()`-coerced equality instead of the default strict one. See [Loose matching](#loose-matching). Omitted or `false` = strict equality (original behavior)."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions and conditional reactions to execute based on component state (hide, tooltip, …)."
+
+  - type: Markdown
+    content: |
+      The label is rendered through the `View` engine, so it can be a plain string or a full component structure (`{type: strong, content: …}`).
 
   - type: RjBuildDescriber
     title: "Interactive Example: Display label from value"
@@ -64,8 +102,123 @@ renderView:
 
   - type: Markdown
     content: |
+      ## Loose matching
+
+      By default an option matches the current value only on **strict** equality (`===`), so `1` (number) and `"1"` (string) are two different values and no label is found.
+
+      This bites when the JS type of the same identifier is not guaranteed across sources. A typical case is a decoupled backend that renders an entity reference id as a **string** when reading the entity, but echoes it back as a **number** in its save response: the label is correct on load, then disappears right after a save — until a full reload restores the original type.
+
+      Set `loose: true` to compare the values as strings instead:
+
+      ```yaml
+      - type: LabelFromValue
+        dataLocation: ~.stage
+        dynamicOptions: ~~.allStages
+        loose: true
+      ```
+
+      Nullish values are never coerced: an empty value (`null` / `undefined`) still matches nothing, so it cannot accidentally match an option whose value is the `"null"` string. `loose` is opt-in — omitted, the component behaves exactly as before.
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Loose matching"
+    description:
+      - type: Markdown
+        content: |
+          Both components read the same value, `"2"` (a **string**), against options whose values are **numbers**. Only the loose one finds the label.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: strong
+              content: "Strict (default): "
+            - type: LabelFromValue
+              dataLocation: ~.status
+              options:
+                - label: "Active"
+                  value: 1
+                - label: "Inactive"
+                  value: 2
+                - label: "Pending"
+                  value: 3
+        - type: div
+          content:
+            - type: strong
+              content: "Loose: "
+            - type: LabelFromValue
+              dataLocation: ~.status
+              loose: true
+              options:
+                - label: "Active"
+                  value: 1
+                - label: "Inactive"
+                  value: 2
+                - label: "Pending"
+                  value: 3
+      data:
+        status: "2"
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Options loaded from a backend"
+    description:
+      - type: Markdown
+        content: |
+          `dynamicOptions` reads the options from the data (here `allStages`, as an `additionalDataSource` would provide them). The value is a **number** while the option values are **strings**, hence `loose: true`.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: strong
+              content: "Stage: "
+            - type: LabelFromValue
+              dataLocation: ~~.deal.data.stage
+              dynamicOptions: ~~.allStages
+              loose: true
+      data:
+        allStages:
+          - label: "Discovery"
+            value: "12"
+          - label: "Negotiation"
+            value: "13"
+          - label: "Closed won"
+            value: "14"
+        deal:
+          data:
+            stage: 13
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Inside a template, against global data"
+    description:
+      - type: Markdown
+        content: |
+          Within a template, `~~.` reaches the global data while `~.` would stay in the template scope.
+    toDescribe:
+      renderView:
+        - load: userCard
+      templates:
+        userCard:
+          type: div
+          content:
+            - "Admin: "
+            - type: LabelFromValue
+              dataLocation: ~~.isAdmin
+              options:
+                - label: "Yes"
+                  value: true
+                - label: "No"
+                  value: false
+      data:
+        isAdmin: true
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - The first matching option wins; the options list is not deduplicated.
+      - When no option matches the value (or the matched option carries no `label`), nothing is displayed — the value itself is not used as a fallback label.
+      - An empty value (`null`, `undefined`, `""`) therefore renders nothing, unless an option explicitly declares that value.
+
       ## Limitations
-      - Only the first matching label is displayed; duplicate values in options are not supported.
-      - No support for grouped options or nested structures.
-      - No built-in formatting for the label (use a wrapper if needed).
-      - If no options are provided, the raw value is shown.
+
+      - No support for grouped options or nested option structures.
+      - No built-in formatting of the label (wrap the component if needed).
+      - Multi-value data (an array of values) is not supported: the whole array is compared to each option value.

package/public/rjbuild/docs/core/example/native-html-forms.md

@@ -146,13 +146,22 @@ Use the `for` attribute to associate labels with form elements for accessibility
 ```
 
 ### Radio Buttons
+
+Each radio must be checked only when the stored value is its own. `checked: ~.selectedSize` would check every radio as soon as a size is selected, so compare the value with an attribute transform:
+
 ```yaml
 - type: input
   attributes:
     type: "radio"
     name: "size"
     value: "small"
-    checked: ~.selectedSize
+  attributeTransforms:
+    - what: setAttributeValue
+      name: checked
+      mode: replace
+      value: true
+      when: ~.selectedSize
+      is: "small"
   actions:
     - what: setData
       on: change
@@ -164,7 +173,13 @@ Use the `for` attribute to associate labels with form elements for accessibility
     type: "radio"
     name: "size"
     value: "large"
-    checked: ~.selectedSize
+  attributeTransforms:
+    - what: setAttributeValue
+      name: checked
+      mode: replace
+      value: true
+      when: ~.selectedSize
+      is: "large"
   actions:
     - what: setData
       on: change
@@ -172,6 +187,8 @@ Use the `for` attribute to associate labels with form elements for accessibility
       value: "large"
 ```
 
+A checkbox or radio without a `checked` binding (attribute or attribute transform) is forced to unchecked and never shows a user's click. [CheckBoxField](../element/form/CheckBoxField.md) with `controlType: radio` handles all of this by itself.
+
 ## Advanced Patterns
 
 ### Form Validation with Conditional Actions

package/public/rjbuild/docs/core/reaction/collectField.md

@@ -0,0 +1,51 @@
+# Reaction: collectField
+
+The `collectField` reaction writes the values of one field of every item of a collection, as an array. Typical use: a "select all" checkbox that writes the identifiers of the listed items.
+
+## Properties
+
+- `from` (string, required): The collection (template syntax), an array of objects.
+- `field` (string, required): The name of the field to read in each item. It is evaluated.
+- `path` (string, required): The location receiving the array (template syntax).
+
+## Behavior
+
+- The array of the `field` values is written at `path`, in the order of the collection.
+- The items that are not objects, and the items whose field is `null`, `undefined` or an empty string, are skipped.
+- A collection that is not an array writes an empty array.
+- The collection is read from the complete data, even inside a `DataFilter`.
+
+## Example
+
+### Select all / deselect all
+
+```yaml
+renderView:
+  - type: button
+    content: "Select all"
+    actions:
+      - what: collectField
+        on: click
+        from: ~~.results
+        field: nid
+        path: ~~.selection
+  - type: button
+    content: "Deselect all"
+    actions:
+      - what: setData
+        on: click
+        path: ~~.selection
+        value: []
+
+data:
+  results:
+    - nid: 4
+      title: "First"
+    - nid: 9
+      title: "Second"
+  selection: []
+```
+
+## Limitations
+
+- Only a direct field of the items is read (no nested path such as `author.id`).

package/public/rjbuild/docs/core/reaction/collectField.yaml

@@ -0,0 +1,81 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: collectField
+
+      The `collectField` reaction writes the values of one field of every item of a collection, as an array. Typical use: a "select all" checkbox that writes the identifiers of the listed items.
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: from
+          after: "(string, required)"
+        details: "The collection (template syntax), an array of objects."
+      - term:
+          code: field
+          after: "(string, required)"
+        details: "The name of the field to read in each item. It is evaluated."
+      - term:
+          code: path
+          after: "(string, required)"
+        details: "The location receiving the array (template syntax)."
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - The array of the `field` values is written at `path`, in the order of the collection.
+      - The items that are not objects, and the items whose field is `null`, `undefined` or an empty string, are skipped.
+      - A collection that is not an array writes an empty array.
+      - The collection is read from the complete data, even inside a `DataFilter`.
+
+  - type: RjBuildDescriber
+    title: "Select all / deselect all"
+    description: "collectField writes every nid of the results; setData empties the selection."
+    toDescribe:
+      renderView:
+        - type: button
+          attributes:
+            type: button
+            style:
+              marginRight: "0.5rem"
+          content: "Select all"
+          actions:
+            - what: collectField
+              on: click
+              from: ~~.results
+              field: nid
+              path: ~~.selection
+        - type: button
+          attributes:
+            type: button
+          content: "Deselect all"
+          actions:
+            - what: setData
+              on: click
+              path: ~~.selection
+              value: []
+        - type: div
+          content:
+            - type: strong
+              content: "Selection: "
+            - type: Join
+              content: ~~.selection
+              separator: ", "
+      data:
+        results:
+          - nid: 4
+            title: "First"
+          - nid: 9
+            title: "Second"
+          - nid: 15
+            title: "Third"
+        selection: []
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - Only a direct field of the items is read (no nested path such as `author.id`).

package/public/rjbuild/docs/core/reaction/fetchData.md

@@ -14,7 +14,7 @@
 - `requestKey` (string, optional): Identifier used to group requests that should cancel each other. When set, firing a new request with the same key aborts the previous one client-side (via AbortController). Different keys are independent. Bypasses the global lock automatically. See [Concurrency control](#concurrency-control--requestkey) below.
 - `updateOnlyData` (boolean, optional): When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false.
 - `updateDataAtLocation` (string, optional): When `updateOnlyData` is true, specifies where to place the response data using template path syntax (e.g., "~~.userProfile", "~.config.settings"). If not specified, replaces the entire data object.
-- `url` (string, required): The URL to call (must be a static string, dynamic URLs are not supported)
+- `url` (string or array, required): The URL to call: a string or a template reference (`~~.endpoint`), or an array of segments built like the `src` of `additionalDataSource` (literal strings, references evaluated in the current template context, `{segment, required}`, `{param, value, required}`). No request is sent when the URL is empty, or when a required segment is empty. See [Dynamic URLs with `src` as Array](../../getting-started/rjbuild-structure.md#dynamic-urls-with-src-as-array).
 
 ## Behavior
 - Supports configurable HTTP methods (GET by default for backward compatibility)
@@ -232,6 +232,26 @@ actions:
     refreshAppOnResponse: false
 ```
 
+### URL built from the data
+
+```yaml
+- type: button
+  content: "Load"
+  actions:
+    - what: fetchData
+      on: click
+      url:
+        - "/api/items/"
+        - segment: ~.id
+          required: true
+        - param: display
+          value: ~~.display
+      updateOnlyData: true
+      updateDataAtLocation: ~~.details
+```
+
+Inside a `Switch` item, `~.id` reads the item: each button loads its own item. Nothing is fetched when the item has no `id`.
+
 ## Limitations
 - Only one request can be active at a time
 - Response must be a valid rjbuild **only** if refreshAppOnResponse is true and updateOnlyData is false

package/public/rjbuild/docs/core/reaction/fetchData.yaml

@@ -52,10 +52,10 @@ renderView:
           content: "When true and `refreshAppOnResponse` is true, only updates the data section instead of replacing the entire RjBuild. Preserves templates and renderView. Default: false"
       - term:
           code: url
-          after: "(string, required)"
+          after: "(string or array, required)"
         details:
           type: Markdown
-          content: "The URL to call (must be a static string, dynamic URLs are not supported)"
+          content: "The URL to call: a string or a template reference (`~~.endpoint`), or an array of segments built like the `src` of `additionalDataSource` (literal strings, references evaluated in the current template context, `{segment, required}`, `{param, value, required}`). No request is sent when the URL is empty, or when a required segment is empty."
 
   - type: Markdown
     content: |

package/public/rjbuild/docs/core/reaction/index.md

@@ -11,6 +11,10 @@ Reactions in Reactive-JSON allow you to respond to user events and perform opera
 - **[addData](./addData.md)**: Adds new data to the specified path
 - **[removeData](./removeData.md)**: Removes data from the specified path
 - **[moveData](./moveData.md)**: Moves data from one path to another
+- **[toggleData](./toggleData.md)**: Adds a value to an array when absent, removes it when present
+- **[collectField](./collectField.md)**: Writes the values of a field of every item of a collection as an array
+- **[joinData](./joinData.md)**: Writes a string built from several parts (literals, references, segments)
+- **[stringifyData](./stringifyData.md)**: Writes the JSON representation of a value
 
 ### Network Operations
 - **[fetchData](./fetchData.md)**: Fetches data from a URL using GET requests
@@ -21,4 +25,5 @@ Reactions in Reactive-JSON allow you to respond to user events and perform opera
 - **[redirectNow](./redirectNow.md)**: Performs an immediate redirect
 - **[triggerEvent](./triggerEvent.md)**: Triggers a custom event
 - **[postMessage](./postMessage.md)**: Sends a message to another window/frame
+- **[printPage](./printPage.md)**: Opens the print dialog of the browser
 

package/public/rjbuild/docs/core/reaction/index.yaml

@@ -14,6 +14,10 @@ renderView:
       - **[addData](./addData)**: Adds new data to the specified path
       - **[removeData](./removeData)**: Removes data from the specified path
       - **[moveData](./moveData)**: Moves data from one path to another
+      - **[toggleData](./toggleData)**: Adds a value to an array when absent, removes it when present
+      - **[collectField](./collectField)**: Writes the values of a field of every item of a collection as an array
+      - **[joinData](./joinData)**: Writes a string built from several parts (literals, references, segments)
+      - **[stringifyData](./stringifyData)**: Writes the JSON representation of a value
 
       ### Network Operations
       - **[fetchData](./fetchData)**: Fetches data from a URL using GET requests
@@ -24,3 +28,4 @@ renderView:
       - **[redirectNow](./redirectNow)**: Performs an immediate redirect
       - **[triggerEvent](./triggerEvent)**: Triggers a custom event
       - **[postMessage](./postMessage)**: Sends a message to another window/frame
+      - **[printPage](./printPage)**: Opens the print dialog of the browser