@ea-lab/reactive-json-docs 1.3.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "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": "^1.2.0",
+    "@ea-lab/reactive-json": "^1.3.0",
     "@ea-lab/reactive-json-chartjs": "^1.0.0",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.md

@@ -8,42 +8,73 @@ Dynamically sets or modifies the value of an HTML attribute before rendering. Th
 
 ```yaml
 attributeTransforms:
-  # Add CSS class
+  # Add CSS class (string mode)
   - what: setAttributeValue
     name: "class"
     value: "active"
     
-  # Replace attribute value
+  # Replace attribute value (string mode)
   - what: setAttributeValue
     name: "data-status"
     mode: "replace"
     value: ~.currentStatus
+    
+  # Merge style object (object mode)
+  - what: setAttributeValue
+    name: "style"
+    value:
+      borderColor: "#3b82f6"
+      backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
 ```
 
 ## Properties
 
 - **name** *(string, required)*: The name of the attribute to modify.
 - **mode** *(string, optional)*: The modification mode. Default: `"append"`.
-  - `"append"`: Adds the value to the existing attribute value (space-separated).
+  - `"append"`: Adds the value to the existing attribute value (space-separated for strings, merges properties for objects).
   - `"replace"`: Completely replaces the existing attribute value.
-- **value** *(string, required)*: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
-- **preventDuplicateValues** *(boolean, optional)*: When `true` (default), prevents duplicate values when using append mode.
-- **separator** *(string, optional)*: The separator used between values. Default: `" "` (space).
+- **value** *(string | object, required)*: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`).
+  - **String mode**: When `value` is a string, operates in string mode for simple attributes like `class`, `data-*`, etc.
+  - **Object mode**: When `value` is an object, operates in object mode for complex attributes like `style`. In append mode, merges properties property by property.
+- **preventDuplicateValues** *(boolean, optional)*: When `true` (default), prevents duplicate values when using append mode (applies to string mode and string properties in object mode).
+- **separator** *(string, optional)*: The separator used between values in string mode. Default: `" "` (space).
 
 ## Behavior
 
+The transformer operates in two distinct modes based on the `value` type:
+
+### String Mode (when `value` is a string)
+
 - **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
 - **Replace mode**: Completely overwrites the existing attribute value.
 - **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
 
+### Object Mode (when `value` is an object)
+
+- **Replace mode**: Completely replaces the entire object attribute.
+- **Append mode**: Merges properties property by property:
+  - Starts from the current object attribute
+  - For each property in `value`, applies the same logic as string mode:
+    - If both current and new values are strings: appends them (respecting `preventDuplicateValues`)
+    - Otherwise: replaces the property with the new value (new value has precedence)
+  - Handles nested objects recursively
+  - Works on a copy to avoid mutation issues
+
+### Undefined Values
+
+- **Append mode**: `undefined` values are ignored, keeping the current attribute unchanged.
+- **Replace mode**: `undefined` is assigned to the attribute.
+
 ## Common Use Cases
 
-- **Dynamic CSS classes**: Adding/removing CSS classes based on state.
-- **Data attributes**: Setting data-* attributes for JavaScript integration.
-- **ARIA attributes**: Dynamically updating accessibility attributes.
-- **Style attributes**: Modifying inline styles conditionally.
+- **Dynamic CSS classes**: Adding/removing CSS classes based on state (string mode).
+- **Data attributes**: Setting data-* attributes for JavaScript integration (string mode).
+- **ARIA attributes**: Dynamically updating accessibility attributes (string mode).
+- **Style attributes**: Modifying inline styles conditionally (object mode). Merge style properties without losing existing ones.
+
+## Examples
 
-## Example
+### String Mode Example
 
 ```yaml
 renderView:
@@ -61,6 +92,8 @@ renderView:
         margin: "10px 0"
         width: "300px"
         display: "block"
+        backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+        color: "#212529"
     attributeTransforms:
       - what: setAttributeValue
         name: "class"
