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

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

@@ -74,6 +74,53 @@ renderView:
         class: ""
         txt: Hello world!
 
+  - type: Markdown
+    content: |
+      ## URL attributes
+
+      The URL attributes (`href`, `src`, `action`, `formAction`, `poster`) accept an array of segments, in the format of the `src` of `additionalDataSource` (see *Dynamic URLs with `src` as Array* in [RjBuild structure](../../getting-started/rjbuild-structure)). The references are evaluated in the current template context, so each item of a `Switch` gets its own URL:
+
+      ```yaml
+      - type: a
+        attributes:
+          href:
+            - "/article/"
+            - ~.year
+            - "/"
+            - segment: ~.slug
+              required: true
+        content: ~.title
+      ```
+
+      When a required segment is empty, the attribute is omitted. An array in another attribute is evaluated as before (each item separately).
+
+  - type: Markdown
+    content: |
+      ## Form controls
+
+      `input`, `textarea` and `select` elements are rendered as **controlled** React elements: their `value` defaults to `""`.
+
+      A checkbox or radio `input` is controlled by its `checked` attribute, which defaults to `false`. Without a binding, the input never shows as checked, whatever its reactions do to the data. Bind it to the data:
+
+      - a boolean: `checked: ~.isSelected` (a falsy value leaves the input unchecked);
+      - a comparison or a list membership: an `attributeTransforms` entry setting `checked`, with a condition (`is`, `contains`...).
+
+      ```yaml
+      - type: input
+        attributes:
+          type: checkbox
+          value: ~.label
+        attributeTransforms:
+          - what: setAttributeValue
+            name: checked
+            mode: replace
+            value: true
+            when: ~~.lead.sessions
+            contains: ~.label
+      ```
+
+      A warning is logged when a checkbox or radio has event reactions (`on: change`...) but neither a `checked` attribute nor an attribute transform on `checked`. To store a value or a list of values, prefer [CheckBoxField](../form/CheckBoxField), which binds `checked` itself.
+
   - type: Markdown
     content: |
       ## Limitations

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

