@ea-lab/reactive-json-docs 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [

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

@@ -0,0 +1,169 @@
+# AutocompleteField
+
+The `AutocompleteField` component provides a search-as-you-type input that fetches suggestions from a remote API as the user types. It supports single and multiple value selection, and customizable dropdown and selected-item templates.
+
+## Basic Syntax
+
+```yaml
+- type: AutocompleteField
+  dataLocation: ~~.selectedId
+  placeholder: "Search…"
+  src:
+    - "/api/items"
+    - param: "search"
+      value: "<reactive-json:autocomplete-field:input>"
+    - param: "limit"
+      value: "10"
+```
+
+## Properties
+
+- `dataLocation` (string, required): Path where the selected value (or array of values in multiple mode) is stored in the data context.
+- `src` (array, required): URL segments used to build the API endpoint, using the same format as `additionalDataSource.src`. The special token `<reactive-json:autocomplete-field:input>` is replaced by the current search text at request time.
+- `placeholder` (string, optional): Placeholder text for the search input.
+- `minChars` (number, optional): Minimum number of characters required before a search is triggered. Defaults to `2`.
+- `debounce` (number, optional): Delay in milliseconds between the last keystroke and the API request. Defaults to `300`.
+- `multiple` (boolean, optional): Enable multiple selection mode. Selected values are stored as an array. Defaults to `false`.
+- `maxItems` (number, optional): Maximum number of items that can be selected in multiple mode. No limit by default.
+- `clearOnSelect` (boolean, optional): Clear the search input and close the dropdown after an item is selected. Defaults to `true`.
+- `itemTemplate` (rjbuild, optional): Template used to render each item in the dropdown. Has access to item data via `~.` (e.g., `~.label`, `~.value`). Defaults to a `div` displaying `~.label`.
+- `selectedTemplate` (rjbuild, optional): Template used to render the selected item (single mode) or each tag (multiple mode). Has access to item data via `~.`. Defaults to a `span` displaying `~.label`.
+- `defaultFieldValue` (any, optional): Default value used when no data is present at `dataLocation`.
+- `attributes` (object, optional): Attributes applied to the root container `div`. Also receives the CSS class `rj-autocomplete` automatically.
+- `actions` (array, optional): Actions to execute based on component state.
+
+## Backend Response Format
+
+The endpoint must return a JSON array of objects. Each object must have at minimum a `value` and a `label` key:
+
+```json
+[
+  { "value": 42, "label": "First result" },
+  { "value": 7,  "label": "Second result" }
+]
+```
+
+Additional keys can be included and are available in `itemTemplate` / `selectedTemplate` via `~.fieldName`.
+
+## The Input Token
+
+The string `<reactive-json:autocomplete-field:input>` is a special token that can be placed anywhere in the `src` segments (as a `value`, `param`, or URL segment). It is replaced at request time with the current text in the search field.
+
+```yaml
+src:
+  - "/api/search"
+  - param: "q"
+    value: "<reactive-json:autocomplete-field:input>"
+```
+
+## CSS Classes
+
+The component uses the following CSS classes for styling:
+
+- `.rj-autocomplete` — root container
+- `.rj-autocomplete__input` — the search text input
+- `.rj-autocomplete__dropdown` — the suggestions dropdown
+- `.rj-autocomplete__item` — each suggestion item
+- `.rj-autocomplete__item.is-selected` — a suggestion that is already selected (multiple mode)
+- `.rj-autocomplete__selected` — the selected-item area (single mode)
+- `.rj-autocomplete__clear` — the clear button (single mode)
+- `.rj-autocomplete__tag` — a selected tag (multiple mode)
+- `.rj-autocomplete__tag-remove` — the remove button on a tag
+- `.rj-autocomplete__loading` — the loading indicator
+
+## Examples
+
+### Single value selection
+
+Stores a single selected value. Shows a clear button once an item is selected.
+
+```yaml
+renderView:
+  - type: AutocompleteField
+    dataLocation: ~~.selectedId
+    placeholder: "Search…"
+    src:
+      - "/api/items"
+      - param: "search"
+        value: "<reactive-json:autocomplete-field:input>"
+      - param: "limit"
+        value: "10"
+
+data:
+  selectedId: null
+```
+
+### Multiple selection with a limit
+
+Stores up to 3 values as an array. Each selected item is displayed as a removable tag.
+
+```yaml
+renderView:
+  - type: AutocompleteField
+    dataLocation: ~~.selectedIds
+    multiple: true
+    maxItems: 3
+    placeholder: "Add items (max 3)…"
+    src:
+      - "/api/items"
+      - param: "search"
+        value: "<reactive-json:autocomplete-field:input>"
+      - param: "limit"
+        value: "10"
+  - type: p
+    content:
+      - "Selected IDs: "
+      - type: Join
+        content: ~~.selectedIds
+
+data:
+  selectedIds: []
+```
+
+### Custom templates
+
+Use `itemTemplate` and `selectedTemplate` to render richer content. Both templates have access to all fields returned by the backend via `~.`.
+
+```yaml
+- type: AutocompleteField
+  dataLocation: ~~.selectedItem
+  placeholder: "Search…"
+  src:
+    - "/api/items"
+    - param: "search"
+      value: "<reactive-json:autocomplete-field:input>"
+  itemTemplate:
+    type: div
+    content:
+      - type: strong
+        content: ~.label
+      - " (#"
+      - ~.value
+      - ")"
+  selectedTemplate:
+    type: span
+    content:
+      - ~.label
+      - " ✓"
+```
+
+### Keep search text after selection
+
+Set `clearOnSelect: false` to keep the typed text and dropdown open after selecting an item (useful in multiple mode when selecting several items quickly).
+
+```yaml
+- type: AutocompleteField
+  dataLocation: ~~.selectedIds
+  multiple: true
+  clearOnSelect: false
+  placeholder: "Search…"
+  src: [...]
+```
+
+## Limitations
+
+- Requires an external API endpoint; no built-in static options support.
+- The dropdown only renders while the user is actively typing (results are not re-fetched on re-open without re-typing).
+- In multiple mode, selected items' display data is kept in local React state and may be lost on page reload unless persisted separately.
+- Styling must be provided via external CSS targeting the `.rj-autocomplete*` classes, or via `attributes.style`.
+- No built-in keyboard navigation for the dropdown.

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

@@ -0,0 +1,225 @@
+renderView:
+  - type: Markdown
+    content: |
+      # AutocompleteField
+
+      The `AutocompleteField` component provides a search-as-you-type input that fetches suggestions from a remote API as the user types. It supports single and multiple value selection, and customizable dropdown and selected-item templates.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: AutocompleteField
+        dataLocation: ~~.selectedId
+        placeholder: "Search…"
+        src:
+          - "/api/items"
+          - param: "search"
+            value: "<reactive-json:autocomplete-field:input>"
+          - param: "limit"
+            value: "10"
+      ```
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, required)"
+        details: "Path where the selected value (or array of values in multiple mode) is stored in the data context."
+      - term:
+          code: src
+          after: "(array, required)"
+        details:
+          type: Markdown
+          content: "URL segments used to build the API endpoint. The special token `<reactive-json:autocomplete-field:input>` is replaced by the current search text at request time."
+      - term:
+          code: placeholder
+          after: "(string, optional)"
+        details: "Placeholder text for the search input."
+      - term:
+          code: minChars
+          after: "(number, optional, default: 2)"
+        details: "Minimum number of characters required before a search is triggered."
+      - term:
+          code: debounce
+          after: "(number, optional, default: 300)"
+        details: "Delay in milliseconds between the last keystroke and the API request."
+      - term:
+          code: multiple
+          after: "(boolean, optional, default: false)"
+        details: "Enable multiple selection mode. Selected values are stored as an array."
+      - term:
+          code: maxItems
+          after: "(number, optional)"
+        details: "Maximum number of items selectable in multiple mode. No limit by default."
+      - term:
+          code: clearOnSelect
+          after: "(boolean, optional, default: true)"
+        details: "Clear the search input and close the dropdown after an item is selected."
+      - term:
+          code: itemTemplate
+          after: "(rjbuild, optional)"
+        details:
+          type: Markdown
+          content: "Template rendered for each item in the dropdown. Has access to item data via `~.` (e.g., `~.label`, `~.value`). Defaults to a `div` displaying `~.label`."
+      - term:
+          code: selectedTemplate
+          after: "(rjbuild, optional)"
+        details:
+          type: Markdown
+          content: "Template rendered for the selected item (single mode) or each tag (multiple mode). Has access to item data via `~.`. Defaults to a `span` displaying `~.label`."
+      - term:
+          code: defaultFieldValue
+          after: "(any, optional)"
+        details: "Default value used when no data is present at dataLocation."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details:
+          type: Markdown
+          content: "Attributes applied to the root container `div`. Also receives the CSS class `rj-autocomplete` automatically."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on component state."
+
+  - type: Markdown
+    content: |
+      ## Backend Response Format
+
+      The endpoint must return a JSON array of objects. Each object must have at minimum a `value` and a `label` key:
+
+      ```json
+      [
+        { "value": 42, "label": "First result" },
+        { "value": 7,  "label": "Second result" }
+      ]
+      ```
+
+      Additional keys can be included and are available in `itemTemplate` / `selectedTemplate` via `~.fieldName`.
+
+  - type: Markdown
+    content: |
+      ## The Input Token
+
+      The string `<reactive-json:autocomplete-field:input>` is a special token that can be placed anywhere in the `src` segments. It is replaced at request time with the current text in the search field.
+
+      ```yaml
+      src:
+        - "/api/search"
+        - param: "q"
+          value: "<reactive-json:autocomplete-field:input>"
+      ```
+
+  - type: Markdown
+    content: |
+      ## CSS Classes
+
+      The component uses the following CSS classes for styling:
+
+      | Class | Element |
+      |---|---|
+      | `.rj-autocomplete` | Root container |
+      | `.rj-autocomplete__input` | The search text input |
+      | `.rj-autocomplete__dropdown` | The suggestions dropdown |
+      | `.rj-autocomplete__item` | Each suggestion item |
+      | `.rj-autocomplete__item.is-selected` | A suggestion already selected (multiple mode) |
+      | `.rj-autocomplete__selected` | The selected-item area (single mode) |
+      | `.rj-autocomplete__clear` | The clear button (single mode) |
+      | `.rj-autocomplete__tag` | A selected tag (multiple mode) |
+      | `.rj-autocomplete__tag-remove` | The remove button on a tag |
+      | `.rj-autocomplete__loading` | The loading indicator |
+
+  - type: Markdown
+    content: |
+      ## Examples
+
+      > **Note**: The following examples require a live API endpoint. They show the YAML configuration without a live demo.
+
+      ### Single value selection
+
+      Stores a single selected value. Shows a clear button once an item is selected.
+
+      ```yaml
+      renderView:
+        - type: AutocompleteField
+          dataLocation: ~~.selectedId
+          placeholder: "Search…"
+          src:
+            - "/api/items"
+            - param: "search"
+              value: "<reactive-json:autocomplete-field:input>"
+            - param: "limit"
+              value: "10"
+
+      data:
+        selectedId: null
+      ```
+
+      ### Multiple selection with a limit
+
+      Stores up to 3 values as an array. Each selected item is displayed as a removable tag.
+
+      ```yaml
+      renderView:
+        - type: AutocompleteField
+          dataLocation: ~~.selectedIds
+          multiple: true
+          maxItems: 3
+          placeholder: "Add items (max 3)…"
+          src:
+            - "/api/items"
+            - param: "search"
+              value: "<reactive-json:autocomplete-field:input>"
+            - param: "limit"
+              value: "10"
+        - type: p
+          content:
+            - "Selected IDs: "
+            - type: Join
+              content: ~~.selectedIds
+
+      data:
+        selectedIds: []
+      ```
+
+      ### Custom templates
+
+      Use `itemTemplate` and `selectedTemplate` to render richer content. Both templates have access to all fields returned by the backend via `~.`.
+
+      ```yaml
+      - type: AutocompleteField
+        dataLocation: ~~.selectedItem
+        placeholder: "Search…"
+        src:
+          - "/api/items"
+          - param: "search"
+            value: "<reactive-json:autocomplete-field:input>"
+        itemTemplate:
+          type: div
+          content:
+            - type: strong
+              content: ~.label
+            - " (#"
+            - ~.value
+            - ")"
+        selectedTemplate:
+          type: span
+          content:
+            - ~.label
+            - " ✓"
+      ```
+
+      ## Limitations
+
+      - Requires an external API endpoint; no built-in static options support.
+      - The dropdown only renders while the user is actively typing (results are not re-fetched on re-open without re-typing).
+      - In multiple mode, selected items' display data is kept in local React state and may be lost on page reload unless persisted separately.
+      - Styling must be provided via external CSS targeting the `.rj-autocomplete*` classes, or via `attributes.style`.
+      - No built-in keyboard navigation for the dropdown.
+
+templates: {}
+data: {}

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

@@ -0,0 +1,108 @@
+# Join
+
+The `Join` component concatenates an array of values into a single string, with a configurable separator. It is useful for displaying lists of scalar values (IDs, labels, tags, etc.) inline.
+
+## Basic Syntax
+
+```yaml
+- type: Join
+  content: ~~.myArray
+  separator: ", "
+```
+
+## Properties
+
+- `content` (array, required): The array to join. Supports template references such as `~~.myArray` or `~.items`. Non-array values are coerced to string and displayed as-is.
+- `separator` (string, optional): The string used between each element. Defaults to `", "`.
+- `attributes` (object, optional): Additional attributes for the root element.
+- `actions` (array, optional): Actions to execute based on component state.
+
+## Examples
+
+### Basic join with default separator
+
+```yaml
+renderView:
+  - type: Join
+    content: ~~.tags
+
+data:
+  tags:
+    - "react"
+    - "yaml"
+    - "json"
+```
+
+Renders: `react, yaml, json`
+
+### Custom separator
+
+```yaml
+renderView:
+  - type: Join
+    content: ~~.ids
+    separator: " | "
+
+data:
+  ids:
+    - 1
+    - 2
+    - 3
+```
+
+Renders: `1 | 2 | 3`
+
+### Used inside a sentence
+
+```yaml
+renderView:
+  - type: p
+    content:
+      - "Selected items: "
+      - type: Join
+        content: ~~.selectedIds
+        separator: ", "
+
+data:
+  selectedIds:
+    - 42
+    - 7
+    - 15
+```
+
+### With template-scoped data
+
+```yaml
+renderView:
+  - type: Switch
+    content: ~~.users
+    singleOption:
+      load: userRow
+
+templates:
+  userRow:
+    type: div
+    content:
+      - "Roles: "
+      - type: Join
+        content: ~.roles
+        separator: " / "
+
+data:
+  users:
+    - name: "Alice"
+      roles: ["admin", "editor"]
+    - name: "Bob"
+      roles: ["viewer"]
+```
+
+## Notes
+
+- If `content` evaluates to a non-array value, it is rendered as a plain string (no separator applied).
+- Null or undefined `content` renders nothing.
+- Array elements are joined using JavaScript's native `.join()`, so objects will render as `[object Object]`. Use this component with arrays of primitives (strings, numbers).
+
+## Limitations
+
+- No support for rendering rich content (HTML, components) between items — use `Switch` with a template for that.
+- No per-item formatting; all elements are joined as plain strings.

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

@@ -0,0 +1,113 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Join
+
+      The `Join` component concatenates an array of values into a single string, with a configurable separator. It is useful for displaying lists of scalar values (IDs, labels, tags, etc.) inline.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: Join
+        content: ~~.myArray
+        separator: ", "
+      ```
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: content
+          after: "(array, required)"
+        details: "The array to join. Supports template references such as ~~.myArray or ~.items. Non-array values are coerced to string and displayed as-is."
+      - term:
+          code: separator
+          after: '(string, optional, default: ", ")'
+        details: "The string used between each element."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Additional attributes for the root element."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on component state."
+
+  - type: RjBuildDescriber
+    title: "Basic join with default separator"
+    description: "Join an array of strings with the default comma-space separator."
+    toDescribe:
+      renderView:
+        - type: p
+          content:
+            - "Tags: "
+            - type: Join
+              content: ~~.tags
+      data:
+        tags:
+          - "react"
+          - "yaml"
+          - "json"
+
+  - type: RjBuildDescriber
+    title: "Custom separator"
+    description: "Use a pipe separator to display a list of IDs."
+    toDescribe:
+      renderView:
+        - type: p
+          content:
+            - "IDs: "
+            - type: Join
+              content: ~~.ids
+              separator: " | "
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Raw array: "
+            - type: Code
+              content: ~~.ids
+      data:
+        ids:
+          - 42
+          - 7
+          - 15
+
+  - type: RjBuildDescriber
+    title: "Inside a sentence"
+    description: "Embed a Join inside a paragraph to display selected values inline."
+    toDescribe:
+      renderView:
+        - type: p
+          content:
+            - "Selected items: "
+            - type: strong
+              content:
+                type: Join
+                content: ~~.selectedIds
+                separator: ", "
+      data:
+        selectedIds:
+          - 42
+          - 7
+          - 15
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - If `content` evaluates to a non-array value, it is rendered as a plain string (no separator applied).
+      - Null or undefined `content` renders nothing.
+      - Array elements are joined using JavaScript's native `.join()`, so objects will render as `[object Object]`. Use this component with arrays of primitives (strings, numbers).
+
+      ## Limitations
+
+      - No support for rendering rich content (HTML, components) between items — use `Switch` with a template for that.
+      - No per-item formatting; all elements are joined as plain strings.
+
+templates: {}
+data: {}

package/public/rjbuild/docs/core/element/special/Switch.md

@@ -257,4 +257,106 @@ data:
     - name: "string2"
     - name: "string3"
 ```
+
+## Caveats — common pitfalls that fail silently
+
+These two patterns *look* correct, type-check, throw no error, and produce
+empty output. They're easy to miss and have cost real debugging time.
+
+### Caveat 1 — `content` must be a template reference, not an inline array
+
+Switch iterates whatever you put in `content`, but the per-item template
+context (i.e. what `~.field` resolves against) is fetched from the **reactive
+data store** at the iterated path. An inline array literal in `content` is
+never written to the store, so each iteration's `templateData` ends up
+`undefined` and every `~.field` resolves to nothing.
+
+```yaml
+# ❌ Silent failure — items render but ~.label is undefined
+renderView:
+  - type: Switch
+    content:
+      - {label: "Home"}
+      - {label: "About"}
+    singleOption:
+      load: navLink
+
+templates:
+  navLink:
+    type: a
+    content: ~.label
+```
+
+```yaml
+# ✅ Works — content points into the store
+data:
+  navItems:
+    - {label: "Home"}
+    - {label: "About"}
+
+renderView:
+  - type: Switch
+    content: ~~.navItems
+    singleOption:
+      load: navLink
+
+templates:
+  navLink:
+    type: a
+    content: ~.label
+```
+
+**Rule of thumb:** `Switch.content` is always a path reference (`~~.foo` for
+global, `~.foo` for local), never a literal. If your iteration data is
+"constant" from a page-data perspective, that's fine — just put it in the
+YAML's `data:` section. It will still be reachable via `~~.foo`.
+
+### Caveat 2 — `singleOption` must use `load:`, not an inline template
+
+The per-item `TemplateContext` that makes `~.field` resolve against the
+current item is set up by the `load` branch of the `View` engine. Writing
+`singleOption` as an inline `{type: ..., content: ...}` skips that setup —
+the iteration happens, but `~.field` inside the inline template resolves
+against the **outer** context (whatever was active where the Switch sits),
+not the per-item context.
+
+```yaml
+# ❌ ~.name resolves against the outer context, not each user
+renderView:
+  - type: Switch
+    content: ~~.users
+    singleOption:
+      type: div
+      content: ~.name
+```
+
+```yaml
+# ✅ Per-item context is correctly pushed
+renderView:
+  - type: Switch
+    content: ~~.users
+    singleOption:
+      load: userCard
+
+templates:
+  userCard:
+    type: div
+    content: ~.name
+```
+
+**Rule of thumb:** treat `singleOption` and `options.<key>` as
+`{load: <templateName>}` only. If you find yourself writing an inline
+template there, factor it into `templates:` and reference it.
+
+### Debugging checklist when an iteration renders empty
+
+1. Is `Switch.content` a `~~.path` (not an inline literal)?
+2. Does that path exist in the store? (Defaults in `data:` are merged in
+   unless the parent mounts with a `dataOverride` that omits the field.)
+3. Is `singleOption` / `options.<key>` a `{load: <name>}`?
+4. Is each item in the data an object (not a primitive)? Switch silently
+   skips non-object entries.
+5. Is the `usePagination` hook available? Switch returns `null` if not —
+   normally guaranteed by `ReactiveJsonRoot` auto-merging
+   `coreComponentsPlugin`, but worth checking on a stripped-down root.
  

package/public/rjbuild/docs/core/element/special/Switch.yaml

@@ -118,12 +118,109 @@ renderView:
 
       # ✅ This will work:
       data:
-        items: 
+        items:
           - name: "string1"
           - name: "string2"
           - name: "string3"
       ```
 
+      ## Caveats — common pitfalls that fail silently
+
+      Two patterns *look* correct, throw no error, and produce empty output.
+      They've cost real debugging time.
+
+      ### Caveat 1 — `content` must be a template reference, not an inline array
+
+      Switch iterates whatever you put in `content`, but the per-item
+      template context is fetched from the **reactive data store** at the
+      iterated path. An inline array literal in `content` is never written
+      to the store, so each iteration's `templateData` ends up `undefined`
+      and every `~.field` resolves to nothing.
+
+      ```yaml
+      # ❌ Silent failure — items render but ~.label is undefined
+      renderView:
+        - type: Switch
+          content:
+            - {label: "Home"}
+            - {label: "About"}
+          singleOption:
+            load: navLink
+      templates:
+        navLink:
+          type: a
+          content: ~.label
+      ```
+
+      ```yaml
+      # ✅ Works — content points into the store
+      data:
+        navItems:
+          - {label: "Home"}
+          - {label: "About"}
+      renderView:
+        - type: Switch
+          content: ~~.navItems
+          singleOption:
+            load: navLink
+      templates:
+        navLink:
+          type: a
+          content: ~.label
+      ```
+
+      **Rule of thumb:** `Switch.content` is always a path reference
+      (`~~.foo` for global, `~.foo` for local), never a literal. Constant
+      iteration data belongs in the YAML's `data:` section.
+
+      ### Caveat 2 — `singleOption` must use `load:`, not an inline template
+
+      The per-item TemplateContext that makes `~.field` resolve against the
+      current item is set up by the `load` branch of the View engine.
+      Writing `singleOption` as an inline `{type: ..., content: ...}` skips
+      that setup — the iteration happens, but `~.field` resolves against
+      the **outer** context, not the per-item context.
+
+      ```yaml
+      # ❌ ~.name resolves against the outer context
+      renderView:
+        - type: Switch
+          content: ~~.users
+          singleOption:
+            type: div
+            content: ~.name
+      ```
+
+      ```yaml
+      # ✅ Per-item context is correctly pushed
+      renderView:
+        - type: Switch
+          content: ~~.users
+          singleOption:
+            load: userCard
+      templates:
+        userCard:
+          type: div
+          content: ~.name
+      ```
+
+      **Rule of thumb:** treat `singleOption` and `options.<key>` as
+      `{load: <templateName>}` only. Factor inline templates into
+      `templates:`.
+
+      ### Debugging checklist when an iteration renders empty
+
+      1. Is `Switch.content` a `~~.path` (not an inline literal)?
+      2. Does that path exist in the store? (Defaults in `data:` are merged
+         in unless the parent mounts with a `dataOverride` that omits the
+         field.)
+      3. Is `singleOption` / `options.<key>` a `{load: <name>}`?
+      4. Is each item in the data an object (not a primitive)? Switch
+         silently skips non-object entries.
+      5. Is the `usePagination` hook available? Switch returns `null` if
+         not — normally guaranteed by `ReactiveJsonRoot` auto-merging
+         `coreComponentsPlugin`.
+
   - type: RjBuildDescriber
     title: "Simple usage with `singleOption` (no pagination)"
     description: |

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

@@ -10,6 +10,8 @@
 ## Properties
 - `httpMethod` (string, optional): The HTTP method to use (default: "get"). Supports: get, post, put, patch, delete, etc.
 - `refreshAppOnResponse` (boolean, optional): If true (default), the response will update the application. If false, the response is ignored (webhook mode).
+- `allowConcurrent` (boolean, optional): When true, allows concurrent requests (bypasses the global lock). Default: false. Implicitly true when `requestKey` is set.
+- `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)
@@ -54,6 +56,40 @@ The response event provides access to the complete server response through `<rea
 
 > **⚠️ Important:** When using `updateOnlyData: true`, the server response must contain **data only**, not a complete RjBuild structure. The response should be the raw data object, not wrapped in `{data: {...}, renderView: [...], templates: {...}}`.
 
+## Concurrency control — `requestKey`
+
+By default, `fetchData` and `submitData` share a **global lock** at the document level: only one HTTP request can be active across the whole app at any time. A second call fired while the first is in flight is **silently dropped**. This is safe for most cases but bites when a user clicks rapidly through buckets in a filter UI, or hits two save buttons quickly — the second request's siblings (e.g. `setData` updating local UI state) still run, but the request itself never goes out, leaving UI and data out of sync.
+
+`requestKey` opts the call into per-key cancel-on-new semantics. The library keeps a registry of in-flight requests keyed by `requestKey` and, on each new call:
+
+1. Aborts the previous request with the same key (via `AbortController` on the underlying axios call).
+2. Replaces the registry entry with the new request.
+3. Lets the new request proceed.
+
+Aborted requests are silently swallowed: their `.catch` doesn't log an error, and their `.finally` skips the `response` event dispatch. The successor will fire its own `response` event normally.
+
+```yaml
+# Rapid clicks on bucket A then B share `facet-refresh` — A's request
+# is aborted as soon as B is fired, so only B's response lands in the
+# store. Without requestKey, B would silently no-op (global lock held
+# by A) and the UI would diverge from the data.
+actions:
+  - what: setData
+    on: click
+    path: ~~.selectedFilter
+    value: ~.key
+  - what: fetchData
+    on: click
+    requestKey: facet-refresh
+    url: ~~.endpoint
+    updateOnlyData: true
+    updateDataAtLocation: ~~.result
+```
+
+Different keys are independent: edit modals on multiple rows can each have their own `requestKey: 'save-row-42'` etc. and save simultaneously without interfering.
+
+`requestKey` implies `allowConcurrent: true` — the global lock is bypassed automatically when a key is provided, since per-key cancel-on-new already guarantees single-flight within the key.
+
 ## Examples
 
 ### Data Loading with GET (Default)

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

@@ -26,6 +26,18 @@ renderView:
         details:
           type: Markdown
           content: "If true (default), the response will update the application. If false, the response is ignored (webhook mode)"
+      - term:
+          code: allowConcurrent
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: "When true, allows concurrent requests (bypasses the global lock). Default: false. Implicitly true when `requestKey` is set."
+      - term:
+          code: requestKey
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "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."
       - term:
           code: updateDataAtLocation
           after: "(string, optional)"

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

@@ -11,6 +11,8 @@
 - `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`).
+- `allowConcurrent` (boolean, optional): When true, allows concurrent requests (bypasses the global lock). Default: false. Implicitly true when `requestKey` is set.
+- `requestKey` (string, optional): Identifier used to group requests that should cancel each other. When set, firing a new submission with the same key aborts the previous one client-side (via AbortController). Different keys are independent. Bypasses the global lock automatically. See the [Concurrency control section in `fetchData`](fetchData.md#concurrency-control--requestkey) — the semantics are identical.
 - `submitSilently` (boolean, optional): If true, doesn't apply visual disabling styles during submission
 - `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.

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

@@ -35,6 +35,18 @@ renderView:
         details:
           type: Markdown
           content: "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`)"
+      - term:
+          code: allowConcurrent
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: "When true, allows concurrent requests (bypasses the global lock). Default: false. Implicitly true when `requestKey` is set."
+      - term:
+          code: requestKey
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "Identifier used to group requests that should cancel each other. When set, firing a new submission with the same key aborts the previous one client-side (via AbortController). Different keys are independent. Bypasses the global lock automatically. See [Concurrency control in `fetchData`](fetchData) — same semantics."
       - term:
           code: submitSilently
           after: "(boolean, optional)"