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

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

@@ -1,236 +1,24 @@
-# Reactive-JSON Reactions System Documentation
+# Reactions
 
-## Introduction
+> For an introduction to the reactions system and detailed examples, see [Getting Started: Reactions](../../getting-started/reactions.md).
 
-Reactions are a fundamental part of Reactive-JSON's interactivity system. They allow you to respond to user events and perform operations like data updates, network requests, and browser interactions. In the RjBuild, reactions are defined under the `actions` key, just like regular actions, but are distinguished by the presence of the `on` property.
+Reactions in Reactive-JSON allow you to respond to user events and perform operations like data updates, network requests, and browser interactions. They execute in response to user events to modify application state and trigger behaviors.
 
-### Basic Structure
-```yaml
-renderView:
-  - type: button
-    content: Click me
-    actions:
-      - what: setData    # Reaction type
-        on: click        # Event that triggers the reaction
-        path: ~.my_state # Where to store the data
-        value: "on"      # Value to set
-```
+## Available Reaction Components
 
-## 1. Basic Reactions
+### Data Management
+- **[setData](./setData.md)**: Sets data at the specified path
+- **[addData](./addData.md)**: Adds new data to the specified path
+- **[removeData](./removeData.md)**: Removes data from the specified path
+- **[moveData](./moveData.md)**: Moves data from one path to another
 
-### 1.1 Data Management
-- `addData` : Adds new data to the specified path
-- `setData` : Sets data at the specified path
-- `removeData` : Removes data from the specified path
-- `moveData` : Moves data from one path to another
+### Network Operations
+- **[fetchData](./fetchData.md)**: Fetches data from a URL using GET requests
+- **[submitData](./submitData.md)**: Submits data to a server endpoint using POST/PUT/DELETE
 
-### 1.2 Network Operations
-- `fetchData` : Fetches data from a URL
-- `submitData` : Submits data to a server endpoint
+### Browser Operations
+- **[setClipboardData](./setClipboardData.md)**: Copies data to the clipboard
+- **[redirectNow](./redirectNow.md)**: Performs an immediate redirect
+- **[triggerEvent](./triggerEvent.md)**: Triggers a custom event
+- **[postMessage](./postMessage.md)**: Sends a message to another window/frame
 
