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

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

@@ -0,0 +1,185 @@
+renderView:
+  - type: Markdown
+    content: |
+      # UnsetAttributeValue
+
+      Removes a specific value from an HTML attribute while preserving other values.
+
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      actions:
+        # Remove CSS class
+        - what: unsetAttributeValue
+          name: "class"
+          value: "highlighted"
+          
+        # Remove with template
+        - what: unsetAttributeValue
+          name: "data-tags"
+          value: ~.tagToRemove
+
+  - type: Markdown
+    content: |
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: name
+          after: "(string, required)"
+        details: The name of the attribute to modify.
+      - term:
+          code: separator
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: |
+            The separator used between values. Default: `" "` (space).
+      - term:
+          code: unsetAllOccurrences
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: |
+            When `true` (default), removes all occurrences of the value from the attribute. When `false`, removes the number of elements defined by `unsetCount`.
+      - term:
+          code: unsetCount
+          after: "(number, optional)"
+        details:
+          type: Markdown
+          content: |
+            Specifies the number of objects to remove. Supports template evaluation and is cast to integer. When `0`, removes nothing. When `1` or more, removes the specified number of elements starting from the beginning of the string. When `-1` or less, removes the specified number of elements starting from the end of the string. When undefined or invalid, defaults to removing all occurrences (equivalent to `unsetAllOccurrences: true`).
+      - term:
+          code: value
+          after: "(string, required)"
+        details:
+          type: Markdown
+          content: |
+            The value to remove from the attribute. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already.
+
+  - type: Markdown
+    content: |
+      ## Behavior
+
+      - **Selective removal**: Removes only the specified value from the attribute.
+      - **Occurrence control**: Removes all occurrences by default, or only the first when configured.
+      - **Count control**: When `unsetCount` is specified, controls the exact number of elements to remove and the direction (from beginning or end).
+      - **Preservation**: Other values in the attribute remain intact.
+
+      ## Logic Reference
+
+      ### Behavior Matrix
+
+      | `unsetAllOccurrences` | `unsetCount` | Behavior | Notes |
+      |:---------------------:|:------------:|:---------|:------|
+      | `true` | *ignored* | **Removes ALL occurrences** | `unsetCount` is completely ignored |
+      | `false` | `1` | Removes **1 occurrence** from beginning | Default behavior when `unsetCount` is valid |
+      | `false` | `2` | Removes **2 occurrences** from beginning | |
+      | `false` | `-1` | Removes **1 occurrence** from end | |
+      | `false` | `-2` | Removes **2 occurrences** from end | |
+      | `false` | `0` | **Removes nothing** | |
+      | `false` | `undefined` | **Removes ALL occurrences** | Fallback to "all" behavior |
+      | `false` | `null` | **Removes ALL occurrences** | Fallback to "all" behavior |
+      | `false` | `"invalid"` | **Removes ALL occurrences** | Fallback to "all" behavior |
+      | `undefined` | `1` | Removes **1 occurrence** from beginning | `unsetAllOccurrences` defaults to `true`, but valid `unsetCount` applies |
+      | `undefined` | `-1` | Removes **1 occurrence** from end | |
+      | `undefined` | `0` | **Removes nothing** | |
+      | `undefined` | `undefined` | **Removes ALL occurrences** | Complete default behavior |
+
+      ### Logic Summary
+
+      1. **If `unsetAllOccurrences: true`** → removes ALL, ignores `unsetCount`
+      2. **If `unsetAllOccurrences: false` AND `unsetCount` valid** → uses `unsetCount`
+      3. **If `unsetCount` invalid/undefined** → fallback to "remove ALL" even if `unsetAllOccurrences: false`
+      4. **If nothing is defined** → default behavior = "remove ALL"
+
+      This logic ensures there is always a defined behavior, with an intelligent fallback to "remove all" when parameters are invalid.
+
+      ## Common Use Cases
+
+      - **CSS class removal**: Removing specific CSS classes while keeping others.
+      - **Data attribute cleanup**: Removing specific values from space-separated data attributes.
+      - **Conditional styling**: Removing styling classes based on state changes.
+
+  - type: RjBuildDescriber
+    title: "UnsetAttributeValue Action Examples"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to selectively remove specific CSS classes using the `UnsetAttributeValue` action.
+          
+          **Expected behavior:**
+          - Initially, the input field has both 'readonly' and 'highlighted' classes (readonly + visual styling)
+          - Click "Remove 'highlighted' class" to remove only the 'highlighted' class (removing visual styling but keeping readonly)
+          - Click "Reset" to restore the original classes
+          - Notice how only the specified value is removed while other classes remain intact
+          
+          Try interacting with the buttons to see how specific classes are selectively removed.
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Remove 'highlighted' class"
+          actions:
+            - what: setData
+              on: click
+              path: ~.removeHighlight
+              value: true
+              stopPropagation: true
+
+        - type: button
+          content: "Reset"
+          actions:
+            - what: setData
+              on: click
+              path: ~.removeHighlight
+              value: false
+              stopPropagation: true
+
+        - type: input
+          attributes:
+            type: "text"
+            value: "This input has multiple classes..."
+            class: "uav-readonly uav-highlighted"
+            readonly: "readonly"
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              borderRadius: "4px"
+              fontSize: "16px"
+              margin: "10px 0"
+              width: "300px"
+              display: "block"
+          actions:
+            - what: unsetAttributeValue
+              name: "class"
+              value: "uav-highlighted"
+              when: ~.removeHighlight
+              is: true
+
+        - type: style
+          content: |
+            .uav-readonly {
+              cursor: not-allowed !important;
+              opacity: 0.7 !important;
+            }
+            .uav-highlighted {
+              border-color: #ffc107 !important;
+              outline: 2px solid #ffc107 !important;
+              outline-offset: 2px !important;
+            }
+
+      data:
+        removeHighlight: false
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - Only removes exact matches of the specified value.
+      - Maintains the integrity of other attribute values.
+      - Works with any space-separated attribute values.
+      - Safe to use even if the value doesn't exist in the attribute.
+      - The value property supports full template evaluation including `~.localData`, `~~.globalData`, `~>nearestKey`, and `~~>globalKey` patterns.

