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

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

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

@@ -0,0 +1,51 @@
+# Reaction: joinData
+
+The `joinData` reaction writes a string built from several parts at a location: a URL that depends on the data, a label, a key. YAML has no string concatenation; `joinData` fills this gap.
+
+## Properties
+
+- `path` (string, required): The location receiving the string (template syntax).
+- `parts` (array, required): The parts of the string, in the format of the `src` of `additionalDataSource` (see [Dynamic URLs with `src` as Array](../../getting-started/rjbuild-structure.md#dynamic-urls-with-src-as-array)):
+  - a literal string;
+  - a template reference (`~.slug`, `~~.id`, `~>item.id`), evaluated in the current template context;
+  - `{segment, required}`: a reference used as a path part;
+  - `{param, value, required}`: a query parameter, appended after the path (`?key=value`, or `&key=value` when the path already has a query string).
+
+## Behavior
+
+- An empty reference adds an empty string.
+- An empty `required` segment or parameter cancels the write: the location keeps its value. Mark the parts that must never be missing as required, to avoid writing a truncated URL.
+- A non-required parameter whose key or value is empty is omitted.
+
+## Example
+
+### Build the URL of the chosen entity, then submit to it
+
+```yaml
+renderView:
+  - type: button
+    content: "Link"
+    actions:
+      - what: joinData
+        on: click
+        path: ~~.saveUrl
+        parts:
+          - "/api/save?bundle=company&id="
+          - segment: ~~.selectedId
+            required: true
+      - what: submitData
+        on: click
+        url: ~~.saveUrl
+        data:
+          parent: ~~.parentId
+
+data:
+  selectedId: 42
+  parentId: 7
+```
+
+`fetchData`, `submitData` and `redirectNow` also accept the parts directly in `url` / `to`, and URL attributes (`href`, `src`...) accept them too: use `joinData` when the composed string must be stored, or shown.
+
+## Limitations
+
+- The parts are joined as they are: path parts are not URL-encoded (only parameters are).

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

@@ -0,0 +1,87 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: joinData
+
+      The `joinData` reaction writes a string built from several parts at a location: a URL that depends on the data, a label, a key. YAML has no string concatenation; `joinData` fills this gap.
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: path
+          after: "(string, required)"
+        details: "The location receiving the string (template syntax)."
+      - term:
+          code: parts
+          after: "(array, required)"
+        details:
+          type: Markdown
+          content: |
+            The parts of the string, in the format of the `src` of `additionalDataSource` (see *Dynamic URLs with `src` as Array* in [RjBuild structure](../../getting-started/rjbuild-structure)):
+            - a literal string;
+            - a template reference (`~.slug`, `~~.id`, `~>item.id`), evaluated in the current template context;
+            - `{segment, required}`: a reference used as a path part;
+            - `{param, value, required}`: a query parameter, appended after the path (`?key=value`, or `&key=value` when the path already has a query string).
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - An empty reference adds an empty string.
+      - An empty `required` segment or parameter cancels the write: the location keeps its value. Mark the parts that must never be missing as required, to avoid writing a truncated URL.
+      - A non-required parameter whose key or value is empty is omitted.
+
+  - type: RjBuildDescriber
+    title: "Compose a URL per item"
+    description: "Each button writes the URL of its item; the required segment prevents a truncated URL."
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~~.articles
+          singleOption:
+            load: article
+        - type: div
+          content:
+            - type: strong
+              content: "URL: "
+            - type: code
+              content: ~~.url
+      templates:
+        article:
+          type: button
+          attributes:
+            type: button
+            style:
+              marginRight: "0.5rem"
+          content: ~.title
+          actions:
+            - what: joinData
+              on: click
+              path: ~~.url
+              parts:
+                - "/article/"
+                - ~.year
+                - "/"
+                - segment: ~.slug
+                  required: true
+                - param: lang
+                  value: ~~.lang
+      data:
+        lang: "fr"
+        url: ""
+        articles:
+          - title: "With a slug"
+            year: 2026
+            slug: "hello"
+          - title: "Without a slug"
+            year: 2025
+
+  - type: Markdown
+    content: |
+      `fetchData`, `submitData` and `redirectNow` also accept the parts directly in `url` / `to`, and URL attributes (`href`, `src`...) accept them too: use `joinData` when the composed string must be stored, or shown.
+
+      ## Limitations
+
+      - The parts are joined as they are: path parts are not URL-encoded (only parameters are).

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

@@ -0,0 +1,22 @@
+# Reaction: printPage
+
+The `printPage` reaction opens the print dialog of the browser for the current page (`window.print()`).
+
+## Properties
+
+This reaction has no specific property.
+
+## Example
+
+```yaml
+renderView:
+  - type: button
+    content: "Print"
+    actions:
+      - what: printPage
+        on: click
+```
+
+## Limitations
+
+- The whole page is printed: use print CSS (`@media print`) to hide the parts that must not be printed.

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

@@ -0,0 +1,29 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: printPage
+
+      The `printPage` reaction opens the print dialog of the browser for the current page (`window.print()`).
+
+      ## Properties
+
+      This reaction has no specific property.
+
+  - type: RjBuildDescriber
+    title: "Print button"
+    description: "Clicking the button opens the print dialog."
+    toDescribe:
+      renderView:
+        - type: button
+          attributes:
+            type: button
+          content: "Print"
+          actions:
+            - what: printPage
+              on: click
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - The whole page is printed: use print CSS (`@media print`) to hide the parts that must not be printed.

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

@@ -4,12 +4,14 @@ The `redirectNow` reaction performs an immediate browser redirection to a specif
 
 ## Properties
 
-- `to` (string, required): The URL to redirect to. This value is evaluated, so it can be a static URL or dynamically constructed from data.
+- `to` (string or array, required): The URL to redirect to: a string or a template reference, 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}`). See [Dynamic URLs with `src` as Array](../../getting-started/rjbuild-structure.md#dynamic-urls-with-src-as-array).
+- `replace` (boolean, optional): When `true`, the current history entry is replaced instead of adding a new one (the back button does not come back to the current page). Default: `false`.
 
 ## Behavior
 
 - When triggered, the reaction evaluates the `to` property to get the target URL.
-- It then sets `window.location.href` to the resulting URL, causing the browser to navigate to the new page.
+- It then sets `window.location.href` to the resulting URL (or calls `window.location.replace()` with `replace: true`), causing the browser to navigate to the new page.
+- Nothing happens when the URL is empty, or when a required segment is empty: the user is never sent to a truncated URL.
 
 ## Example
 
@@ -27,6 +29,22 @@ renderView:
         to: "https://github.com/reactive-json/reactive-json"
 ```
 
+### Redirecting to a URL built from a response
+
+After a creation, the URL of the new item is only known from the response:
+
+```yaml
+- what: redirectNow
+  on: response
+  replace: true
+  to:
+    - "/dashboards/"
+    - segment: "<reactive-json:event-new-value>.id"
+      required: true
+    - param: edit
+      value: "1"
+```
+
 ## Limitations
 
 - The `to` property must resolve to a valid URL string for the redirection to work.

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

@@ -11,17 +11,38 @@ renderView:
     content:
       - term:
           code: to
-          after: "(string, required)"
+          after: "(string or array, required)"
         details:
           type: Markdown
-          content: "The URL to redirect to. This value is evaluated, so it can be a static URL or dynamically constructed from data"
+          content: "The URL to redirect to: a string or a template reference, 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}`). See *Dynamic URLs with `src` as Array* in [RjBuild structure](../../getting-started/rjbuild-structure)."
+      - term:
+          code: replace
+          after: "(boolean, optional)"
+        details: "When true, the current history entry is replaced instead of adding a new one (the back button does not come back to the current page). Default: false."
 
   - type: Markdown
     content: |
       ## Behavior
 
       - When triggered, the reaction evaluates the `to` property to get the target URL.
-      - It then sets `window.location.href` to the resulting URL, causing the browser to navigate to the new page.
+      - It then sets `window.location.href` to the resulting URL (or calls `window.location.replace()` with `replace: true`), causing the browser to navigate to the new page.
+      - Nothing happens when the URL is empty, or when a required segment is empty: the user is never sent to a truncated URL.
+
+      ## URL built from a response
+
+      After a creation, the URL of the new item is only known from the response:
+
+      ```yaml
+      - what: redirectNow
+        on: response
+        replace: true
+        to:
+          - "/dashboards/"
+          - segment: "<reactive-json:event-new-value>.id"
+            required: true
+          - param: edit
+            value: "1"
+      ```
 
       ## Limitations
 

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

@@ -5,13 +5,14 @@ The `setClipboardData` reaction copies a specified value to the user's clipboard
 ## Properties
 
 - `value` (any, required): The value to be copied to the clipboard. The value is evaluated, so it can be a literal string or a path to data.
+- `statusPath` (string, optional): A location receiving `"copied"` or `"failed"` once the copy is done, so that the page can react to the outcome (show a confirmation, announce it with a notice...).
 
 ## Behavior
 
 - When triggered, the reaction evaluates the `value` property.
-- If the evaluated value is a string, it uses the `navigator.clipboard.writeText()` API to copy it to the clipboard.
-- If the evaluated value is not a string, the reaction does nothing.
-- An error is logged to the console if the clipboard operation fails (e.g., due to browser permissions).
+- A string or a number is copied with the `navigator.clipboard.writeText()` API. Other values (objects, arrays) and empty values are ignored.
+- Outside a secure context (plain http on a host other than `localhost`), where the Clipboard API is not available, or when it fails, the copy falls back to the deprecated `copy` command on a temporary text field.
+- An error is logged to the console if the copy fails, and `statusPath` receives `"failed"`. A value that cannot be copied (empty, object, array) also reports `"failed"`.
 
 ## Example
 
@@ -22,7 +23,7 @@ This example shows a button that, when clicked, copies the value of `~.shareable
 ```yaml
 renderView:
   - type: div
-    content: "Your code: ~.shareable_code"
+    content: ["Your code: ", ~.shareable_code]
   - type: button
     content: "Copy Code"
     actions:
@@ -33,8 +34,36 @@ data:
   shareable_code: "ABC-123-XYZ"
 ```
 
+### Showing the outcome
+
+```yaml
+renderView:
+  - type: button
+    content: "Copy the key"
+    actions:
+      - what: setClipboardData
+        on: click
+        value: ~~.apiKey
+        statusPath: ~~.copyStatus
+  - type: span
+    content: "Copied"
+    actions:
+      - what: hide
+        when: ~~.copyStatus
+        isNot: "copied"
+  - type: span
+    content: "The copy failed: select the key and copy it manually."
+    actions:
+      - what: hide
+        when: ~~.copyStatus
+        isNot: "failed"
+
+data:
+  apiKey: "ABC-123-XYZ"
+  copyStatus: ""
+```
+
 ## Limitations
 
-- This reaction relies on the Clipboard API, which requires a secure context (HTTPS) to function in most modern browsers.
 - The user may be prompted for permission to access the clipboard, depending on browser settings.
-- The reaction only supports copying string values. Numbers and other types will be converted to strings, but objects and arrays will not be copied. 
+- Only strings and numbers are copied: objects and arrays are ignored. 

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

@@ -15,21 +15,26 @@ renderView:
         details:
           type: Markdown
           content: "The value to be copied to the clipboard. The value is evaluated, so it can be a literal string or a path to data"
+      - term:
+          code: statusPath
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "A location receiving `\"copied\"` or `\"failed\"` once the copy is done, so that the page can react to the outcome."
 
   - type: Markdown
     content: |
       ## Behavior
 
       - When triggered, the reaction evaluates the `value` property.
-      - If the evaluated value is a string, it uses the `navigator.clipboard.writeText()` API to copy it to the clipboard.
-      - If the evaluated value is not a string, the reaction does nothing.
-      - An error is logged to the console if the clipboard operation fails (e.g., due to browser permissions).
+      - A string or a number is copied with the `navigator.clipboard.writeText()` API. Other values (objects, arrays) and empty values are ignored.
+      - Outside a secure context (plain http on a host other than `localhost`), where the Clipboard API is not available, or when it fails, the copy falls back to the deprecated `copy` command on a temporary text field.
+      - An error is logged to the console if the copy fails, and `statusPath` receives `"failed"`. A value that cannot be copied (empty, object, array) also reports `"failed"`.
 
       ## Limitations
 
-      - This reaction relies on the Clipboard API, which requires a secure context (HTTPS) to function in most modern browsers.
       - The user may be prompted for permission to access the clipboard, depending on browser settings.
-      - The reaction only supports copying string values. Numbers and other types will be converted to strings, but objects and arrays will not be copied.
+      - Only strings and numbers are copied: objects and arrays are ignored.
 
   - type: RjBuildDescriber
     title: "Copying text to the clipboard"
@@ -44,5 +49,12 @@ renderView:
             - what: setClipboardData
               on: click
               value: ~.shareable_code
+              statusPath: ~.copyStatus
+        - type: span
+          attributes:
+            style:
+              marginLeft: "0.5rem"
+          content: ["Status: ", ~.copyStatus]
       data:
-        shareable_code: "ABC-123-XYZ" 
+        shareable_code: "ABC-123-XYZ"
+        copyStatus: "" 

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

@@ -0,0 +1,45 @@
+# Reaction: stringifyData
+
+The `stringifyData` reaction writes the JSON representation of a value (`JSON.stringify`) at a location. Use it to send structured data (an array, an object) to an endpoint that expects a text field.
+
+## Properties
+
+- `from` (string, required): The value to serialize (template syntax).
+- `path` (string, required): The location receiving the JSON string (template syntax).
+
+## Behavior
+
+- The JSON string is written synchronously, in the order of the actions list. Placed before a `submitData` of the same event, it guarantees that the submitted data holds the fresh JSON.
+- An undefined value writes an empty string.
+- The value is read from the complete data, even inside a `DataFilter`.
+
+## Example
+
+### Save a layout as JSON
+
+```yaml
+renderView:
+  - type: button
+    content: "Save"
+    actions:
+      - what: stringifyData
+        on: click
+        from: ~~.dashboard.widgets
+        path: ~~.dashboard.payload.layout
+      - what: submitData
+        on: click
+        url: "/api/dashboard/save"
+        data:
+          layout: ~~.dashboard.payload.layout
+
+data:
+  dashboard:
+    widgets:
+      - id: "sales"
+        width: 2
+    payload: {}
+```
+
+## Limitations
+
+- The JSON is compact (no indentation).

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

@@ -0,0 +1,58 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: stringifyData
+
+      The `stringifyData` reaction writes the JSON representation of a value (`JSON.stringify`) at a location. Use it to send structured data (an array, an object) to an endpoint that expects a text field.
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: from
+          after: "(string, required)"
+        details: "The value to serialize (template syntax)."
+      - term:
+          code: path
+          after: "(string, required)"
+        details: "The location receiving the JSON string (template syntax)."
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - The JSON string is written synchronously, in the order of the actions list. Placed before a `submitData` of the same event, it guarantees that the submitted data holds the fresh JSON.
+      - An undefined value writes an empty string.
+      - The value is read from the complete data, even inside a `DataFilter`.
+
+  - type: RjBuildDescriber
+    title: "Serialize a list"
+    description: "The button writes the JSON of the widgets list in payload.layout."
+    toDescribe:
+      renderView:
+        - type: button
+          attributes:
+            type: button
+          content: "Serialize"
+          actions:
+            - what: stringifyData
+              on: click
+              from: ~~.widgets
+              path: ~~.payload.layout
+        - type: pre
+          content: ~~.payload.layout
+      data:
+        widgets:
+          - id: "sales"
+            width: 2
+          - id: "leads"
+            width: 1
+        payload:
+          layout: ""
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - The JSON is compact (no indentation).