-### 1.3 Browser Operations
-- `setClipboardData` : Copies data to the clipboard
-- `redirectNow` : Performs an immediate redirect
-- `triggerEvent` : Triggers a custom event
-- `postMessage` : Sends a message to another window/frame
-
-## 2. Reaction Structure
-Each reaction is defined by:
-- `what` : The name of the reaction to execute
-- `on` : The event that triggers the reaction
-- Reaction-specific options (vary by reaction type)
-- **Optional conditions** : Reactions support the same conditional system as actions
-
-### 2.1 Conditional Reactions
-Just like actions, reactions can be made conditional using various comparison operators:
-
-- `when` + `is` / `isNot` : Value equality checks
-- `when` + `isEmpty` : Empty value tests
-- `when` + `contains` / `containsNot` : Content search
-- `when` + `>`, `<`, `>=`, `<=` : Numeric/date comparisons
-- `andConditions` / `orConditions` : Complex condition logic
-
-For example:
-```yaml
-actions:
-  - what: setData              # Reaction name
-    on: click                  # Triggering event
-    path: ~.user.profile       # Reaction-specific option
-    value: ~.form_data         # Reaction-specific option
-    when: ~.is_editing         # Condition - only execute if editing
-    is: true                   # Condition value
-  - what: submitData           # Reaction name
-    on: submit                 # Triggering event
-    url: "/api/endpoint"       # Reaction-specific option
-    method: "POST"             # Reaction-specific option
-    data: ~.form_data          # Reaction-specific option
-    when: ~.form_data          # Condition - only submit if form has data
-    isEmpty: "not"             # Condition check
-  - what: setData              # Multiple conditions example
-    on: click
-    path: ~.result
-    value: "success"
-    andConditions:             # All conditions must be true
-      - when: ~.user.role
-        is: "admin"
-      - when: ~.feature_enabled
-        is: true
-```
-
-## 3. Event Types
-The `on` property accepts standard browser events. These events are the same as those used in standard web development, and their availability depends on the HTML element type. For example, a `change` event will only work on form elements like `input`, `select`, or `textarea`, while a `click` event works on any element.
-
-Common event types:
-- `click` : Mouse click (works on any element)
-- `change` : Form input change (works on form elements only)
-- `submit` : Form submission (works on form elements only)
-- `keydown` : Keyboard key press (works on elements that can receive focus)
-- `keyup` : Keyboard key release (works on elements that can receive focus)
-
-## 4. Event Control
-The `stopPropagation` property can be used to control event bubbling and subsequent actions:
-```yaml
-actions:
-  - what: setData
-    on: click
-    path: ~.state
-    value: "on"
-    stopPropagation: true  # Prevents event bubbling AND stops execution of subsequent actions
-```
-
-When `stopPropagation` is set to `true`, it:
-1. Prevents the event from bubbling up to parent elements
-2. Stops the execution of any subsequent actions defined for the same event
-
-This is particularly useful when you want to ensure that only the first matching action is executed, even if multiple actions are defined for the same event.
-
-## 5. Technical Details
-- Reactions are triggered by events
-- Multiple reactions can be defined for the same event
-- Reactions are executed in order
-- Reactions can be chained together
-- **Reactions support all the same conditional operators as actions**: `when`, `is`, `isNot`, `isEmpty`, `contains`, `>`, `<`, `>=`, `<=`, `andConditions`, `orConditions`
-- Conditional reactions only execute when their conditions evaluate to true
-- The execution order of multiple reactions on the same event is guaranteed to match their order in the YAML
-- If a reaction's conditions are not met, it is skipped and the next reaction is evaluated
-
-## 6. Limitations
-- Reactions cannot modify external state
-- Network operations must be properly configured
-- Browser operations require appropriate permissions
-
-## 7. Complete Examples
-
-### 7.1 Data Input and Submission
-```yaml
-renderView:
-  - type: TextField
-    label: "Username"
-    placeholder: "Enter your username"
-    dataLocation: ~.form_data.username
-  - type: TextField
-    label: "Email"
-    placeholder: "Enter your email"
-    inputType: "email"
-    dataLocation: ~.form_data.email
-  - type: button
-    content: Submit
-    actions:
-      - what: submitData
-        on: click
-        url: "/api/submit"
-        data:
-          username: ~.form_data.username
-          email: ~.form_data.email
-        when: ~.form_data.username
-        isEmpty: not
-
-data:
-  form_data:
-    username: ""
-    email: ""
-```
-
-### 7.2 Conditional Reactions Example
-```yaml
-renderView:
-  - type: button
-    content: "Toggle State"
-    actions:
-      - what: setData
-        on: click
-        path: ~.button_state
-        value: "on"
-        when: ~.button_state
-        is: "off"
-        stopPropagation: true
-      - what: setData
-        on: click
-        path: ~.button_state
-        value: "off"
-        when: ~.button_state
-        is: "on"
-        stopPropagation: true
-  - type: div
-    content: ["Button state: ", ~.button_state]
-  - type: div
-    content: "Button has been clicked!"
-    actions:
-      - what: hide
-        when: ~.button_state
-        is: "off"
-
-data:
-  button_state: "off"
-```
-
-### 7.3 Complex Conditional Logic
-```yaml
-renderView:
-  - type: TextField
-    label: "Enter a number:"
-    dataLocation: ~.user_input
-    inputType: "number"
-  - type: button
-    content: "Process Number"
-    actions:
-      - what: setData
-        on: click
-        path: ~.result
-        value: "Number is valid and positive!"
-        andConditions:
-          - when: ~.user_input
-            isEmpty: "not"
-          - when: ~.user_input
-            ">": 0
-      - what: setData
-        on: click
-        path: ~.result
-        value: "Number must be positive!"
-        when: ~.user_input
-        "<=": 0
-      - what: setData
-        on: click
-        path: ~.result
-        value: "Please enter a number!"
-        when: ~.user_input
-        isEmpty: true
-  - type: div
-    content: ["Result: ", ~.result]
-    actions:
-      - what: hide
-        when: ~.result
-        isEmpty: true
-
-data:
-  user_input: null
-  result: null
-```
-
-## Conclusion
-
-You now have a good understanding of reactions in Reactive-JSON. We've seen how they allow you to respond to user events and perform various operations like data updates and network requests.
-
-To create complete interactive interfaces, you should combine reactions with actions. Actions handle the conditional behavior of elements, while reactions handle user interactions and data updates.
-
-For more information about actions and conditional behavior, check out the [Actions Documentation](../action/index.md).

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

