@ea-lab/reactive-json-docs 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "0.4.0",
+  "version": "0.6.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": "^0.3.1",
+    "@ea-lab/reactive-json": "^0.5.0",
     "@ea-lab/reactive-json-chartjs": "^0.0.23",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",
@@ -75,5 +75,8 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "dependencies": {
+    "remark-gfm": "^4.0.1"
   }
 }

package/public/rjbuild/docs/advanced-concepts/index.md

@@ -6,4 +6,5 @@ This section covers advanced features and concepts in Reactive-JSON that enable
 
 - **[Data Mapping](data-mapping.md)**: Learn how to selectively dispatch and transform response data using the Data Mapping system
 - **[Data Processors](data-processors.md)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system
+- **[Forward Update](forward-update.md)**: Implementation details about the retrieval of event values.
 - **[Plugins](plugins/index.md)**: Learn how to extend Reactive-JSON with custom components and plugins.

package/public/rjbuild/docs/advanced-concepts/index.yaml

@@ -9,6 +9,7 @@ renderView:
 
       - **[Data Mapping](data-mapping)**: Learn how to selectively dispatch and transform response data using the Data Mapping system.
       - **[Data Processors](data-processors)**: Learn how to intercept and modify data from HTTP requests using the DataProcessor system.
+      - **[Forward Update](forward-update)**: Implementation details about the retrieval of event values.
       - **[Plugins](plugins/index)**: Learn how to extend Reactive-JSON with custom components and plugins.
 
 data:

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.md

@@ -19,7 +19,7 @@ All components have access to these React contexts:
 - **TemplateContext**: Contains current template data for evaluation
 
 Other specialized contexts are available.
-- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+- **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
 - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
 ## Basic Element Component

package/public/rjbuild/docs/advanced-concepts/plugins/component-development.yaml

@@ -22,7 +22,7 @@ renderView:
       - **TemplateContext**: Contains current template data for evaluation
 
       Other specialized contexts are available.
-      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/core/reaction/index).
+      - **EventDispatcherContext**: Centralized event handling system, mostly used by the [reaction system](/docs/getting-started/reactions).
       - **PaginationContext**: Used by components that integrate pagination, such as [Switch](/docs/core/element/special/Switch).
 
       ## Basic Element Component

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

@@ -0,0 +1,93 @@
+# SetAttributeValue
+
+Dynamically sets or modifies the value of an HTML attribute on an element.
+
+## Basic Syntax
+
+```yaml
+actions:
+  # 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: "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>
+      - 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: ""
+```
+
+## 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.

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

@@ -0,0 +1,141 @@
+renderView:
+  - type: Markdown
+    content: |
+      # SetAttributeValue
+
+      Dynamically sets or modifies the value of an HTML attribute on an element.
+
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      actions:
+        # 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>
+            - 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.

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

