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

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

@@ -0,0 +1,244 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      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
+
+  - type: Markdown
+    content: |
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: keepAttributeWhenEmpty
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: |
+            Whether to keep the attribute when it becomes empty. If `false`, the attribute is removed when no values remain. Default: `false`.
+      - 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: value
+          after: "(string|array, required)"
+        details:
+          type: Markdown
+          content: |
+            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.
+
+  - type: Markdown
+    content: |
+
+      ## 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
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      # 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"
+
+  - type: Markdown
+    content: |
+
+      ### 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.
+
+  - type: RjBuildDescriber
+    title: "ToggleAttributeValue Action Examples"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to toggle the readonly attribute using the `ToggleAttributeValue` action.
+          
+          **Expected behavior:**
+          - Initially, the input field is editable (normal appearance)
+          - Click "Toggle readonly" to make the input readonly (you cannot type in it + visual changes)
+          - Click "Toggle readonly" again to make it editable again
+          - Click "Reset" to return to the initial state (editable)
+          - The toggle action automatically adds/removes the 'readonly' value from the class attribute
+          
+          Try interacting with the buttons to see how the readonly state toggles.
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Toggle readonly"
+          actions:
+            - what: setData
+              on: click
+              path: ~.shouldToggle
+              value: "yes"
+              when: ~.shouldToggle
+              is: "no"
+              stopPropagation: true
+            - what: setData
+              on: click
+              path: ~.shouldToggle
+              value: "no"
+              when: ~.shouldToggle
+              is: "yes"
+              stopPropagation: true
+
+        - type: button
+          content: "Reset"
+          actions:
+            - what: setData
+              on: click
+              path: ~.shouldToggle
+              value: "no"
+              stopPropagation: true
+
+        - type: input
+          attributes:
+            type: "text"
+            placeholder: "Try typing here when readonly is removed..."
+            value: ~.input_value
+            class: "tav-demo-input"
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              borderRadius: "4px"
+              fontSize: "16px"
+              margin: "10px 0"
+              width: "300px"
+              display: "block"
+          actions:
+            - what: toggleAttributeValue
+              name: "class"
+              value: "tav-readonly"
+              when: ~.shouldToggle
+              is: "yes"
+            - what: setData
+              on: change
+              path: ~.input_value
+              value: <reactive-json:event-new-value>
+        - type: style
+          content: |
+            .tav-readonly {
+              cursor: not-allowed !important;
+              opacity: 0.7 !important;
+              border-color: #6c757d !important;
+              pointer-events: none !important;
+            }
+
+      data:
+        shouldToggle: "no"
+        input_value: ""
+  - type: Markdown
+    content: |
+      ## 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.).

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

@@ -0,0 +1,108 @@
+# UnsetAttribute
+
+Completely removes an HTML attribute from an element.
+
+## Basic Syntax
+
+```yaml
+actions:
+  # Remove entire attribute
+  - what: unsetAttribute
+    name: "class"
+    
+  # Conditional removal
+  - what: unsetAttribute
+    name: "style"
+    when: ~.useDefaultStyling
+    is: true
+```
+
+## Properties
+
+- **name** *(string, required)*: The name of the attribute to remove completely.
+
+## Behavior
+
+- **Complete removal**: Removes the entire attribute and all its values from the DOM element.
+- **Attribute deletion**: The attribute is completely deleted, not just emptied.
+- **Irreversible**: Once removed, the attribute must be explicitly set again to restore it.
+
+## Common Use Cases
+
+- **Conditional attribute presence**: Removing attributes entirely based on conditions.
+- **Accessibility cleanup**: Removing ARIA attributes when not needed.
+- **Data attribute management**: Completely removing data-* attributes.
+- **Style reset**: Removing inline style attributes to fall back to CSS.
+
+## Example
+
+```yaml
+renderView:
+  - type: button
+    content: "Remove readonly attribute"
+    actions:
+      - what: setData
+        on: click
+        path: ~.makeEditable
+        value: true
+        stopPropagation: true
+
+  - type: button
+    content: "Reset"
+    actions:
+      - what: setData
+        on: click
+        path: ~.makeEditable
+        value: false
+        stopPropagation: true
+
+  - type: input
+    attributes:
+      type: "text"
+      value: ~.input_value
+      placeholder: "Try typing here when readonly is removed..."
+      class: "ua-demo-input"
+      readonly: "readonly"
+      style:
+        padding: "10px"
+        border: "2px solid #007bff"
+        borderRadius: "4px"
+        fontSize: "16px"
+        margin: "10px 0"
+        width: "300px"
+        display: "block"
+    actions:
+      - what: unsetAttribute
+        name: "readonly"
+        when: ~.makeEditable
+        is: true
+      - what: setData
+        on: change
+        path: ~.input_value
+        value: <reactive-json:event-new-value>
+
+  - type: style
+    content: |
+      .ua-demo-input[readonly] {
+        cursor: not-allowed !important;
+        opacity: 0.7 !important;
+        border-color: #6c757d !important;
+      }
+      .ua-demo-input:not([readonly]) {
+        border-color: #28a745 !important;
+        outline: 2px solid #28a745 !important;
+        outline-offset: 2px !important;
+      }
+
+data:
+  makeEditable: false
+  input_value: ""
+```
+
+## Notes
+
+- This action **completely removes the entire attribute**, not just specific values.
+- Use `UnsetAttributeValue` if you only want to remove specific values.
+- The attribute can be restored using `SetAttributeValue` if needed.
+- **Important**: To set an empty attribute (not remove it), use `SetAttributeValue` with an empty string value.
+- Useful for conditional attribute presence rather than conditional values.

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

