@ea-lab/reactive-json-docs 0.8.0 → 1.0.0

package/public/rjbuild/docs/advanced-concepts/plugins/plugin-system.yaml

@@ -1,7 +1,7 @@
 renderView:
   - type: Markdown
     content: |
-      # Plugin System Guide
+      # Plugin system guide
 
       ## Overview
 
@@ -124,6 +124,57 @@ renderView:
 
   - type: Markdown
     content: |
+      ### Component Override Behavior
+
+      When using `mergeComponentCollections` with multiple plugins, **the last component with a given name takes precedence**. This allows you to override default components with custom implementations.
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      import { ReactiveJsonRoot, mergeComponentCollections } from "@ea-lab/reactive-json";
+      import { defaultComponents } from "@ea-lab/reactive-json";
+      import { customComponents } from "./plugins/customComponents.js";
+
+      const plugins = mergeComponentCollections([
+          defaultComponents,    // Contains a "Button" component
+          customComponents      // Also contains a "Button" component - this one will be used
+      ]);
+
+  - type: Markdown
+    content: |
+      This override mechanism is particularly useful for:
+
+      - **Customizing default components**: Replace built-in components with your own implementations
+      - **Theme customization**: Override components to match your design system
+      - **Feature enhancement**: Add functionality to existing components
+      - **Third-party integration**: Replace components with versions from external libraries
+
+      **Example: Overriding a Default Button**
+
+  - type: SyntaxHighlighter
+    language: jsx
+    content: |
+      // Default plugin has a basic Button
+      const defaultPlugin = {
+          element: {
+              Button: BasicButton  // Simple button implementation
+          }
+      };
+
+      // Your custom plugin overrides it
+      const customPlugin = {
+          element: {
+              Button: EnhancedButton  // Button with animations and custom styling
+          }
+      };
+
+      // EnhancedButton will be used everywhere "Button" is referenced
+      const plugins = mergeComponentCollections([defaultPlugin, customPlugin]);
+
+  - type: Markdown
+    content: |
+      **⚠️ Important**: Component names must match exactly (case-sensitive) for the override to work. The order in the `mergeComponentCollections` array determines precedence.
+
       ### Custom ReactiveJsonRoot Wrapper
 
       Creating a custom wrapper allows you to **centralize plugin inclusion** across your entire application. Instead of manually importing and merging plugins in every component that uses Reactive-JSON, you define them once in a wrapper component.
@@ -193,6 +244,7 @@ renderView:
       2. **Use descriptive names** for components and plugins
       3. **Document component props** and usage patterns
       4. **Provide examples** for complex components
-      5. **Choose non-conflicting names** with existing components
+      5. **Be intentional with component names** - use unique names unless you specifically want to override existing components
+      6. **Document overrides** when replacing default components to help other developers understand the customization
 
 templates:

package/public/rjbuild/docs/core/action/Attribute/SetAttributeValue.md

@@ -1,5 +1,7 @@
 # SetAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [setAttributeValue transformer](../../attributeTransformer/setAttributeValue.md).
+
 Dynamically sets or modifies the value of an HTML attribute on an element.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/SetAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # SetAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [setAttributeValue transformer](../../attributeTransformer/setAttributeValue).
+
       Dynamically sets or modifies the value of an HTML attribute on an element.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/ToggleAttributeValue.md

@@ -1,5 +1,7 @@
 # ToggleAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [toggleAttributeValue transformer](../../attributeTransformer/toggleAttributeValue.md).
+
 Toggles the presence of a specific value in an HTML attribute. Supports both simple on-off toggles and cyclic toggling through multiple values.
 
 ## Important Notes

package/public/rjbuild/docs/core/action/Attribute/ToggleAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # ToggleAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [toggleAttributeValue transformer](../../attributeTransformer/toggleAttributeValue).
+
       Toggles the presence of a specific value in an HTML attribute. Supports both simple on-off toggles and cyclic toggling through multiple values.
 
       ## Important Notes

package/public/rjbuild/docs/core/action/Attribute/UnsetAttribute.md

@@ -1,5 +1,7 @@
 # UnsetAttribute
 
+> **Alternative**: For pre-render attribute modification, see the [unsetAttribute transformer](../../attributeTransformer/unsetAttribute.md).
+
 Completely removes an HTML attribute from an element.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttribute.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # UnsetAttribute
 
+      > **Alternative**: For pre-render attribute modification, see the [unsetAttribute transformer](../../attributeTransformer/unsetAttribute).
+
       Completely removes an HTML attribute from an element.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttributeValue.md

@@ -1,5 +1,7 @@
 # UnsetAttributeValue
 
+> **Alternative**: For pre-render attribute modification, see the [unsetAttributeValue transformer](../../attributeTransformer/unsetAttributeValue.md).
+
 Removes a specific value from an HTML attribute while preserving other values.
 
 ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/UnsetAttributeValue.yaml