package/public/rjbuild/docs/core/action/Hide.md

@@ -19,4 +19,4 @@ renderView:
 ```
 
 ## Limitation
-- The element no longer exists in the DOM, so no events can be attached to it. 
+- When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/docs/core/action/Hide.yaml

@@ -30,31 +30,31 @@ renderView:
               actions:
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: false
+                  path: ~.shouldHide
+                  value: "true"
+                  when: ~.shouldHide
+                  is: "false"
                 - what: setData
                   on: click
-                  path: "shouldHide"
-                  value: ~.shouldHide
-                  is: true
+                  path: ~.shouldHide
+                  value: "false"
                   when: ~.shouldHide
-                  is: false
+                  is: "true"
 
             - type: div
               content: "This text will be hidden when shouldHide is true."
               actions:
                 - what: hide
                   when: ~.shouldHide
-                  is: true
+                  is: "true"
 
             - type: div
               content: ["Current state: shouldHide = ", ~.shouldHide]
 
       data:
-        shouldHide: false
+        shouldHide: "false"
 
   - type: Markdown
     content: |
       ## Limitation
-      - The element no longer exists in the DOM, so no events can be attached to it. 
+      - When hidden, the element no longer exists in the DOM, so no events can be attached to it. 

package/public/rjbuild/docs/core/action/ReactOnEvent.md

@@ -1,8 +1,8 @@
 # ReactOnEvent
 
-**Type**: Internal Action Component
+ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
 
-**Description**: ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
+> **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
 ## How it Works
 
@@ -43,8 +43,8 @@ ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the
 
 Some events have special handling and **do not** use ReactOnEvent:
 
-- `on: "message"` → Uses MessageListener component (listens on window)
-- `on: "hashchange"` → Uses HashChangeListener component (listens on window)
+- `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+- `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
 
 ## Event Propagation Control
 
@@ -67,15 +67,15 @@ actions:
 - **Context preservation**: Maintains access to global and template data contexts
 - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
+## Important Notes
+
+- **Never use `type: ReactOnEvent`** in your renderView - it's an internal component
+- **Use `actions` with `on: "eventName"`** - this is the correct way to handle events
+- **ReactOnEvent is automatically instantiated** by the Actions system when needed
+- **Event propagation is stopped by default** - use `stopPropagation: false` to change this
+
 ## Related Components
 
 - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
 - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
-- **[Reactions System](../reaction/index.md)**: The actual reaction functions that ReactOnEvent executes
-
-## Important Notes
-
-- **Not for direct use**: Never use `type: ReactOnEvent` in your renderView
-- **Automatic instantiation**: The Actions system creates this component automatically
-- **Internal implementation**: This is part of the framework's internal architecture
-- **Event binding**: Events are bound to the actual DOM elements, not wrapper components 
+- **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes

package/public/rjbuild/docs/core/action/ReactOnEvent.yaml

@@ -3,9 +3,9 @@ renderView:
     content: |
       # ReactOnEvent
 
-      **Type**: Internal Action Component
-
-      **Description**: ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected. It should **not** be used directly as an element type.
+      ReactOnEvent is an internal action component that is automatically instantiated by the Actions system when reactions with event handlers (`on: "eventName"`) are detected.
+      
+      > **Important**: It should **not** be used directly as an element type. The Reactive-JSON engine will automatically instantiate it when needed.
 
       ## How it Works
 
@@ -16,105 +16,66 @@ renderView:
       3. Creates a ReactOnEvent component that attaches the appropriate event listeners
       4. Wraps the target element with these event handlers
 
-  - type: RjBuildDescriber
-    title: "Correct Usage: Reactions with Events"
-    description:
-      - type: Markdown
-        content: |
-          This example shows the **correct** way to use event handling in Reactive-JSON. 
-          
-          ReactOnEvent is automatically created by the system when you use `on: "eventName"` in actions.
+      ## Usage Pattern
 
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Click me"
-              actions:
-                - what: setData
-                  on: click              # ReactOnEvent handles this automatically
-                  path: "clicked"
-                  value: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: 1
-                  when: ~.clickCount
-                  isEmpty: true
-                - what: setData
-                  on: click
-                  path: "clickCount"
-                  value: "~.clickCount + 1"
-                  when: ~.clickCount
-                  isEmpty: "not"
-                  
-            - type: input
-              props:
-                type: "text"
-                placeholder: "Type something..."
-              actions:
-                - what: setData
-                  on: change           # ReactOnEvent handles this automatically
-                  path: "inputValue"
-                  value: "~event.target.value"
-                  
-            - type: div
-              content: "Mouse over this area"
-              props:
-                style:
-                  padding: "10px"
-                  border: "1px solid #ccc"
-                  backgroundColor: "~.hovered ? '#f0f0f0' : 'white'"
-              actions:
-                - what: setData
-                  on: mouseover       # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: true
-                - what: setData
-                  on: mouseleave      # ReactOnEvent handles this automatically
-                  path: "hovered"
-                  value: false
-              
-        - type: div
-          content:
-            - type: div
-              content: ["Button clicked: ", ~.clicked]
-              
-            - type: div
-              content: ["Click count: ", ~.clickCount]
-              
-            - type: div
-              content: ["Input value: '", ~.inputValue, "'"]
-              
-            - type: div
-              content: ["Mouse hover state: ", ~.hovered]
+      Instead of using ReactOnEvent directly, you define reactions in the `actions` array of any element:
 
+      ```yaml
+      renderView:
         - type: button