@@ -91,11 +124,81 @@ data:
   input_data: ""
 ```
 
+### Object Mode Example (Style Merging)
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      style:
+        padding: "20px"
+        borderWidth: "2px"
+        borderStyle: "solid"
+        borderColor: "#007bff #007bff"
+        borderRadius: "4px"
+        backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+        color: "#212529"
+    attributeTransforms:
+      # Merge additional style properties without losing existing ones
+      - what: setAttributeValue
+        name: "style"
+        value:
+          borderColor: "#007bff var(--bs-primary, #3b82f6)"
+        when: ~.isHighlighted
+        is: true
+    # Result when isHighlighted is true:
+    # The modification changes the highlight color for vertical borders (left and right)
+    # borderColor becomes: "#007bff var(--bs-primary, #3b82f6)"
+    # (horizontal borders stay #007bff, vertical borders change to primary color)
+
+data:
+  isHighlighted: false
+```
+
+### Object Mode Replace Example
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      style:
+        padding: "10px"
+        border: "2px solid #007bff"
+        backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+        color: "#212529"
+    attributeTransforms:
+      # Completely replace the style object
+      - what: setAttributeValue
+        name: "style"
+        mode: "replace"
+        value:
+          backgroundColor: "var(--bs-primary-bg-subtle, #d4f0ec)"
+          color: "var(--bs-primary-text-emphasis, #2b6b5a)"
+          padding: "15px"
+          borderRadius: "8px"
+          border: "2px solid var(--bs-primary, #44a08d)"
+    # Result:
+    # style: {
+    #   backgroundColor: "var(--bs-primary-bg-subtle, #d4f0ec)",
+    #   color: "var(--bs-primary-text-emphasis, #2b6b5a)",
+    #   padding: "15px",
+    #   borderRadius: "8px",
+    #   border: "2px solid var(--bs-primary, #44a08d)"
+    # }
+    # (original styles are completely replaced)
+```
+
 ## Notes
 
 - **Pre-render execution**: This transformer modifies attributes before the component renders, ensuring child components receive the transformed attributes.
-- **Append mode behavior**: Respects existing attribute values when using append mode.
-- **Replace mode**: Use when you need complete control over the attribute value.
-- **Duplicate prevention**: Only applies to append mode.
+- **Mode detection**: The transformer automatically detects whether to use string mode or object mode based on the `value` type after template evaluation.
+- **Append mode behavior**: 
+  - **String mode**: Respects existing attribute values, adding new values separated by the specified separator.
+  - **Object mode**: Merges properties property by property, applying string append logic where both values are strings, otherwise replacing with the new value.
+- **Replace mode**: Use when you need complete control over the attribute value. In object mode, completely replaces the entire object.
+- **Duplicate prevention**: Only applies to append mode, and works for string values in both string mode and object mode.
+- **Object merging**: In object mode append, nested objects are merged recursively. Properties that don't match the expected format for append are replaced (new value has precedence).
+- **Extended properties vs shorthand**: When transformations are required, prefer using extended CSS properties (e.g., `borderWidth`, `borderStyle`, `borderColor`) instead of shorthand properties (e.g., `border`). This ensures the browser handles property modifications correctly. When you modify a single property like `borderColor` on an element that uses the shorthand `border`, the browser may decompose the shorthand into individual properties, which can lead to unexpected behavior. Using extended properties from the start avoids this issue.
 - **Template evaluation**: The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
 - **Conditional execution**: Supports the same condition system as actions (`when`, `is`, `isEmpty`, `isNotEmpty`, etc.).
+- **Undefined handling**: `undefined` values are ignored in append mode but assigned in replace mode.

package/public/rjbuild/docs/core/attributeTransformer/setAttributeValue.yaml

@@ -12,16 +12,23 @@ renderView:
   - type: TabbedSerializer
     yamlSerializedContent: |
       attributeTransforms:
-        # Add CSS class
+        # Add CSS class (string mode)
         - what: setAttributeValue
           name: "class"
           value: "active"
           
-        # Replace attribute value
+        # Replace attribute value (string mode)
         - what: setAttributeValue
           name: "data-status"
           mode: "replace"
           value: ~.currentStatus
+          
+        # Merge style object (object mode)
+        - what: setAttributeValue
+          name: "style"
+          value:
+            borderColor: "#3b82f6"
+            backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
 
   - type: Markdown
     content: |
@@ -44,8 +51,14 @@ renderView:
             - `"replace"`: Completely replaces the existing attribute value
       - term:
           code: value
-          after: "(string, required)"
-        details: The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already. Special characters are handled safely.
+          after: "(string | object, required)"
+        details:
+          type: Markdown
+          content: |
+            The value to set or append. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`).
+            
+            - **String mode**: When `value` is a string, operates in string mode for simple attributes like `class`, `data-*`, etc.
+            - **Object mode**: When `value` is an object, operates in object mode for complex attributes like `style`. In append mode, merges properties property by property.
       - term:
           code: preventDuplicateValues
           after: "(boolean, optional)"