@@ -3,6 +3,8 @@ renderView:
     content: |
       # UnsetAttributeValue
 
+      > **Alternative**: For pre-render attribute modification, see the [unsetAttributeValue transformer](../../attributeTransformer/unsetAttributeValue).
+
       Removes a specific value from an HTML attribute while preserving other values.
 
       ## Basic Syntax

package/public/rjbuild/docs/core/action/Attribute/index.md

@@ -0,0 +1,121 @@
+# Attribute Actions
+
+> **Note**: Reactive-JSON provides two systems for attribute modification:
+> 
+> - **Attribute Actions** (this section): Execute **after rendering**, modify DOM attributes directly
+> - **[Attribute Transformers](../../attributeTransformer/index.md)**: Execute **before rendering**, modify attributes for child components
+> 
+> Choose actions for post-render DOM manipulation and transformers for pre-render attribute conditioning.
+
+Attribute Actions in Reactive-JSON allow you to modify element attributes after rendering based on dynamic conditions. They are evaluated continuously based on data state and provide direct DOM manipulation capabilities.
+
+## Key Differences from Transformers
+
+- **Timing**: Attribute actions execute **after rendering**, while transformers execute **before rendering**
+- **Impact**: Actions modify the DOM directly, transformers affect attributes passed to child components
+- **Use case**: Actions are ideal for imperative DOM updates that don't need to affect child component props
+
+## Available Attribute Actions
+
+### Value Management
+- **[SetAttributeValue](./SetAttributeValue.md)**: Sets or modifies HTML attribute values dynamically after rendering
+- **[UnsetAttributeValue](./UnsetAttributeValue.md)**: Removes specific values from HTML attributes while preserving others
+- **[ToggleAttributeValue](./ToggleAttributeValue.md)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+### Attribute Management
+- **[UnsetAttribute](./UnsetAttribute.md)**: Completely removes HTML attributes after rendering
+
+## Basic Usage
+
+Attribute actions are defined in the `actions` array on any element:
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      class: "base-class"
+      data-status: "default"
+    actions:
+      # Add class conditionally
+      - what: SetAttributeValue
+        name: "class"
+        value: "active"
+        when: ~~.isActive
+        is: true
+      
+      # Remove attribute entirely
+      - what: UnsetAttribute
+        name: "data-status"
+        when: ~~.hideStatus
+        is: true
+      
+      # Toggle between states
+      - what: ToggleAttributeValue
+        name: "class"
+        value: ["theme-light", "theme-dark"]
+        when: ~~.toggleTheme
+        isNotEmpty:
+```
+
+## Execution Order
+
+Attribute actions are applied based on data changes and re-evaluated when dependencies change:
+
+1. Component renders with base attributes
+2. Actions are evaluated based on current data state
+3. DOM attributes are modified directly
+4. Changes are applied to the live DOM element
+
+## Conditional Execution
+
+All attribute actions support the same conditional system as other actions:
+
+- **`when`**: Specifies the data value to evaluate
+- **`is`**: Exact value comparison
+- **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
+- **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns
+
+## Common Patterns
+
+### Conditional Styling
+```yaml
+actions:
+  - what: SetAttributeValue
+    name: "class"
+    value: "error"
+    when: ~~.validation.hasErrors
+    is: true
+```
+
+### State-based Attributes
+```yaml
+actions:
+  - what: ToggleAttributeValue
+    name: "aria-expanded"
+    value: "true"
+    when: ~~.menu.isOpen
+    is: true
+```
+
+### Dynamic Data Attributes
+```yaml
+actions:
+  - what: SetAttributeValue
+    name: "data-user-role"
+    value: ~~.currentUser.role
+    mode: "replace"
+```
+
+## When to Use Actions vs Transformers
+
+### Use Attribute Actions when:
+- You need to modify DOM attributes after the component has rendered
+- You're working with imperative DOM updates
+- You need to interact with external libraries that read DOM attributes
+- The attribute changes don't need to affect child component behavior
+
+### Use Attribute Transformers when:
+- You need attributes to be available to child components
+- You're doing conditional attribute setup before rendering
+- You want predictable attribute values during the render phase
+- You're building reusable components that depend on specific attributes

package/public/rjbuild/docs/core/action/Attribute/index.yaml

@@ -0,0 +1,77 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Attribute Actions
+
+      > **Note**: Reactive-JSON provides two systems for attribute modification:
+      > 
+      > - **Attribute Actions** (this section): Execute **after rendering**, modify DOM attributes directly
+      > - **[Attribute Transformers](../../attributeTransformer/index)**: Execute **before rendering**, modify attributes for child components
+      > 
+      > Choose actions for post-render DOM manipulation and transformers for pre-render attribute conditioning.
+
+      Attribute Actions in Reactive-JSON allow you to modify element attributes after rendering based on dynamic conditions. They are evaluated continuously based on data state and provide direct DOM manipulation capabilities.
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      renderView:
+        - type: div
+          attributes:
+            class: "base-class"
+            data-status: "default"
+          actions:
+            # Add class conditionally
+            - what: SetAttributeValue
+              name: "class"
+              value: "active"
+              when: ~~.isActive
+              is: true
+            
+            # Remove attribute entirely
+            - what: UnsetAttribute
+              name: "data-status"
+              when: ~~.hideStatus
+              is: true
+            
+            # Toggle between states
+            - what: ToggleAttributeValue
+              name: "class"
+              value: ["theme-light", "theme-dark"]
+              when: ~~.toggleTheme
+              isNotEmpty:
+
+  - type: Markdown
+    content: |
+      ## Key Differences from Transformers
+
+      - **Timing**: Attribute actions execute **after rendering**, while transformers execute **before rendering**
+      - **Impact**: Actions modify the DOM directly, transformers affect attributes passed to child components
+      - **Use case**: Actions are ideal for imperative DOM updates that don't need to affect child component props
+
+      ## Available Attribute Actions
+
+      ### Value Management
+      - **[SetAttributeValue](./SetAttributeValue)**: Sets or modifies HTML attribute values dynamically after rendering
+      - **[UnsetAttributeValue](./UnsetAttributeValue)**: Removes specific values from HTML attributes while preserving others
+      - **[ToggleAttributeValue](./ToggleAttributeValue)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+      ### Attribute Management
+      - **[UnsetAttribute](./UnsetAttribute)**: Completely removes HTML attributes after rendering
+
+      ## Execution Order
+
+      Attribute actions are applied based on data changes and re-evaluated when dependencies change:
+
+      1. Component renders with base attributes
+      2. Actions are evaluated based on current data state
+      3. DOM attributes are modified directly
+      4. Changes are applied to the live DOM element
+
+      ## Conditional Execution
+
+      All attribute actions support the same conditional system as other actions:
+
+      - **`when`**: Specifies the data value to evaluate
+      - **`is`**: Exact value comparison
+      - **`isEmpty`/`isNotEmpty`**: Empty/non-empty checks
+      - **Template evaluation**: Full support for `~.`, `~~.`, `~>`, `~~>` patterns

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

@@ -0,0 +1,17 @@
+# Attribute Transformers
+
+> **Note**: Don't confuse with [Attribute Actions](../action/Attribute/index.md). Attribute Transformers execute **before rendering** and modify attributes for child components, while Attribute Actions execute **after rendering** and modify the DOM directly.
+
+Attribute Transformers allow you to dynamically modify element attributes before rendering, based on conditions from the application state.
+
+> **For detailed usage, examples, and extensibility information**, see **[Attribute Transformers Advanced Guide](../../advanced-concepts/attribute-transformers.md)**.
+
+## Available Attribute Transformers
+
+### Value Management
+- **[setAttributeValue](./setAttributeValue.md)**: Sets or modifies HTML attribute values dynamically before rendering
+- **[unsetAttributeValue](./unsetAttributeValue.md)**: Removes specific values from HTML attributes while preserving others
+- **[toggleAttributeValue](./toggleAttributeValue.md)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+### Attribute Management
+- **[unsetAttribute](./unsetAttribute.md)**: Completely removes HTML attributes before rendering

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

@@ -0,0 +1,24 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Attribute Transformers
+
+      > **Note**: Don't confuse with [Attribute Actions](../action/Attribute/index). Attribute Transformers execute **before rendering** and modify attributes for child components, while Attribute Actions execute **after rendering** and modify the DOM directly.
+
+      Attribute Transformers allow you to dynamically modify element attributes before rendering, based on conditions from the application state.
+
+      > **For detailed usage, examples, and extensibility information**, see **[Attribute Transformers Advanced Guide](../../advanced-concepts/attribute-transformers)**.
+
+      ## Available Attribute Transformers
+
+      ### Value Management
+      - **[setAttributeValue](./setAttributeValue)**: Sets or modifies HTML attribute values dynamically before rendering
+      - **[unsetAttributeValue](./unsetAttributeValue)**: Removes specific values from HTML attributes while preserving others
+      - **[toggleAttributeValue](./toggleAttributeValue)**: Toggles the presence of specific values in HTML attributes, supports cyclic toggling
+
+      ### Attribute Management
+      - **[unsetAttribute](./unsetAttribute)**: Completely removes HTML attributes before rendering
+
+data:
+  page_title: "Attribute Transformers - Reactive-JSON Documentation"
+

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

@@ -0,0 +1,101 @@
+# setAttributeValue
+
+> **Alternative**: For post-render DOM modification, see the [SetAttributeValue action](../action/Attribute/SetAttributeValue.md).
+
+Dynamically sets or modifies the value of an HTML attribute before rendering. This attribute transformer allows you to conditionally modify attributes based on data state during the evaluation phase.
+
+## Basic Syntax
+
+```yaml
+attributeTransforms:
+  # Add CSS class
+  - what: setAttributeValue
+    name: "class"
+    value: "active"
+    
+  # Replace attribute value
+  - what: setAttributeValue
+    name: "data-status"
+    mode: "replace"
+    value: ~.currentStatus
+```
+
+## 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).
+  - `"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).
+
+## Behavior
+
+- **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.
+
+## 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.
+
+## Example
+
+```yaml
+renderView:
+  - type: input
+    attributes:
+      type: "text"
+      placeholder: "Type to see conditional styling..."
+      class: "base-input"
+      value: ~.input_data
+      style:
+        padding: "10px"
+        border: "2px solid #007bff"
+        borderRadius: "4px"
+        fontSize: "16px"
+        margin: "10px 0"
+        width: "300px"
+        display: "block"
+    attributeTransforms:
+      - what: setAttributeValue
+        name: "class"
+        value: "highlighted"
+        when: ~.input_data
+        isNotEmpty:
+    actions:
+      - what: setData
+        on: change
+        path: ~.input_data
+        value: <reactive-json:event-new-value>
+
+  - type: div
+    content: ["Current value: ", ~.input_data]
+
+  - type: style
+    content: |
+      .base-input {
+        transition: border-color 0.3s ease;
+      }
+      .highlighted {
+        border-color: #28a745 !important;
+        outline: 2px solid #28a745 !important;
+        outline-offset: 2px !important;
+      }
+
+data:
+  input_data: ""
+```
+
+## 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.
+- **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.).

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