-          content: "Reset all"
+          content: "Click me"
           actions:
             - what: setData
-              on: click
-              path: "clicked"
-              value: false
-            - what: setData
-              on: click
-              path: "clickCount"
-              value: 0
-            - what: setData
-              on: click
-              path: "inputValue"
-              value: ""
-            - what: setData
-              on: click
-              path: "hovered"
-              value: false
+              on: click           # This triggers ReactOnEvent internally
+              path: "buttonClicked"
+              value: true
+      ```
+
+      ## Supported Event Types
+
+      ReactOnEvent supports any DOM event by prefixing with `on` and capitalizing the first letter:
+
+      - `on: click` → `onClick`
+      - `on: change` → `onChange`
+      - `on: mouseover` → `onMouseOver`
+      - `on: keydown` → `onKeyDown`
+      - `on: submit` → `onSubmit`
+      - etc.
+
+      ## Special Event Handling
+
+      Some events have special handling and **do not** use ReactOnEvent:
+
+      - `on: "message"` → Uses the [MessageListener](MessageListener.md) component (listens on window)
+      - `on: "hashchange"` → Uses the [HashChangeListener](HashChangeListener.md) component (listens on window)
+
+      ## Event Propagation Control
+
+      By default, ReactOnEvent stops event propagation. You can control this behavior:
+
+      ```yaml
+      actions:
+        - what: setData
+          on: click
+          path: "clicked"
+          value: true
+          stopPropagation: false  # Allow event to continue propagating
+      ```
+
+      ## Event Placeholders
+
+      ReactOnEvent supports special placeholders to access event data:
+
+      - `<reactive-json:event-new-value>`: Returns the most relevant value from form events (checked for checkboxes, value for inputs)
+      - `<reactive-json:event>.propertyPath`: Access any event property (e.g., `.data.message` for MessageEvent, `.key` for KeyboardEvent)
+
+      ## Technical Implementation
 
-      data:
-        clicked: false
-        clickCount: 0
-        inputValue: ""
-        hovered: false
+      - **Event attachment**: Uses React's event system via `cloneElement`
+      - **Multiple events**: Can handle multiple event types on the same element
+      - **Reaction execution**: Executes reactions in the order they appear
+      - **Context preservation**: Maintains access to global and template data contexts
+      - **Early termination**: Supports `stopPropagation: true` to halt reaction chain execution
 
   - type: Markdown
     content: |
@@ -125,9 +86,8 @@ renderView:
       - **ReactOnEvent is automatically instantiated** by the Actions system when needed
       - **Event propagation is stopped by default** - use `stopPropagation: false` to change this
       
-      ## Related Documentation
+      ## Related Components
       
-      - **[Actions System](index.md)**: Learn about the actions system that uses ReactOnEvent
-      - **[Reactions](../reaction/index.md)**: The reaction functions that ReactOnEvent executes
-      - **[MessageListener](MessageListener.md)**: For `on: "message"` events
-      - **[HashChangeListener](HashChangeListener.md)**: For `on: "hashchange"` events 
+      - **[MessageListener](MessageListener.md)**: Handles `on: "message"` events
+      - **[HashChangeListener](HashChangeListener.md)**: Handles `on: "hashchange"` events
+      - **[Reactions System](../../getting-started/reactions.md)**: The actual reaction functions that ReactOnEvent executes 

package/public/rjbuild/docs/core/action/Redirect.md

@@ -6,14 +6,22 @@
 - `to`: destination URL
 
 ## Example
+
+The following example will redirect the current page when the user clicks on the button.
+
 ```yaml
 renderView:
   - type: button