@@ -1,254 +1,26 @@
 renderView:
   - type: Markdown
     content: |
-      # Reactive-JSON Reactions System Documentation
+      # Reactions
 
-      ## Introduction
+      > For an introduction to the reactions system and detailed examples, see [Getting Started: Reactions](../../getting-started/reactions).
 
-      Reactions are a fundamental part of Reactive-JSON's interactivity system. They allow you to respond to user events and perform operations like data updates, network requests, and browser interactions. In the RjBuild, reactions are defined under the `actions` key, just like regular actions, but are distinguished by the presence of the `on` property.
+      Reactions in Reactive-JSON allow you to respond to user events and perform operations like data updates, network requests, and browser interactions. They execute in response to user events to modify application state and trigger behaviors.
 
-      Reactions enable you to create interactive interfaces that respond to user input, modify application state, communicate with servers, and control browser behavior - all through JSON configuration.
-
-  - type: RjBuildDescriber
-    title: "Basic Reaction Structure"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the fundamental structure of reactions in Reactive-JSON.
-          
-          Reactions are defined as part of the `actions` array on any element and consist of:
-          - `what`: The name of the reaction to execute
-          - `on`: The event that triggers the reaction
-          - **Reaction-specific properties**: Vary depending on the reaction type
-          - **Optional conditions**: Same conditional system as actions
-
-    toDescribe:
-      renderView:
-        - type: TextField
-          label: "Enter some text:"
-          dataLocation: ~.user_input
-          placeholder: "Type something..."
-
-        - type: button
-          content: "Save Text"
-          actions:
-            - what: setData              # Reaction type
-              on: click                  # Triggering event
-              path: ~.saved_text         # Reaction-specific property
-              value: ~.user_input        # Reaction-specific property
-              when: ~.user_input         # Optional condition
-              isEmpty: "not"             # Condition value
-
-        - type: div
-          content: ["Saved text: ", ~.saved_text]
-          actions:
-            - what: hide                 # Action (no 'on' property)
-              when: ~.saved_text         # Condition
-              isEmpty: true
-
-      data:
-        user_input: ""
-        saved_text: ""
-
-  - type: Markdown
-    content: |
-      ## Reaction Types
-
-      Reactive-JSON provides several built-in reactions:
+      ## Available Reaction Components
 
       ### Data Management
-      - **[setData](setData)**: Sets data at the specified path
-      - **[addData](addData)**: Adds new data to the specified path
-      - **[removeData](removeData)**: Removes data from the specified path
-      - **[moveData](moveData)**: Moves data from one path to another
+      - **[setData](./setData)**: Sets data at the specified path
+      - **[addData](./addData)**: Adds new data to the specified path
+      - **[removeData](./removeData)**: Removes data from the specified path
+      - **[moveData](./moveData)**: Moves data from one path to another
 
       ### Network Operations