@@ -0,0 +1,135 @@
+renderView:
+  - type: Markdown
+    content: |
+      # UnsetAttribute
+
+      Completely removes an HTML attribute from an element.
+
+      ## Basic Syntax
+
+  - type: TabbedSerializer
+    yamlSerializedContent: |
+      actions:
+        # Remove entire attribute
+        - what: unsetAttribute
+          name: "class"
+          
+        # Conditional removal
+        - what: unsetAttribute
+          name: "style"
+          when: ~.useDefaultStyling
+          is: true
+
+  - type: Markdown
+    content: |
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: name
+          after: "(string, required)"
+        details: The name of the attribute to remove completely.
+
+  - type: Markdown
+    content: |
+
+      ## Behavior
+
+      - **Complete removal**: Removes the entire attribute and all its values from the DOM element.
+      - **Attribute deletion**: The attribute is completely deleted, not just emptied.
+      - **Irreversible**: Once removed, the attribute must be explicitly set again to restore it.
+
+      ## Common Use Cases
+
+      - **Conditional attribute presence**: Removing attributes entirely based on conditions.
+      - **Accessibility cleanup**: Removing ARIA attributes when not needed.
+      - **Data attribute management**: Completely removing data-* attributes.
+      - **Style reset**: Removing inline style attributes to fall back to CSS.
+
+  - type: RjBuildDescriber
+    title: "UnsetAttribute Action Examples"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates how to completely remove HTML attributes using the `UnsetAttribute` action.
+          
+          **Expected behavior:**
+          - Initially, the input field is read-only (you cannot type in it) and has visual styling
+          - Click "Remove readonly attribute" to remove the entire readonly attribute - the input becomes editable
+          - Click "Reset" to restore the readonly attribute - the input becomes read-only again
+          - The action completely removes the entire attribute, not just its value
+          
+          Try interacting with the buttons to see how the readonly attribute is completely removed/restored.
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Remove readonly attribute"
+          actions:
+            - what: setData
+              on: click
+              path: ~.makeEditable
+              value: true
+              stopPropagation: true
+
+        - type: button
+          content: "Reset"
+          actions:
+            - what: setData
+              on: click
+              path: ~.makeEditable
+              value: false
+              stopPropagation: true
+
+        - type: input
+          attributes:
+            type: "text"
+            value: ~.input_value
+            placeholder: "Try typing here when readonly is removed..."
+            class: "ua-demo-input"
+            readonly: "readonly"
+            style:
+              padding: "10px"
+              border: "2px solid #007bff"
+              borderRadius: "4px"
+              fontSize: "16px"
+              margin: "10px 0"
+              width: "300px"
+              display: "block"
+          actions:
+            - what: unsetAttribute
+              name: "readonly"
+              when: ~.makeEditable
+              is: true
+            - what: setData
+              on: change
+              path: ~.input_value
+              value: <reactive-json:event-new-value>
+
+        - type: style
+          content: |
+            .ua-demo-input[readonly] {
+              cursor: not-allowed !important;
+              opacity: 0.7 !important;
+              border-color: #6c757d !important;
+            }
+            .ua-demo-input:not([readonly]) {
+              border-color: #28a745 !important;
+              outline: 2px solid #28a745 !important;
+              outline-offset: 2px !important;
+            }
+
+      data:
+        makeEditable: false
+        input_value: ""
+
+  - type: Markdown
+    content: |
+      ## Notes
+
+      - This action **completely removes the entire attribute**, not just specific values.
+      - Use `UnsetAttributeValue` if you only want to remove specific values.
+      - The attribute can be restored using `SetAttributeValue` if needed.
+      - **Important**: To set an empty attribute (not remove it), use `SetAttributeValue` with an empty string value.
+      - Useful for conditional attribute presence rather than conditional values.

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

@@ -0,0 +1,135 @@
+# UnsetAttributeValue
+
+Removes a specific value from an HTML attribute while preserving other values.
+
+## Basic Syntax
+
+```yaml
+actions:
+  # Remove CSS class
+  - what: unsetAttributeValue
+    name: "class"
+    value: "highlighted"
+    
+  # Remove with template
+  - what: unsetAttributeValue
+    name: "data-tags"
+    value: ~.tagToRemove
+```
+
+## Properties
+
+- **name** *(string, required)*: The name of the attribute to modify.
+- **separator** *(string, optional)*: The separator used between values. Default: `" "` (space).
+- **unsetAllOccurrences** *(boolean, optional)*: When `true` (default), removes all occurrences of the value from the attribute. When `false`, removes the number of elements defined by `unsetCount`.
+- **unsetCount** *(number, optional)*: 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`).
+- **value** *(string, required)*: The value to remove from the attribute. Supports template evaluation (e.g., `~.dynamicValue`, `~~.globalValue`). Automatically converted to string if not already.
+
+## 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.
+
+## Example
+
+```yaml
+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
+```
+
+## 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.