-    content: "Go to Google"
+    content: "Go to EA Lab"
     actions:
       - what: redirect
-        to: "https://www.google.com"
+        to: "https://ea-lab.io"
+        when: ~~.allowRedirect
+        is: "true"
+      - what: setData
         on: click
+        path: ~~.allowRedirect
+        value: "true"
 ```
 
 ## Limitation

package/public/rjbuild/docs/core/action/Redirect.yaml

@@ -8,59 +8,26 @@ renderView:
       ## Properties
       - `to`: destination URL
 
-  - type: RjBuildDescriber
-    title: "Redirect Action Example"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the `redirect` action. **Warning**: clicking the button below will actually redirect you!
-          
-          For demonstration purposes, this redirects to a safe page (the current page), but in real usage you would specify any URL.
-
-    toDescribe:
-      renderView:
-        - type: div
-          content:
-            - type: button
-              content: "Redirect to Current Page (Safe Demo)"
-              actions:
-                - what: redirect
-                  on: click
-                  to: "."
-
-            - type: div
-              content: "↑ Click the button above to see the redirect in action"
-
-            - type: button
-              content: "Conditional Redirect (Google)"
-              actions:
-                - what: redirect
-                  on: click
-                  to: "https://www.google.com"
-                  when: ~.allowRedirect
-                  is: true
-
-            - type: button
-              content: "Toggle Redirect Permission"
-              actions:
-                - what: setData
-                  on: click
-                  path: "allowRedirect"
-                  value: ~.allowRedirect
-                  is: false
-                - what: setData
-                  on: click
-                  path: "allowRedirect"
-                  value: ~.allowRedirect
-                  is: true
-                  when: ~.allowRedirect
-                  is: false
+  - type: Markdown
+    content: |
+      ## Example
 
-            - type: div
-              content: ["Redirect allowed: ", ~.allowRedirect]
+      The following example will redirect the current page when the user clicks on the button.
 
-      data:
-        allowRedirect: false
+      ```yaml
+      renderView:
+        - type: button
+          content: "Go to EA Lab"
+          actions:
+            - what: redirect
+              to: "https://ea-lab.io"
+              when: ~~.allowRedirect
+              is: "true"
+            - what: setData
+              on: click
+              path: ~~.allowRedirect
+              value: "true"
+      ```
 
   - type: Markdown
     content: |

package/public/rjbuild/docs/core/action/VisuallyHide.yaml

@@ -29,32 +29,30 @@ renderView:
               actions:
                 - what: setData
                   on: click
-                  path: "shouldVisuallyHide"
-                  value: ~.shouldVisuallyHide
-                  is: false
+                  path: ~.shouldVisuallyHide
+                  value: "false"
+                  when: ~.shouldVisuallyHide
+                  is: "true"
+                  stopPropagation: true
                 - what: setData
                   on: click
-                  path: "shouldVisuallyHide"
-                  value: ~.shouldVisuallyHide
-                  is: true
+                  path: ~.shouldVisuallyHide
+                  value: "true"
                   when: ~.shouldVisuallyHide
-                  is: false
+                  is: "false"
 
             - type: div
               content: "This text will be visually hidden but remains in the DOM."
               actions:
                 - what: visuallyHide
                   when: ~.shouldVisuallyHide
-                  is: true
+                  is: "true"
 
             - type: div
               content: ["Current state: shouldVisuallyHide = ", ~.shouldVisuallyHide]
 
-            - type: div
-              content: "↑ Notice the space is preserved even when hidden"
-
       data:
-        shouldVisuallyHide: false
+        shouldVisuallyHide: "false"
 
   - type: Markdown
     content: |