-      - **[fetchData](fetchData)**: Fetches data from a URL using GET requests
-      - **[submitData](submitData)**: Submits data to a server endpoint using POST/PUT/DELETE
+      - **[fetchData](./fetchData)**: Fetches data from a URL using GET requests
+      - **[submitData](./submitData)**: Submits data to a server endpoint using POST/PUT/DELETE
 
       ### Browser Operations
-      - **[setClipboardData](setClipboardData)**: Copies data to the clipboard
-      - **[redirectNow](redirectNow)**: Performs an immediate redirect
-      - **[triggerEvent](triggerEvent)**: Triggers a custom event
-      - **[postMessage](postMessage)**: Sends a message to another window/frame
-
-      For detailed documentation of each reaction, including properties and examples, see their respective documentation pages.
-
-  - type: RjBuildDescriber
-    title: "Event Types and Conditional Reactions"
-    description:
-      - type: Markdown
-        content: |
-          This example shows different event types and conditional reactions.
-          
-          Common event types:
-          - `click`: Mouse click (works on any element)
-          - `change`: Form input change (works on form elements only)
-          - `submit`: Form submission (works on form elements only)
-          - `keydown`/`keyup`: Keyboard events (works on focusable elements)
-
-    toDescribe:
-      renderView:
-        - type: button
-          content: "Toggle Mode (Click)"
-          actions:
-            - what: setData
-              on: click
-              path: ~.mode
-              value: "editing"
-              when: ~.mode
-              isNot: "editing"
-            - what: setData
-              on: click
-              path: ~.mode
-              value: "viewing"
-              when: ~.mode
-              is: "editing"
-
-        - type: TextField
-          label: "Text field (onChange):"
-          dataLocation: ~.text_value
-          actions:
-            - what: setData
-              on: change
-              path: ~.last_change
-              value: ~.text_value
-              when: ~.mode
-              is: "editing"
-
-        - type: div
-          content: ["Current mode: ", ~.mode]
-
-        - type: div
-          content: ["Last change: ", ~.last_change]
-          actions:
-            - what: hide
-              when: ~.last_change
-              isEmpty: true
-
-      data:
-        mode: "viewing"
-        text_value: ""
-        last_change: ""
-
-  - type: RjBuildDescriber
-    title: "Data Management Example"
-    description:
-      - type: Markdown
-        content: |
-          This example demonstrates the core data management reactions: setData, addData, and removeData.
-
-    toDescribe:
-      renderView:
-        - type: TextField
-          label: "Add item:"
-          dataLocation: ~.new_item
-          placeholder: "Enter item name"
-
-        - type: button
-          content: "Add Item"
-          actions:
-            - what: addData
-              on: click
-              path: ~.items
-              value:
-                name: ~.new_item
-              when: ~.new_item
-              isEmpty: "not"
-            - what: setData
-              on: click
-              path: ~.new_item
-              value: ""
-              when: ~.new_item
-              isEmpty: "not"
-
-        - type: div
-          content: "Items:"
-          attributes:
-            style:
-              fontWeight: "bold"
-              margin: "10px 0 5px 0"
-
-        - type: Switch
-          content: ~.items
-          singleOption:
-            load: itemTemplate
-
-      templates:
-        itemTemplate:
-          type: div
-          content:
-            - "• "
-            - ~.name
-            - type: button
-              content: " [Remove]"
-              attributes:
-                style:
-                  marginLeft: "10px"
-                  background: "red"
-                  color: "white"
-                  border: "none"
-                  padding: "2px 8px"
-                  fontSize: "12px"
-              actions:
-                - what: removeData
-                  on: click
-                  target: currentTemplateData
-                  parentLevel: 0
-
-      data:
-        new_item: ""
-        items:
-          - name: "Sample item 1"
-          - name: "Sample item 2"
-
-  - type: Markdown
-    content: |
-      ## Advanced Features
-
-      ### Conditional Logic
-      Reactions support the same conditional operators as actions:
-      - `when` + `is`/`isNot`: Value equality checks
-      - `when` + `isEmpty`: Empty value tests  
-      - `when` + `contains`/`containsNot`: Content search
-      - `when` + `>`, `<`, `>=`, `<=`: Numeric/date comparisons
-      - `andConditions`/`orConditions`: Complex condition logic
-
-      ### Event Control
-      Use `stopPropagation: true` to:
-      1. Prevent event bubbling to parent elements
-      2. Stop execution of subsequent actions for the same event
-
-      ### Execution Order
-      - Multiple reactions on the same event execute in the order they are defined
-      - Reactions with unmet conditions are skipped
-      - Actions (without `on` property) are evaluated separately from reactions
-
-  - type: Markdown
-    content: |
-      ## Technical Details
-
-      - Reactions are triggered by DOM events
-      - Multiple reactions can be defined for the same event
-      - Reactions are executed in the order they appear in the YAML
-      - Reactions can be chained together by modifying data that other reactions depend on
-      - Conditional reactions only execute when their conditions evaluate to true
-      - The `stopPropagation` property affects both event bubbling and subsequent action execution
-
-      ## Limitations
-
-      - Event availability depends on the HTML element type (e.g., `change` only works on form elements)
-      - Network operations require proper CORS configuration
-      - Browser operations require appropriate permissions
-      - No built-in error handling beyond console logging for network operations
-      - Only one network request (fetch/submit) can be active at a time
-      - URLs in network operations must be static strings (dynamic URLs not supported)
-
-      ## Best Practices
-
-      1. **Use descriptive conditions**: Make your conditional logic clear and readable
-      2. **Handle empty states**: Always consider what happens when data is empty or undefined
-      3. **Order matters**: Place more specific conditions before general ones
-      4. **Use stopPropagation wisely**: Only use it when you specifically need to prevent event bubbling or stop action execution
-      5. **Test network operations**: Ensure your API endpoints return the expected format
-      6. **Provide user feedback**: Use visual indicators during loading states (see individual reaction documentation for CSS examples) 
+      - **[setClipboardData](./setClipboardData)**: Copies data to the clipboard
+      - **[redirectNow](./redirectNow)**: Performs an immediate redirect
+      - **[triggerEvent](./triggerEvent)**: Triggers a custom event
+      - **[postMessage](./postMessage)**: Sends a message to another window/frame