@@ -65,16 +78,36 @@ renderView:
 
       ## Behavior
 
+      The transformer operates in two distinct modes based on the `value` type:
+
+      ### String Mode (when `value` is a string)
+
       - **Append mode**: Adds the new value to the existing attribute, separated by the specified separator.
       - **Replace mode**: Completely overwrites the existing attribute value.
       - **Duplicate prevention**: In append mode, prevents adding duplicate values when enabled.
 
+      ### Object Mode (when `value` is an object)
+
+      - **Replace mode**: Completely replaces the entire object attribute.
+      - **Append mode**: Merges properties property by property:
+        - Starts from the current object attribute
+        - For each property in `value`, applies the same logic as string mode:
+          - If both current and new values are strings: appends them (respecting `preventDuplicateValues`)
+          - Otherwise: replaces the property with the new value (new value has precedence)
+        - Handles nested objects recursively
+        - Works on a copy to avoid mutation issues
+
+      ### Undefined Values
+
+      - **Append mode**: `undefined` values are ignored, keeping the current attribute unchanged.
+      - **Replace mode**: `undefined` is assigned to the attribute.
+
       ## Common Use Cases
 
-      - **Dynamic CSS classes**: Adding/removing CSS classes based on state.
-      - **Data attributes**: Setting data-* attributes for JavaScript integration.
-      - **ARIA attributes**: Dynamically updating accessibility attributes.
-      - **Style attributes**: Modifying inline styles conditionally.
+      - **Dynamic CSS classes**: Adding/removing CSS classes based on state (string mode).
+      - **Data attributes**: Setting data-* attributes for JavaScript integration (string mode).
+      - **ARIA attributes**: Dynamically updating accessibility attributes (string mode).
+      - **Style attributes**: Modifying inline styles conditionally (object mode). Merge style properties without losing existing ones.
 
   - type: RjBuildDescriber
     title: "SetAttributeValue Action Examples"
@@ -108,6 +141,8 @@ renderView:
               margin: "10px 0"
               width: "300px"
               display: "block"
+              backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+              color: "#212529"
           actions:
             - what: setData
               on: change
@@ -134,11 +169,108 @@ renderView:
       data:
         input_data: ""
 
+  - type: RjBuildDescriber
+    title: "Object Mode Example - Style Merging"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to use `setAttributeValue` in object mode to merge style properties without losing existing ones.
+          
+          **Expected behavior:**
+          - The div has initial styles (padding, border, borderRadius)
+          - When `isHighlighted` is true, additional style properties are merged
+          - The modification changes the highlight color for vertical borders (left and right), as `borderColor` contains two colors
+          - The original styles are preserved, and new properties are added
+          - Try toggling the highlight to see the style merge in action
+
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            style:
+              padding: "10px"
+              borderWidth: "5px"
+              borderStyle: "solid"
+              borderColor: "black"
+              borderRadius: "4px"
+              backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+              color: "#212529"
+          attributeTransforms:
+            # Merge additional style properties without losing existing ones
+            - what: setAttributeValue
+              name: "style"
+              value:
+                borderColor: "var(--bs-primary, #3b82f6)"
+              when: ~.isHighlighted
+              is: true
+          content: "Click to toggle highlight"
+
+        - type: button
+          content: "Toggle Highlight"
+          actions:
+            - what: setData
+              on: click
+              path: ~.isHighlighted
+              value: true
+              when: ~.isHighlighted
+              is: false
+            - what: setData
+              on: click
+              path: ~.isHighlighted
+              value: false
+              when: ~.isHighlighted
+              is: true
+
+      data:
+        isHighlighted: false
+
+  - type: RjBuildDescriber
+    title: "Object Mode Replace Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to completely replace a style object using `mode: "replace"`.
+          
+          **Expected behavior:**
+          - The div has initial styles (padding, border)
+          - When replace mode is used, the entire style object is replaced
+          - Original styles are lost, only the new styles remain
+
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              backgroundColor: "var(--bs-secondary-bg-subtle, rgba(0, 0, 0, 0.05))"
+              color: "#212529"
+          attributeTransforms:
+            # Completely replace the style object
+            - what: setAttributeValue
+              name: "style"
+              mode: "replace"
+              value:
+                backgroundColor: "var(--bs-primary-bg-subtle, #d4f0ec)"
+                color: "var(--bs-primary-text-emphasis, #2b6b5a)"
+                padding: "15px"
+                borderRadius: "8px"
+                border: "2px solid var(--bs-primary, #44a08d)"
+          content: "This div's style was completely replaced"
+
   - type: Markdown
     content: |
       ## Notes
 
