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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.4.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/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)"