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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^2.10.0",
+    "@ea-lab/reactive-json": "^2.11.1",
     "@ea-lab/reactive-json-chartjs": "^1.1.1",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

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

@@ -262,6 +262,46 @@ const plugins = mergeComponentCollections([
 
 The registry must be a **shared singleton**: every `DataSync` that resolves the same `dataSyncGroups` object joins the same groups. Provide one instance, not one per render.
 
+## Host-controlled saving (`useDataSyncPolicy`)
+
+Some hosts decide *when* the content is saved, instead of each `DataSync`: an editor with a global **Save** button, for example. The same RjBuild can then autosave in one host and wait for the Save button in another, without any change to its YAML.
+
+Register a `useDataSyncPolicy` hook under `plugins.hook`. It is called on every render of every `DataSync`, with the resolved store path of the syncable (without the `data.` prefix) and the `DataSync` props, and returns the policy of this syncable:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `manual` | boolean | `true` holds the user edits instead of saving them. Default: `false` (the `mode` of the `DataSync` applies). |
+| `flushSignal` | any | In manual mode, a change of this value saves the held edits. Its value at mount does not save anything. |
+| `onDirty` | function | Called on each held edit, e.g. to enable a Save button or a "leave the page?" guard. |
+| `defaultMergeKey` | function(syncable) | The group identity used when the `DataSync` has no `mergeKey`, e.g. `(syncable) => syncable?.item_url`. Return `null` to leave the syncable alone. |
+
+```js
+import { useContext } from "react";
+
+const useDataSyncPolicy = ({ path, props }) => {
+  // The host state, e.g. from a React context provided by the editor.
+  const editor = useContext(EditorContext);
+
+  return {
+    manual: Boolean(editor?.editing) && path === "content",
+    flushSignal: editor?.saveCount,
+    onDirty: editor?.markDirty,
+    defaultMergeKey: (syncable) => syncable?.item_url,
+  };
+};
+
+const plugins = mergeComponentCollections([{ hook: { useDataSyncPolicy } }]);
+```
+
+Behavior in manual mode:
+- An edit is held and `onDirty` is called. The `trigger` property still saves immediately.
+- When `flushSignal` changes, each `DataSync` holding edits saves them once. In a `mergeKey` group, only the owner writes, with the latest shared data.
+- The edits are still mirrored live to the other members of the group, so that every mount shows the same content, and so that the owner writes the edits made on the other mounts.
+
+Without the hook, every `DataSync` follows its own `mode`, and only an explicit `mergeKey` groups syncables. The hook is a plugin: it applies to the roots (and subroots) that receive it, so an app can restrict it to an editor.
+
+**Limitation**: in manual mode, the live mirror follows each store change. In a form updated on each keystroke (`TextField`), each keystroke is mirrored to the other members of the group.
+
 ## Using with Templates
 
 `DataSync` supports `TemplateContext`, so it can be used inside templates to sync individual items in a list:
@@ -362,6 +402,6 @@ renderView:
 - Only one sync can be active at a time per `DataSync` instance. Concurrent changes while a sync is in flight are not queued.
 - The entire Syncable Object is sent in the POST body, not just the `data` field.
 - Only POST requests are supported for submission. Custom HTTP methods are not configurable.
-- `item_url` and `delete_url` are part of the Syncable Object structure but are not used by the component itself. They are available for the backend or for other components to use.
+- `delete_url` is part of the Syncable Object structure but is not used by the component itself. `item_url` is only used to recognize a syncable reloaded from the server (its data is then not posted back).
 - No built-in support for optimistic updates. The local data is replaced by the server response.
 - CORS errors are not retried (they are indistinguishable from network errors when the browser is online).

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

@@ -335,6 +335,46 @@ renderView:
 
       The registry must be a **shared singleton**: every `DataSync` that resolves the same `dataSyncGroups` object joins the same groups. Provide one instance, not one per render.
 
+      ## Host-controlled saving (`useDataSyncPolicy`)
+
+      Some hosts decide *when* the content is saved, instead of each `DataSync`: an editor with a global **Save** button, for example. The same RjBuild can then autosave in one host and wait for the Save button in another, without any change to its YAML.
+
+      Register a `useDataSyncPolicy` hook under `plugins.hook`. It is called on every render of every `DataSync`, with the resolved store path of the syncable (without the `data.` prefix) and the `DataSync` props, and returns the policy of this syncable:
+
+      | Key | Type | Description |
+      |-----|------|-------------|
+      | `manual` | boolean | `true` holds the user edits instead of saving them. Default: `false` (the `mode` of the `DataSync` applies). |
+      | `flushSignal` | any | In manual mode, a change of this value saves the held edits. Its value at mount does not save anything. |
+      | `onDirty` | function | Called on each held edit, e.g. to enable a Save button or a "leave the page?" guard. |
+      | `defaultMergeKey` | function(syncable) | The group identity used when the `DataSync` has no `mergeKey`, e.g. `(syncable) => syncable?.item_url`. Return `null` to leave the syncable alone. |
+
+      ```js
+      import { useContext } from "react";
+
+      const useDataSyncPolicy = ({ path, props }) => {
+        // The host state, e.g. from a React context provided by the editor.
+        const editor = useContext(EditorContext);
+
+        return {
+          manual: Boolean(editor?.editing) && path === "content",
+          flushSignal: editor?.saveCount,
+          onDirty: editor?.markDirty,
+          defaultMergeKey: (syncable) => syncable?.item_url,
+        };
+      };
+
+      const plugins = mergeComponentCollections([{ hook: { useDataSyncPolicy } }]);
+      ```
+
+      Behavior in manual mode:
+      - An edit is held and `onDirty` is called. The `trigger` property still saves immediately.
+      - When `flushSignal` changes, each `DataSync` holding edits saves them once. In a `mergeKey` group, only the owner writes, with the latest shared data.
+      - The edits are still mirrored live to the other members of the group, so that every mount shows the same content, and so that the owner writes the edits made on the other mounts.
+
+      Without the hook, every `DataSync` follows its own `mode`, and only an explicit `mergeKey` groups syncables. The hook is a plugin: it applies to the roots (and subroots) that receive it, so an app can restrict it to an editor.
+
+      **Limitation**: in manual mode, the live mirror follows each store change. In a form updated on each keystroke (`TextField`), each keystroke is mirrored to the other members of the group.
+
       ## Using with Templates
 
       `DataSync` supports `TemplateContext`, so it can be used inside templates to sync individual items in a list:
@@ -382,6 +422,6 @@ renderView:
       - Only one sync can be active at a time per `DataSync` instance. Concurrent changes while a sync is in flight are not queued.
       - The entire Syncable Object is sent in the POST body, not just the `data` field.
       - Only POST requests are supported for submission. Custom HTTP methods are not configurable.
-      - `item_url` and `delete_url` are part of the Syncable Object structure but are not used by the component itself. They are available for the backend or for other components to use.
+      - `delete_url` is part of the Syncable Object structure but is not used by the component itself. `item_url` is only used to recognize a syncable reloaded from the server (its data is then not posted back).
       - No built-in support for optimistic updates. The local data is replaced by the server response.
       - CORS errors are not retried (they are indistinguishable from network errors when the browser is online).

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

@@ -12,6 +12,9 @@ Hooks in Reactive-JSON are reusable React functions that encapsulate common comp
 ### Attribute Processing
 - **[useTransformedAttributes](./useTransformedAttributes.md)**: Applies attribute transformations based on configured transformers
 
+### Hooks provided by the application
+- **useDataSyncPolicy**: Decides how each `DataSync` saves (automatic or held until a flush signal) and how the syncables are grouped. The core has no default implementation: without it, every `DataSync` follows its own `mode`. See [DataSync: Host-controlled saving](../element/special/DataSync.md#host-controlled-saving-usedatasyncpolicy).
+
 ## Architecture
 
 Reactive-JSON hooks follow these core principles:

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

@@ -15,6 +15,9 @@ renderView:
       ### Attribute Processing
       - **[useTransformedAttributes](./useTransformedAttributes)**: Applies attribute transformations based on configured transformers
 
+      ### Hooks provided by the application
+      - **useDataSyncPolicy**: Decides how each `DataSync` saves (automatic or held until a flush signal) and how the syncables are grouped. The core has no default implementation: without it, every `DataSync` follows its own `mode`. See *Host-controlled saving* in [DataSync](../element/special/DataSync).
+
       ## Architecture
 
       Reactive-JSON hooks follow these core principles:

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

@@ -12,7 +12,7 @@ The `setClipboardData` reaction copies a specified value to the user's clipboard
 - When triggered, the reaction evaluates the `value` property.
 - 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"`.
+- 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
 

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

@@ -29,7 +29,7 @@ renderView:
       - When triggered, the reaction evaluates the `value` property.
       - 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"`.
+      - 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
 

package/public/rjbuild/docs/getting-started/rjbuild-structure.md

@@ -336,10 +336,14 @@ additionalDataSource:
     blocking: true
 ```
 
+**Array values:** when the value resolves to an array, the param is repeated for each item: `{ param: "domains", value: ~~.domains }` with `domains: ["a.fr", "b.fr"]` gives `?domains=a.fr&domains=b.fr`. The empty items are skipped, and an empty array counts as an empty value. For a PHP backend, name the param with brackets (`domains[]`) to receive an array.
+
 **Null handling for params:**
 - If either the key or the value resolves to `null`/empty and `required` is absent or `false`, the param is **silently omitted** from the URL.
 - If either resolves to `null`/empty and `required: true` is set, the entire URL is **aborted**, triggering `fallbackDataSource` if defined.
 
+An aborted URL logs a warning naming the caller (`additionalDataSource`, `redirectNow`, `href attribute`...), the empty part and its position in the array.
+
 ```yaml
 additionalDataSource:
   - src:
@@ -409,7 +413,7 @@ The segments format is also accepted by:
 - the URL attributes (`href`, `src`, `action`, `formAction`, `poster`) of any element: the attribute is omitted when a required segment is empty;
 - `parts` of the [joinData](../core/reaction/joinData.md) reaction, which writes the composed string in the data.
 
-There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data.
+There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data. In a reaction, the event placeholders also work in the parts, `required` included: `{ segment: "<reactive-json:event-new-value>.id", required: true }`.
 
 ```yaml
 - type: a

package/public/rjbuild/docs/getting-started/rjbuild-structure.yaml

@@ -355,10 +355,14 @@ renderView:
 
       A param object adds a key-value pair to the URL query string. Both the key and the value accept store references.
 
+      **Array values:** when the value resolves to an array, the param is repeated for each item: `{ param: "domains", value: ~~.domains }` with `domains: ["a.fr", "b.fr"]` gives `?domains=a.fr&domains=b.fr`. The empty items are skipped, and an empty array counts as an empty value. For a PHP backend, name the param with brackets (`domains[]`) to receive an array.
+
       **Null handling:**
       - If either the key or the value resolves to `null`/empty and `required` is absent or `false`, the param is **silently omitted** from the URL.
       - If either resolves to `null`/empty and `required: true` is set, the entire URL is **aborted**, triggering `fallbackDataSource` if defined.
 
+      An aborted URL logs a warning naming the caller (`additionalDataSource`, `redirectNow`, `href attribute`...), the empty part and its position in the array.
+
   - type: TabbedSerializer
     yamlSerializedContent: |
       additionalDataSource:
@@ -439,7 +443,7 @@ renderView:
       - the URL attributes (`href`, `src`, `action`, `formAction`, `poster`) of any element: the attribute is omitted when a required segment is empty;
       - `parts` of the [joinData](../core/reaction/joinData) reaction, which writes the composed string in the data.
 
-      There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data.
+      There, the references are evaluated in the current template context: `~.slug` reads the current template data (e.g. the current `Switch` item), `~~.` the global data, `~>key` an ancestor. In `additionalDataSource.src`, both `~.` and `~~.` read the root data. In a reaction, the event placeholders also work in the parts, `required` included: `{ segment: "<reactive-json:event-new-value>.id", required: true }`.
 
       ```yaml
       - type: a