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

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"`.
 
 ## 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"`.
 
       ## 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).

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

@@ -7,7 +7,7 @@
 - The response can refresh the app (default) or be ignored.
 
 ## Properties
-- `url` (string, required): The destination URL for the request
+- `url` (string or array, required): The destination URL for the request: a string or a template reference, or an array of segments built like the `src` of `additionalDataSource` (references evaluated in the current template context). 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).
 - `httpMethod` (string, optional): The HTTP method to use (default: "post")
 - `data` (object, optional): The data to send. If not specified, data is sent in an object with the structure `{ data: globalDataContext.templateData }`. If `__state` exists in the context, it is automatically added.
 - `refreshAppOnResponse` (boolean, optional): If true (default), reloads the application with the server response. If false, the response is ignored and **no change is made to the application's state or display** (just like `fetchData`).

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

@@ -15,8 +15,10 @@ renderView:
     content:
       - term:
           code: url
-          after: "(string, required)"
-        details: "The destination URL for the request"
+          after: "(string or array, required)"
+        details:
+          type: Markdown
+          content: "The destination URL for the request: a string or a template reference, or an array of segments built like the `src` of `additionalDataSource` (references evaluated in the current template context). No request is sent when the URL is empty, or when a required segment is empty."
       - term:
           code: httpMethod
           after: "(string, optional)"

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

@@ -0,0 +1,72 @@
+# Reaction: toggleData
+
+The `toggleData` reaction adds a value to an array when it is absent, and removes it when it is present. The other values of the array are kept. It is the building block of on/off filters and of data-driven selections (tags, recipients, checked rows).
+
+## Properties
+
+- `path` (string, required): The location of the array (template syntax).
+- `value` (any, required): The value to add or remove. It is evaluated, so it can be a literal or a template reference.
+
+## Behavior
+
+- The value is appended when it is absent from the array, and removed when it is present. The order of the other values is kept.
+- A missing location, or a location that does not hold an array, counts as an empty array: the result is always an array.
+- The values are compared as strings: a numeric identifier (`12`) matches its text form (`"12"`).
+- Nothing happens when the value is `null`, `undefined` or an empty string, such as a value coming from a data source that is not loaded yet. The array never receives an empty value.
+- The current array is read from the complete data, even inside a `DataFilter`.
+
+## Examples
+
+### Filter toggle
+
+```yaml
+renderView:
+  - type: button
+    content: "My tasks"
+    actions:
+      - what: toggleData
+        on: click
+        path: ~~.filters.assignee
+        value: ~~.currentUser.id
+
+data:
+  currentUser:
+    id: 12
+  filters:
+    assignee: []
+```
+
+### One toggle per list item
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~~.rows
+    singleOption:
+      load: row
+
+templates:
+  row:
+    type: button
+    content: ~.title
+    actions:
+      - what: toggleData
+        on: click
+        path: ~~.selection
+        value: ~.id
+
+data:
+  rows:
+    - id: 1
+      title: "First"
+    - id: 2
+      title: "Second"
+  selection: []
+```
+
+To show the state of each item, use `attributeTransforms` with a `contains` condition on the array (see [CheckBoxField](../element/form/CheckBoxField.md#data-driven-checkbox-lists)).
+
+## Limitations
+
+- Only arrays of scalar values are supported: objects are compared by their string form.
+- `addData` appends without checking duplicates, and `removeData` removes by path: use `toggleData` to add or remove a known value.

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

@@ -0,0 +1,77 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reaction: toggleData
+
+      The `toggleData` reaction adds a value to an array when it is absent, and removes it when it is present. The other values of the array are kept. It is the building block of on/off filters and of data-driven selections (tags, recipients, checked rows).
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: path
+          after: "(string, required)"
+        details: "The location of the array (template syntax)."
+      - term:
+          code: value
+          after: "(any, required)"
+        details: "The value to add or remove. It is evaluated, so it can be a literal or a template reference."
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - The value is appended when it is absent from the array, and removed when it is present. The order of the other values is kept.
+      - A missing location, or a location that does not hold an array, counts as an empty array: the result is always an array.
+      - The values are compared as strings: a numeric identifier (`12`) matches its text form (`"12"`).
+      - Nothing happens when the value is `null`, `undefined` or an empty string, such as a value coming from a data source that is not loaded yet. The array never receives an empty value.
+      - The current array is read from the complete data, even inside a `DataFilter`.
+
+  - type: RjBuildDescriber
+    title: "One toggle per list item"
+    description: "Each button adds or removes the id of its item in the selection."
+    toDescribe:
+      renderView:
+        - type: Switch
+          content: ~~.rows
+          singleOption:
+            load: row
+        - type: div
+          content:
+            - type: strong
+              content: "Selection: "
+            - type: Join
+              content: ~~.selection
+              separator: ", "
+      templates:
+        row:
+          type: button
+          attributes:
+            type: button
+            style:
+              marginRight: "0.5rem"
+          content: ~.title
+          actions:
+            - what: toggleData
+              on: click
+              path: ~~.selection
+              value: ~.id
+      data:
+        rows:
+          - id: 1
+            title: "First"
+          - id: 2
+            title: "Second"
+          - id: 3
+            title: "Third"
+        selection: []
+
+  - type: Markdown
+    content: |
+      To show the state of each item, use `attributeTransforms` with a `contains` condition on the array (see [CheckBoxField](../element/form/CheckBoxField)).
+
+      ## Limitations
+
+      - Only arrays of scalar values are supported: objects are compared by their string form.
+      - `addData` appends without checking duplicates, and `removeData` removes by path: use `toggleData` to add or remove a known value.

package/public/rjbuild/docs/docs-components/Mermaid.yaml

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