@@ -0,0 +1,267 @@
+# 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
+
+### Action-Based Behavior
+`ToggleAttributeValue` is an **action component** that operates based on data state changes, not direct event triggers. It requires a state variable in your data to activate the toggle behavior. This means you cannot directly use `on: click` with `ToggleAttributeValue` - instead, you must use `setData` with `on: click` to change a state variable, then use `when/is` conditions on the toggle action to respond to that state change.
+
+### Base Attribute Detection
+`ToggleAttributeValue` determines what to toggle by examining the **original attributes** defined in your component's props, not the current DOM state. This means:
+
+- ✅ **Stable behavior**: The toggle always works relative to the initial attribute values
+- ✅ **No infinite loops**: Changes don't trigger recursive re-evaluation
+- ⚠️ **Limitation**: The toggle cannot detect or work with values that were dynamically added by other attribute actions (`SetAttributeValue`, `UnsetAttributeValue`)
+
+**Example**: If your component initially has `class="base"` and another action adds `"dynamic"`, the toggle will only work with `"base"` and won't see `"dynamic"`.
+
+## Basic Syntax
+
+```yaml
+actions:
+  # Toggle CSS class.
+  - what: toggleAttributeValue
+    name: "class"
+    value: "active"
+    
+  # Cyclic toggle with array.
+  - what: toggleAttributeValue
+    name: "class"
+    value: ["theme-light", "theme-dark", "theme-auto", ""]
+    
+  # Keep attribute when empty.
+  - what: toggleAttributeValue
+    name: "data-optional"
+    value: "enabled"
+    keepAttributeWhenEmpty: true
+    
+  # Conditional toggle.
+  - what: toggleAttributeValue
+    name: "data-features"
+    value: ~.featureName
+    when: ~.shouldToggle
+    is: true
+```
+
+## Properties
+
+- **keepAttributeWhenEmpty** *(boolean, optional)*: Whether to keep the attribute when it becomes empty. If `false`, the attribute is removed when no values remain. Default: `false`.
+- **name** *(string, required)*: The name of the attribute to modify.
+- **separator** *(string, optional)*: The separator used between values. Default: `" "` (space).
+- **value** *(string|array, required)*: The value(s) to toggle in the attribute. Can be a single string or an array of strings for cyclic toggling. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already.
+
+## Behavior
+
+### Simple Toggle (string value)
+- **Smart toggle**: Automatically adds the value if missing, removes it if present.
+- **Preservation**: Other values in the attribute remain intact.
+- **Empty handling**: By default, removes the entire attribute if no values remain. Set `keepAttributeWhenEmpty` to `true` to preserve empty attributes.
+
+#### Common Examples
+```yaml
+# Toggle CSS class.
+- what: toggleAttributeValue
+  name: "class"
+  value: "active"
+
+# Toggle readonly attribute.
+- what: toggleAttributeValue
+  name: "readonly"
+  value: "readonly"
+
+# Toggle checked attribute.
+- what: toggleAttributeValue
+  name: "checked"
+  value: "checked"
+```
+
+### Cyclic Toggle (array value)
+- **Cyclic behavior**: When `value` is an array, the action cycles through the values in order.
+- **Sequential rotation**: Each toggle moves to the next value in the array.
+- **Empty values handling**: Empty strings (`""`) in the array represent the absence of the value.
+- **Clean detection**: Values are split by separator and empty values (from double separators) are filtered out during detection.
+- **First match priority**: If multiple array values are already present, only the first detected value is replaced.
+- **Default fallback**: If no array values are present, the first array value is applied.
+- **Empty value filtering**: Attributes with empty values from double separators (e.g., `"val1,,val2,"`) are cleaned during detection, treating them as `"val1 val2"`.
+- **Single value arrays**: Arrays with one value behave identically to string values (toggle between value and empty).
+- **Empty string inclusion**: Including `""` in arrays explicitly defines an "empty state" in the cycle.
+
+#### Array Behavior Examples
+
+##### Four-step cycle with empty state
+```yaml
+# Starting with class="theme-light"
+# Clicks will progress: theme-light → theme-dark → theme-auto → "" → theme-light → ...
+value: ["theme-light", "theme-dark", "theme-auto", ""]
+```
+
+##### Simple alternation
+```yaml
+# Starting with class="size-small"
+# Clicks will alternate: size-small → size-large → size-small → ...
+value: ["size-small", "size-large"]
+```
+
+##### Single value array (equivalent to string)
+```yaml
+# Equivalent to value: "highlight"
+# Toggles: highlight → "" → highlight → ...
+value: ["highlight"]
+```
+
+## Common Use Cases
+
+- **CSS class toggling**: Adding/removing CSS classes based on state changes.
+- **Data attribute management**: Toggling specific values in space-separated data attributes.
+- **Interactive styling**: Toggle styling classes for user interactions.
+- **Feature flags**: Toggle feature-related classes or data attributes.
+- **State cycling**: Cycle through multiple states (e.g., theme variants, size options).
+- **Multi-step processes**: Progress through sequential steps with visual indicators.
+
+## Examples
+
+### Simple Toggle (string value)
+```yaml
+renderView:
+  - type: button
+    content: "Toggle 'active' class"
+    actions:
+      - what: setData
+        on: click
+        path: ~.toggleActive
+        value: "yes"
+        when: ~.toggleActive
+        is: "no"
+      - what: setData
+        on: click
+        path: ~.toggleActive
+        value: "no"
+        when: ~.toggleActive
+        is: "yes"
+
+  - type: div
+    content: "Element that toggles classes based on state"
+    attributes:
+      class: "base-class"
+      style:
+        padding: "10px"
+        border: "1px solid #ccc"
+        margin: "10px 0"
+    actions:
+      - what: toggleAttributeValue
+        name: "class"
+        value: "active"
+        when: ~.toggleActive
+        is: "yes"
+
+data:
+  toggleActive: "no"
+```
+
+### Keep Attribute When Empty
+```yaml
+renderView:
+  - type: button
+    content: "Toggle data attribute (keeps when empty)"
+    actions:
+      - what: setData
+        on: click
+        path: ~.toggleFeature
+        value: "yes"
+        when: ~.toggleFeature
+        is: "no"
+      - what: setData
+        on: click
+        path: ~.toggleFeature
+        value: "no"
+        when: ~.toggleFeature
+        is: "yes"
+
+  - type: div
+    content: "Element with preserved attribute"
+    attributes:
+      data-feature: "enabled"
+      style:
+        padding: "10px"
+        border: "1px solid #999"
+        margin: "10px 0"
+    actions:
+      - what: toggleAttributeValue
+        name: "data-feature"
+        value: "enabled"
+        keepAttributeWhenEmpty: true
+        when: ~.toggleFeature
+        is: "yes"
+
+data:
+  toggleFeature: "no"
+```
+
+### Cyclic Toggle (array value)
+```yaml
+renderView:
+  - type: button
+    content: "Cycle through themes"
+    actions:
+      - what: setData
+        on: click
+        path: ~.cycleThemes
+        value: "yes"
+        when: ~.cycleThemes
+        is: "no"
+      - what: setData
+        on: click
+        path: ~.cycleThemes
+        value: "no"
+        when: ~.cycleThemes
+        is: "yes"
+
+  - type: div
+    content: "Element that cycles through theme classes"
+    attributes:
+      class: "theme-light"
+    actions:
+      - what: toggleAttributeValue
+        name: "class"
+        value: ["theme-light", "theme-dark", "theme-auto", ""]
+        when: ~.cycleThemes
+        is: "yes"
+
+  - type: button
+    content: "Alternate between sizes"
+    actions:
+      - what: setData
+        on: click
+        path: ~.alternateSizes
+        value: "yes"
+        when: ~.alternateSizes
+        is: "no"
+      - what: setData
+        on: click
+        path: ~.alternateSizes
+        value: "no"
+        when: ~.alternateSizes
+        is: "yes"
+
+  - type: div
+    content: "Element that alternates between size classes"
+    attributes:
+      class: "size-small"
+    actions:
+      - what: toggleAttributeValue
+        name: "class"
+        value: ["size-small", "size-large"]
+        when: ~.alternateSizes
+        is: "yes"
+
+data:
+  cycleThemes: "no"
+  alternateSizes: "no"
+```
+
+## Notes
+
+- The `value` property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.
+- More efficient than separate SetAttributeValue/UnsetAttributeValue actions for toggle scenarios.
+- Works with any space-separated attribute values (class, data attributes, etc.).