@@ -0,0 +1,144 @@
+renderView:
+  - type: Markdown
+    content: |
+      # setAttributeValue
+
+      > **Alternative**: For post-render DOM modification, see the [SetAttributeValue action](../action/Attribute/SetAttributeValue).
+
+      Dynamically sets or modifies the value of an HTML attribute on an element.
+
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      attributeTransforms:
+        # Add CSS class
+        - what: setAttributeValue
+          name: "class"
+          value: "active"
+          
+        # Replace attribute value
+        - what: setAttributeValue
+          name: "data-status"
+          mode: "replace"
+          value: ~.currentStatus
+
+  - type: Markdown
+    content: |
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: name
+          after: "(string, required)"
+        details: The name of the attribute to modify.
+      - term:
+          code: mode
+          after: "(string, optional)"
+        details: 
+          type: Markdown
+          content: |
+            The modification mode. Default: `"append"`
+            - `"append"`: Adds the value to the existing attribute value (space-separated)
+            - `"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.
+      - term:
+          code: preventDuplicateValues
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: When `true` (default), prevents duplicate values when using append mode.
+      - term:
+          code: separator
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            The separator used between values. Default: `" "` (space).
+
+  - type: Markdown
+    content: |
+
+      ## Behavior
+
+      - **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.
+
+      ## 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.
+
+  - type: RjBuildDescriber
+    title: "SetAttributeValue Action Examples"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to use the `SetAttributeValue` action to dynamically add CSS classes based on input content.
+          
+          **Expected behavior:**
+          - Initially, the input field has normal appearance (base styling)
+          - Start typing in the input field
+          - When the field is not empty, the 'sav-highlighted' class is automatically added (visual highlighting)
+          - Clear the field to remove the highlighting
+          - The action uses append mode and responds to the `isNotEmpty` condition
+          
+          Try typing and clearing the input to see how the class attribute changes automatically.
+
+    toDescribe:
+      renderView:
+        - type: input
+          attributes:
+            type: "text"
+            placeholder: "Start typing to see the highlighting..."
+            class: "sav-demo-input"
+            value: ~.input_data
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              borderRadius: "4px"
+              fontSize: "16px"
+              margin: "10px 0"
+              width: "300px"
+              display: "block"
+          actions:
+            - what: setData
+              on: change
+              path: ~.input_data
+              value: <reactive-json:event-new-value>
+          attributeTransforms:
+            - what: setAttributeValue
+              name: "class"
+              value: "sav-highlighted"
+              when: ~.input_data
+              isNotEmpty:
+
+        - type: div
+          content: ~.input_data
+
+        - type: style
+          content: |
+            .sav-highlighted {
+              border-color: #28a745 !important;
+              outline: 2px solid #28a745 !important;
+              outline-offset: 2px !important;
+            }
+
+      data:
+        input_data: ""
+
+  - 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.