-      - The action respects existing attribute values when using append mode.
-      - Use replace mode when you need complete control over the attribute value.
-      - Duplicate prevention only applies to append mode.
-      - The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
+      - **Pre-render execution**: This transformer modifies attributes before the component renders, ensuring child components receive the transformed attributes.
+      - **Mode detection**: The transformer automatically detects whether to use string mode or object mode based on the `value` type after template evaluation.
+      - **Append mode behavior**: 
+        - **String mode**: Respects existing attribute values, adding new values separated by the specified separator.
+        - **Object mode**: Merges properties property by property, applying string append logic where both values are strings, otherwise replacing with the new value.
+      - **Replace mode**: Use when you need complete control over the attribute value. In object mode, completely replaces the entire object.
+      - **Duplicate prevention**: Only applies to append mode, and works for string values in both string mode and object mode.
+      - **Object merging**: In object mode append, nested objects are merged recursively. Properties that don't match the expected format for append are replaced (new value has precedence).
+      - **Extended properties vs shorthand**: When transformations are required, prefer using extended CSS properties (e.g., `borderWidth`, `borderStyle`, `borderColor`) instead of shorthand properties (e.g., `border`). This ensures the browser handles property modifications correctly. When you modify a single property like `borderColor` on an element that uses the shorthand `border`, the browser may decompose the shorthand into individual properties, which can lead to unexpected behavior. Using extended properties from the start avoids this issue.
+      - **Template evaluation**: The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
+      - **Conditional execution**: Supports the same condition system as actions (`when`, `is`, `isEmpty`, `isNotEmpty`, etc.).
+      - **Undefined handling**: `undefined` values are ignored in append mode but assigned in replace mode.

package/public/rjbuild/docs/core/example/DataFilter-example-direct-array.md

@@ -0,0 +1,211 @@
+# DataFilter Example: Filtering Direct Array Items
+
+This example demonstrates how to use `DataFilter` with arrays where each item is a direct object (not wrapped in a namespace property). This is useful when working with data from APIs that return arrays of objects directly.
+
+## Use Case
+
+When your data structure is a direct array of objects like:
+```yaml
+data:
+  rows:
+    - id: 1
+      label: "Operation 1"
+      done: "done"
+      operation: "create"
+    - id: 2
+      label: "Operation 2"
+      done: "pending"
+      operation: "update"
+```
+
+Instead of:
+```yaml
+data:
+  rows:
+    - item:
+        id: 1
+        label: "Operation 1"
+```
+
+## Solution
+
+Use an existing property that is present in all items (like `id`) as the `subjectsWithProperty` namespace. In `whenFilterableData`, reference properties directly without the namespace prefix.
+
+**Important**: When using string values for filtering (like status), use a special value like `"all"` to represent "no filter" instead of an empty string, as empty strings can cause issues with select elements.
+
+## Complete Example
+
+```yaml
+renderView:
+  - type: DataFilter
+    context: global
+    filters:
+      - subjectsWithProperty: id
+        andConditions:
+          # Filter by status (string)
+          - orConditions:
+              - when: ~~._filters.done
+                is: "all"
+              - whenFilterableData: done
+                is: ~~._filters.done
+          
+          # Filter by operation type (text search with contains)
+          - orConditions:
+              - when: ~~._filters.operation
+                is: ""
+              - andConditions:
+                  - whenFilterableData: operation
+                    isNotEmpty: true
+                  - when: ~~._filters.operation
+                    isNotEmpty: true
+                  - whenFilterableData: operation
+                    contains: ~~._filters.operation
+          
+          # Filter by label (text search with contains)
+          - orConditions:
+              - when: ~~._filters.label
+                is: ""
+              - andConditions:
+                  - whenFilterableData: label
+                    isNotEmpty: true
+                  - when: ~~._filters.label
+                    isNotEmpty: true
+                  - whenFilterableData: label
+                    contains: ~~._filters.label
+    content:
+      - type: Switch
+        content: ~~.rows
+        singleOption:
+          load: operationRow
+
+templates:
+  operationRow:
+    - type: tr
+      content:
+        - type: td
+          content: ~.id
+        - type: td
+          content: ~.label
+        - type: td
+          content: ~.done
+        - type: td
+          content: ~.operation
+
+data:
+  rows:
+    - id: 1
+      label: "Operation 1"
+      done: "done"
+      operation: "create"
+    - id: 2
+      label: "Operation 2"
+      done: "pending"
+      operation: "update"
+    - id: 3
+      label: "Operation 3"
+      done: "done"
+      operation: "create"
+  _filters:
+    done: "all"
+    label: ""
+    operation: ""
+```
+
+## Key Points
+
+1. **Namespace Selection**: Choose a property that exists in all items (e.g., `id`, `name`, `key`). This property acts as the identifier for DataFilter to recognize filterable items.
+
+2. **Direct Property Access**: In `whenFilterableData`, reference properties directly:
+   - ✅ `whenFilterableData: label` (correct)
+   - ❌ `whenFilterableData: id.label` (incorrect - don't use namespace prefix)
+
+3. **String-based Filtering**: When using select elements for filtering, use a special value like `"all"` to represent "no filter" instead of an empty string:
+   ```yaml
+   - orConditions:
+       - when: ~~._filters.done
+         is: "all"  # Shows all items
+       - whenFilterableData: done
+         is: ~~._filters.done  # Filters by exact match
+   ```
+   This avoids issues where select elements might not properly handle empty string values.
+
+4. **Text Search**: For text search with `contains`, ensure both the filter value and the data property are not empty:
+   ```yaml
+   - orConditions:
+       - when: ~~._filters.label
+         is: ""  # Shows all when empty
+       - andConditions:
+           - whenFilterableData: label
+             isNotEmpty: true
+           - when: ~~._filters.label
+             isNotEmpty: true
+           - whenFilterableData: label
+             contains: ~~._filters.label
+   ```
+   The `andConditions` wrapper ensures that both the data property and filter value are not empty before attempting the `contains` comparison.
+
+5. **Template Access**: In templates, access properties directly without namespace:
+   - ✅ `~.label`, `~.done`, `~.operation`
+   - ❌ `~.id.label` (incorrect)
+
+## Filter Types Demonstrated
+
+- **Select Filter with "All" option**: Using `is: "all"` to show all items when a special "all" value is selected
+- **Exact String Match**: Using `is` for exact string matching (e.g., status filtering)
+- **Text Search**: Using `contains` for substring matching (case-insensitive) with proper empty checks
+
+## Additional Template Techniques
+
+**Conditional Display in Templates**: The example uses `hide` actions to conditionally display badges based on data values. This is a common pattern for showing different UI elements based on data state:
+
+```yaml
+- type: span
+  content: "Done"
+  actions:
+    - what: hide
+      when: ~.done
+      isNot: "done"  # Hide if status is not "done"
+- type: span
+  content: "Pending"
+  actions:
+    - what: hide
+      when: ~.done
+      isNot: "pending"  # Hide if status is not "pending"
+```
+
+This technique is used in the example to display colored status badges, but it's not part of the DataFilter pattern itself - it's just a way to enhance the visual display of filtered data.
+
+## Filter Patterns
+
+### Pattern 1: Select Filter with "All" Option
+```yaml
+- orConditions:
+    - when: ~~._filters.status
+      is: "all"  # Special value for "show all"
+    - whenFilterableData: status
+      is: ~~._filters.status  # Exact match filter
+```
+
+### Pattern 2: Text Input Filter (Empty String Check)
+```yaml
+- orConditions:
+    - when: ~~._filters.search
+      is: ""  # Empty string means "show all"
+    - andConditions:
+        - whenFilterableData: searchField
+          isNotEmpty: true
+        - when: ~~._filters.search
+          isNotEmpty: true
+        - whenFilterableData: searchField
+          contains: ~~._filters.search
+```
+
+## Notes
+
+- The `subjectsWithProperty` value (`id` in this example) must exist in every item of the array
+- DataFilter filters the data before rendering, so no `hide` actions are needed in templates
+- All filter conditions use `orConditions` with an empty/"all" check first, allowing "show all" when filters are empty or set to "all"
+- For select elements, prefer using a special value like `"all"` instead of empty strings to avoid UI issues
+- For text inputs, empty strings (`""`) work fine for the "show all" condition
+- When using `contains` for text search, always wrap the condition in `andConditions` with `isNotEmpty` checks to avoid errors with empty values
+