@@ -0,0 +1,159 @@
+# LabelFromValue
+
+The `LabelFromValue` component displays the **label** associated with a value, using an option-like structure as data source. It is the read-only counterpart of the form fields: the same `{label, value}` list feeding a [`SelectField`](../form/SelectField.md) or a [`CheckBoxField`](../form/CheckBoxField.md) can be reused to render the selected value as text.
+
+## Basic Syntax
+
+```yaml
+- type: LabelFromValue
+  dataLocation: ~.status
+  options:
+    - label: "Active"
+      value: 1
+    - label: "Inactive"
+      value: 2
+```
+
+With `status: 2` in the data, this renders `Inactive`.
+
+## Properties
+
+- `dataLocation` (string, optional): Path to the value to resolve. Without it, the value is read from the template context under the component's `datafield`.
+- `options` (array, optional): Array of `{label, value}` objects (both support template evaluation). Ignored when `dynamicOptions` is set.
+- `dynamicOptions` (any, optional): Template reference resolving to the options array (e.g. `~~.allStages`, typically options loaded from a backend). Takes precedence over `options`. The items can be `{label, value}` objects, scalars (each scalar is used as both label and value), or objects of any shape mapped with `optionMapping`.
+- `optionMapping` (object, optional): Builds each option from an item of the options list, exactly like in `SelectField` and `CheckBoxField`. It is evaluated once per item, **with the item as the template context** (`~.title` reads the item's `title`, `~~.` still reads the global data). The mapped keys override the item's keys.
+- `defaultFieldValue` (any, optional): Value used when no data is present.
+- `loose` (boolean, optional): Matches the options by `String()`-coerced equality instead of the default strict one (see [Loose matching](#loose-matching)). Omitted or `false` = strict equality (original behavior).
+- `actions` (array, optional): Actions and conditional reactions to execute based on component state (hide, tooltip, …).
+
+The label is rendered through the `View` engine, so it can be a plain string or a full component structure (`{type: strong, content: …}`).
+
+## Loose matching
+
+By default an option matches the current value only on **strict** equality (`===`), so `1` (number) and `"1"` (string) are two different values and no label is found.
+
+This bites when the JS type of the same identifier is not guaranteed across sources. A typical case is a decoupled backend that renders an entity reference id as a **string** when reading the entity, but echoes it back as a **number** in its save response: the label is correct on load, then disappears right after a save — until a full reload restores the original type.
+
+Set `loose: true` to compare the values as strings instead:
+
+```yaml
+- type: LabelFromValue
+  dataLocation: ~.stage
+  dynamicOptions: ~~.allStages
+  loose: true
+```
+
+Nullish values are never coerced: an empty value (`null` / `undefined`) still matches nothing, so it cannot accidentally match an option whose value is the `"null"` string. `loose` is opt-in — omitted, the component behaves exactly as before, so existing usages are unaffected.
+
+## Examples
+
+### Display the label of a selected value
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.status
+    label: "Status"
+    options:
+      - label: "Active"
+        value: 1
+      - label: "Inactive"
+        value: 2
+      - label: "Pending"
+        value: 3
+  - type: div
+    content:
+      - type: strong
+        content: "Label: "
+      - type: LabelFromValue
+        dataLocation: ~.status
+        options:
+          - label: "Active"
+            value: 1
+          - label: "Inactive"
+            value: 2
+          - label: "Pending"
+            value: 3
+
+data:
+  status: 3
+```
+
+Renders: `Label: Pending`.
+
+### Options loaded from a backend, with loose matching
+
+```yaml
+renderView:
+  - type: LabelFromValue
+    dataLocation: ~~.deal.data.stage
+    dynamicOptions: ~~.allStages
+    loose: true
+
+data:
+  # allStages is typically fetched (additionalDataSource) as
+  # [{label: "Discovery", value: "12"}, {label: "Negotiation", value: "13"}, …]
+  deal:
+    data:
+      stage: 13
+```
+
+The value is a number while the option values are strings: without `loose`, nothing would be displayed.
+
+### Options of any shape, with a mapping
+
+```yaml
+renderView:
+  - type: LabelFromValue
+    dataLocation: ~~.deal.stage
+    dynamicOptions: ~~.stages
+    optionMapping:
+      label: ~.title
+      value: ~.id
+
+data:
+  stages:
+    - id: "new"
+      title: "New"
+    - id: "won"
+      title: "Won"
+  deal:
+    stage: "won"
+```
+
+Renders: `Won`. Use the same `optionMapping` as the `SelectField` editing the value.
+
+### Inside a template, against global data
+
+```yaml
+templates:
+  userCard:
+    type: div
+    content:
+      - "Admin: "
+      - type: LabelFromValue
+        dataLocation: ~~.isAdmin
+        options:
+          - label: "Yes"
+            value: true
+          - label: "No"
+            value: false
+
+renderView:
+  - load: userCard
+
+data:
+  isAdmin: true
+```
+
+## Notes
+
+- The first matching option wins; the options list is not deduplicated.
+- When no option matches the value (or the matched option carries no `label`), nothing is displayed — the value itself is not used as a fallback label.
+- An empty value (`null`, `undefined`, `""`) therefore renders nothing, unless an option explicitly declares that value.
+
+## Limitations
+
+- No support for grouped options or nested option structures.
+- No built-in formatting of the label (wrap the component if needed).
+- Multi-value data (an array of values) is not supported: the whole array is compared to each option value.

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

@@ -3,7 +3,23 @@ renderView:
     content: |
       # LabelFromValue
 
-      The `LabelFromValue` component displays the label associated with a value, using an option-like structure. It is useful for showing the display label of a value selected in a SelectField or any value/label mapping.
+      The `LabelFromValue` component displays the **label** associated with a value, using an option-like structure as data source. It is the read-only counterpart of the form fields: the same `{label, value}` list feeding a [`SelectField`](/docs/core/element/form/SelectField) or a [`CheckBoxField`](/docs/core/element/form/CheckBoxField) can be reused to render the selected value as text.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: LabelFromValue
+        dataLocation: ~.status
+        options:
+          - label: "Active"
+            value: 1
+          - label: "Inactive"
+            value: 2
+      ```
+
+      With `status: 2` in the data, this renders `Inactive`.
 
       ## Properties
 
@@ -11,22 +27,44 @@ renderView:
     content:
       - term:
           code: dataLocation
-          after: "(string, required)"
-        details: "Path to the value."
+          after: "(string, optional)"
+        details: "Path to the value to resolve. Without it, the value is read from the template context under the component's `datafield`."
       - term:
           code: options
           after: "(array, optional)"
         details:
           type: Markdown
-          content: "Array of `{label, value}` objects."
+          content: "Array of `{label, value}` objects (both support template evaluation). Ignored when `dynamicOptions` is set."
       - term:
           code: dynamicOptions
           after: "(any, optional)"
-        details: "Template value for dynamic options."
+        details:
+          type: Markdown
+          content: "Template reference resolving to the options array (e.g. `~~.allStages`, typically options loaded from a backend). Takes precedence over `options`. The items can be `{label, value}` objects, scalars (each scalar is used as both label and value), or objects of any shape mapped with `optionMapping`."
+      - term:
+          code: optionMapping
+          after: "(object, optional)"
+        details:
+          type: Markdown
+          content: "Builds each option from an item of the options list, exactly like in `SelectField` and `CheckBoxField`. It is evaluated once per item, **with the item as the template context** (`~.title` reads the item's `title`, `~~.` still reads the global data). The mapped keys override the item's keys."
       - term:
           code: defaultFieldValue
           after: "(any, optional)"
-        details: "Default value if none is set."
+        details: "Value used when no data is present."
+      - term:
+          code: loose
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: "Matches the options by `String()`-coerced equality instead of the default strict one. See [Loose matching](#loose-matching). Omitted or `false` = strict equality (original behavior)."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions and conditional reactions to execute based on component state (hide, tooltip, …)."
+
+  - type: Markdown
+    content: |
+      The label is rendered through the `View` engine, so it can be a plain string or a full component structure (`{type: strong, content: …}`).
 
   - type: RjBuildDescriber
     title: "Interactive Example: Display label from value"
@@ -64,8 +102,123 @@ renderView:
 
   - type: Markdown
     content: |
+      ## Loose matching
+
+      By default an option matches the current value only on **strict** equality (`===`), so `1` (number) and `"1"` (string) are two different values and no label is found.
+
+      This bites when the JS type of the same identifier is not guaranteed across sources. A typical case is a decoupled backend that renders an entity reference id as a **string** when reading the entity, but echoes it back as a **number** in its save response: the label is correct on load, then disappears right after a save — until a full reload restores the original type.
+
+      Set `loose: true` to compare the values as strings instead:
+
+      ```yaml
+      - type: LabelFromValue
+        dataLocation: ~.stage
+        dynamicOptions: ~~.allStages
+        loose: true
+      ```
+
+      Nullish values are never coerced: an empty value (`null` / `undefined`) still matches nothing, so it cannot accidentally match an option whose value is the `"null"` string. `loose` is opt-in — omitted, the component behaves exactly as before.
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Loose matching"
+    description:
+      - type: Markdown
+        content: |
+          Both components read the same value, `"2"` (a **string**), against options whose values are **numbers**. Only the loose one finds the label.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: strong
+              content: "Strict (default): "
+            - type: LabelFromValue
+              dataLocation: ~.status
+              options:
+                - label: "Active"
+                  value: 1
+                - label: "Inactive"
+                  value: 2
+                - label: "Pending"
+                  value: 3
+        - type: div
+          content:
+            - type: strong
+              content: "Loose: "
+            - type: LabelFromValue
+              dataLocation: ~.status
+              loose: true
+              options:
+                - label: "Active"
+                  value: 1
+                - label: "Inactive"
+                  value: 2
+                - label: "Pending"
+                  value: 3
+      data:
+        status: "2"
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Options loaded from a backend"
+    description:
+      - type: Markdown
+        content: |
+          `dynamicOptions` reads the options from the data (here `allStages`, as an `additionalDataSource` would provide them). The value is a **number** while the option values are **strings**, hence `loose: true`.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: strong
+              content: "Stage: "
+            - type: LabelFromValue
+              dataLocation: ~~.deal.data.stage
+              dynamicOptions: ~~.allStages
+              loose: true
+      data:
+        allStages:
+          - label: "Discovery"
+            value: "12"
+          - label: "Negotiation"
+            value: "13"
+          - label: "Closed won"
+            value: "14"
+        deal:
+          data:
+            stage: 13
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Inside a template, against global data"
+    description:
+      - type: Markdown
+        content: |
+          Within a template, `~~.` reaches the global data while `~.` would stay in the template scope.
+    toDescribe:
+      renderView:
+        - load: userCard
+      templates:
+        userCard:
+          type: div
+          content:
+            - "Admin: "
+            - type: LabelFromValue
+              dataLocation: ~~.isAdmin
+              options:
+                - label: "Yes"
+                  value: true
+                - label: "No"
+                  value: false
+      data:
+        isAdmin: true
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - The first matching option wins; the options list is not deduplicated.
+      - When no option matches the value (or the matched option carries no `label`), nothing is displayed — the value itself is not used as a fallback label.
+      - An empty value (`null`, `undefined`, `""`) therefore renders nothing, unless an option explicitly declares that value.
+
       ## Limitations
-      - Only the first matching label is displayed; duplicate values in options are not supported.
-      - No support for grouped options or nested structures.
-      - No built-in formatting for the label (use a wrapper if needed).
-      - If no options are provided, the raw value is shown.
+
+      - No support for grouped options or nested option structures.
+      - No built-in formatting of the label (wrap the component if needed).
+      - Multi-value data (an array of values) is not supported: the whole array is compared to each option value.

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/example/native-html-forms.md

@@ -146,13 +146,22 @@ Use the `for` attribute to associate labels with form elements for accessibility
 ```
 
 ### Radio Buttons
+
+Each radio must be checked only when the stored value is its own. `checked: ~.selectedSize` would check every radio as soon as a size is selected, so compare the value with an attribute transform:
+
 ```yaml
 - type: input
   attributes:
     type: "radio"
     name: "size"
     value: "small"
-    checked: ~.selectedSize
+  attributeTransforms:
+    - what: setAttributeValue
+      name: checked
+      mode: replace
+      value: true
+      when: ~.selectedSize
+      is: "small"
   actions:
     - what: setData
       on: change
@@ -164,7 +173,13 @@ Use the `for` attribute to associate labels with form elements for accessibility
     type: "radio"
     name: "size"
     value: "large"
-    checked: ~.selectedSize
+  attributeTransforms:
+    - what: setAttributeValue
+      name: checked
+      mode: replace
+      value: true
+      when: ~.selectedSize
+      is: "large"
   actions:
     - what: setData
       on: change
@@ -172,6 +187,8 @@ Use the `for` attribute to associate labels with form elements for accessibility
       value: "large"
 ```
 
+A checkbox or radio without a `checked` binding (attribute or attribute transform) is forced to unchecked and never shows a user's click. [CheckBoxField](../element/form/CheckBoxField.md) with `controlType: radio` handles all of this by itself.
+
 ## Advanced Patterns
 
 ### Form Validation with Conditional Actions

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/collectField.md

@@ -0,0 +1,51 @@
+# Reaction: collectField
+
+The `collectField` reaction writes the values of one field of every item of a collection, as an array. Typical use: a "select all" checkbox that writes the identifiers of the listed items.
+
+## Properties
+
+- `from` (string, required): The collection (template syntax), an array of objects.
+- `field` (string, required): The name of the field to read in each item. It is evaluated.
+- `path` (string, required): The location receiving the array (template syntax).
+
+## Behavior
+
+- The array of the `field` values is written at `path`, in the order of the collection.
+- The items that are not objects, and the items whose field is `null`, `undefined` or an empty string, are skipped.
+- A collection that is not an array writes an empty array.
+- The collection is read from the complete data, even inside a `DataFilter`.
+
+## Example
+
+### Select all / deselect all
+
+```yaml
+renderView:
+  - type: button
+    content: "Select all"
+    actions:
+      - what: collectField
+        on: click
+        from: ~~.results
+        field: nid
+        path: ~~.selection
+  - type: button
+    content: "Deselect all"
+    actions:
+      - what: setData
+        on: click
+        path: ~~.selection
+        value: []
+
+data:
+  results:
+    - nid: 4
+      title: "First"
+    - nid: 9
+      title: "Second"
+  selection: []
+```
+
+## Limitations
+
+- Only a direct field of the items is read (no nested path such as `author.id`).