package/public/rjbuild/docs/core/reaction/setData.md

@@ -68,7 +68,7 @@ renderView:
         path: ~.message
         value: ["Welcome, ", ~.username, "!"]
         when: ~.username
-        isEmpty: "not"
+        isNotEmpty:
       - what: setData
         on: click
         path: ~.message

package/public/rjbuild/docs/core/reaction/setData.yaml

@@ -67,7 +67,7 @@ renderView:
               path: ~.message
               value: ["Welcome, ", ~.username, "!"]
               when: ~.username
-              isEmpty: "not"
+              isNotEmpty:
             - what: setData
               on: click
               path: ~.message

package/public/rjbuild/docs/docs-components/index.md

@@ -4,8 +4,6 @@
 
 This section documents components that are specific to the reactive-json-docs package. These components are not part of the core Reactive-JSON library but are provided by the documentation system to enhance the presentation of examples and technical content.
 
-**Important**: These components are only available when using reactive-json-docs and are not included in the core @ea-lab/reactive-json package.
-
 ## Available Components
 
 The documentation system provides specialized components for:

package/public/rjbuild/docs/docs-components/index.yaml

@@ -7,8 +7,6 @@ renderView:
 
       This section documents components that are specific to the reactive-json-docs package. These components are not part of the core Reactive-JSON library but are provided by the documentation system to enhance the presentation of examples and technical content.
 
-      **Important**: These components are only available when using reactive-json-docs and are not included in the core @ea-lab/reactive-json package.
-
       ## Available Components
 
       The documentation system provides specialized components for: