@ea-lab/reactive-json-docs 0.1.2

package/public/rjbuild/component-doc/core/action/index.yaml

@@ -0,0 +1,278 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Reactive-JSON Actions System Documentation
+
+      ## Introduction
+
+      The Reactive-JSON actions system allows you to modify element behavior and appearance based on dynamic conditions. Actions are applied to individual elements and can control visibility, display tooltips, redirect users, or trigger other behaviors based on the current data state.
+
+      This system enables you to create interactive interfaces directly through JSON configuration, without requiring custom JavaScript code.
+
+  - type: RjBuildDescriber
+    title: "Basic Action Structure"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates the fundamental structure of actions in Reactive-JSON.
+          
+          Actions are defined as an array on any element and consist of:
+          - `what`: The type of action to execute
+          - **Action-specific properties**: Vary depending on the action type
+          - **Conditional properties**: Define when the action should be executed (optional)
+
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Toggle visibility"
+          actions:
+            - what: setData
+              on: click
+              path: ~.my_condition
+              value: false
+              when: ~.my_condition
+              is: true
+              stopPropagation: true
+            - what: setData
+              on: click
+              path: ~.my_condition
+              value: true
+              when: ~.my_condition
+              is: false
+              stopPropagation: true
+
+        - type: div
+          content: "This content can be hidden"
+          attributes:
+            style:
+              padding: "10px"
+              border: "1px solid #ccc"
+              margin: "5px 0"
+          actions:
+            - what: hide           # Action type
+              when: ~.my_condition # Condition to evaluate
+              is: true             # Expected value
+
+      data:
+        my_condition: false
+
+  - type: Markdown
+    content: |
+      ## Action Types
+
+      Reactive-JSON provides several built-in actions:
+
+      - **[hide](Hide)**: Completely hides the element and its children
+      - **[visuallyHide](VisuallyHide)**: Visually hides the element while keeping it accessible to screen readers
+      - **[tooltip](Tooltip)**: Displays a tooltip on hover
+      - **[popover](Popover)**: Shows a more complex popover on click
+      - **[redirect](Redirect)**: Redirects to a specified URL
+
+      For detailed documentation of each action, including properties and examples, see their respective documentation pages.
+
+  - type: RjBuildDescriber
+    title: "Basic Conditional Actions"
+    description:
+      - type: Markdown
+        content: |
+          This example shows simple conditional actions using `is` and `isEmpty` conditions.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: div
+              content: "This shows only when status is 'active'"
+              attributes:
+                style:
+                  padding: "10px"
+                  backgroundColor: "#e8f5e8"
+                  margin: "5px 0"
+              actions:
+                - what: hide
+                  when: ~.status
+                  isNot: "active"
+                  
+            - type: div
+              content: "This shows only when text is not empty"
+              attributes:
+                style:
+                  padding: "10px"
+                  backgroundColor: "#f0f8ff"
+                  margin: "5px 0"
+              actions:
+                - what: hide
+                  when: ~.text_input
+                  isEmpty: true
+
+        - type: div
+          content:
+            - type: label
+              content: "Status: "
+            - type: SelectField
+              dataLocation: ~.status
+              options:
+                - value: "inactive"
+                  label: "Inactive"
+                - value: "active"
+                  label: "Active"
+                  
+            - type: br
+            
+            - type: label
+              content: "Text: "
+            - type: TextField
+              dataLocation: ~.text_input
+              placeholder: "Type something..."
+
+      data:
+        status: "inactive"
+        text_input: ""
+
+  - type: RjBuildDescriber
+    title: "Tooltip Action Example"
+    description:
+      - type: Markdown
+        content: |
+          This example demonstrates the tooltip action with conditional display.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Hover for help (when enabled)"
+              actions:
+                - what: tooltip
+                  content: "This is a helpful tooltip!"
+                  placement: "top"
+                  when: ~.show_tooltips
+                  is: true
+                  
+            - type: br
+            - type: br
+            
+            - type: label
+              content:
+                - type: CheckBoxField
+                  dataLocation: ~.show_tooltips
+                  options:
+                    - value: true
+                      label: ""
+                - " Enable tooltips"
+
+      data:
+        show_tooltips: true
+
+  - type: RjBuildDescriber
+    title: "Practical Form Example"
+    description:
+      - type: Markdown
+        content: |
+          This example shows a simple form with conditional submit button and validation messages.
+
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: h4
+              content: "Simple Contact Form"
+              
+            - type: div
+              content:
+                - type: label
+                  content: "Name: "
+                - type: TextField
+                  dataLocation: ~.form.name
+                  placeholder: "Enter your name"
+                      
+            - type: br
+            
+            - type: div
+              content:
+                - type: label
+                  content: "Email: "
+                - type: TextField
+                  dataLocation: ~.form.email
+                  inputType: "email"
+                  placeholder: "Enter your email"
+                      
+            - type: br
+            
+            - type: div
+              content: "Please fill in both fields"
+              attributes:
+                style:
+                  color: "red"
+                  fontSize: "14px"
+              actions:
+                - what: hide
+                  andConditions:
+                    - when: ~.form.name
+                      isEmpty: not
+                    - when: ~.form.email
+                      isEmpty: not
+                  
+            - type: button
+              content: "Submit"
+              attributes:
+                style:
+                  backgroundColor: "#4caf50"
+                  color: "white"
+                  border: "none"
+                  padding: "8px 16px"
+              actions:
+                - what: hide
+                  when: ~.form.name
+                  isEmpty: true
+                - what: hide
+                  when: ~.form.email
+                  isEmpty: true
+                - what: setData
+                  on: click
+                  path: ~.submitted
+                  value: true
+                  
+            - type: div
+              content: "✅ Form submitted successfully!"
+              attributes:
+                style:
+                  color: "green"
+                  marginTop: "10px"
+                  fontWeight: "bold"
+              actions:
+                - what: hide
+                  when: ~.submitted
+                  isNot: true
+
+      data:
+        form:
+          name: ""
+          email: ""
+        submitted: false
+
+  - type: Markdown
+    content: |
+      ## Technical Limitations
+
+      1. **Execution order**: Actions are evaluated in definition order and cannot be reordered dynamically
+      2. **Hide behavior**: Once an element is hidden with the `hide` action, no subsequent actions execute
+      3. **Synchronous evaluation**: All conditions and actions are evaluated synchronously
+      4. **Data scope**: Actions can only access data from the current template context and global context
+      5. **No side effects**: Actions cannot directly modify global state or trigger reactions
+      6. **External dependencies**: Some actions (tooltip, popover) require React Bootstrap components
+
+      ## Best Practices
+
+      1. **Keep conditions simple**: Avoid overly complex condition logic for better maintainability
+      2. **Consider performance**: Minimize frequently-evaluated complex conditions
+      3. **Use appropriate actions**: Choose `visuallyHide` over `hide` when content should remain accessible
+      4. **Test thoroughly**: Verify action behavior with different data states
+      5. **Document complex logic**: Add comments for non-obvious conditional logic
+      6. **Order matters**: Place critical actions (like `hide`) early in the action array when appropriate
+
+      ## Related Documentation
+
+      - **Individual Action Documentation**: See the dedicated pages for each action type
+      - **[Reactions System](../reaction/index)**: Learn about handling user events and state changes
+      - **[Template System](../../template-system)**: Understand data binding and template expressions

package/public/rjbuild/component-doc/core/element/form/CheckBoxField.md

@@ -0,0 +1,276 @@
+# CheckBoxField
+
+The `CheckBoxField` component renders checkbox or radio button groups using React Bootstrap. It supports both single and multiple selections, dynamic options, and intelligent data storage based on the control type and configuration.
+
+## Properties
+
+- `dataLocation` (string, optional): Path to bind the field value in the data context
+- `defaultFieldValue` (any, optional): Default value when no data is present
+- `options` (array, optional): Static array of option objects with `label` and `value` properties
+- `dynamicOptions` (string, optional): Template path to dynamic options array
+- `controlType` (string, optional): Type of control - "checkbox" (default) or "radio"
+- `multiple` (boolean, optional): Force array storage for checkboxes (default: auto-detected)
+- `attributes` (object, optional): Attributes applied to the Form.Group container
+- `actions` (array, optional): Actions to execute based on field state
+
+## Option Format
+
+Each option object must have:
+- `label` (string|object): Display text or Reactive-JSON content for the option
+- `value` (any): The actual value to store when selected
+- `attributes` (object, optional): Additional attributes for the specific option
+
+## Data Storage Modes
+
+The component uses different data storage strategies:
+
+### Single Value Mode
+- Used for radio buttons (`controlType: "radio"`)
+- Used for single checkbox when `options.length === 1` and `multiple` is not set
+- Stores the selected value directly
+
+### Array Mode
+- Used for multiple checkboxes when `options.length > 1` or `multiple: true`
+- Stores selected values in an array
+- Automatically manages array additions and removals
+
+## Basic Examples
+
+### Multiple Checkboxes
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.interests
+    options:
+      - label: "Technology"
+        value: "tech"
+      - label: "Sports"
+        value: "sports"
+      - label: "Music"
+        value: "music"
+      - label: "Travel"
+        value: "travel"
+
+data:
+  interests:
+    - sports
+    - travel
+```
+
+### Radio Buttons
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.priority
+    controlType: "radio"
+    options:
+      - label: "Low"
+        value: "low"
+      - label: "Medium"
+        value: "medium"
+      - label: "High"
+        value: "high"
+      - label: "Critical"
+        value: "critical"
+
+data:
+  priority: ""
+```
+
+### Single Checkbox
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.acceptTerms
+    options:
+      - label: "I accept the terms and conditions"
+        value: true
+  - type: CheckBoxField
+    dataLocation: ~.newsletter
+    options:
+      - label: "Subscribe to newsletter"
+        value: true
+
+data:
+  acceptTerms: false
+  newsletter: false
+```
+
+## Value Types Limitations
+
+**Important**: CheckBoxField has limitations with non-string value types due to HTML input behavior:
+
+- ✅ **String values**: Work perfectly (`"tech"`, `"sports"`, etc.)
+- ✅ **Boolean values**: Work for single checkboxes (`true`/`false`)  
+- ❌ **Numeric values**: May cause issues due to string conversion in HTML inputs
+- ❌ **Complex objects**: Not supported in array mode
+
+**Recommendation**: Use string values for reliability. Numeric and complex value type support may be improved in future versions.
+
+```yaml
+# ✅ Recommended - String values
+options:
+  - label: "Priority 1"
+    value: "priority_1"
+  - label: "Priority 2" 
+    value: "priority_2"
+
+# ❌ Avoid - Numeric values may cause issues
+options:
+  - label: "Priority 1"
+    value: 1
+  - label: "Priority 2"
+    value: 2
+```
+
+## Dynamic Options with Conditional Display
+
+CheckBoxField supports dynamic options loaded from data using `dynamicOptions`. Since dynamic path selection like `~.data[~.key]` is not supported, the recommended technique is:
+
+1. **Create one CheckBoxField per category** instead of trying to use dynamic paths
+2. **Use conditional `hide` actions** to show only the relevant CheckBoxField
+3. **Store selections in separate data locations** for each category
+
+### Example: Skills by Category
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.selectedCategory
+    label: "Select Category to see available skills:"
+    options:
+      - label: "Choose category"
+        value: ""
+      - label: "Technology"
+        value: "technology"
+      - label: "Business"
+        value: "business"
+      - label: "Creative"
+        value: "creative"
+  - type: CheckBoxField
+    dataLocation: ~.techSkills
+    dynamicOptions: ~.skillCategories.technology
+    actions:
+      - what: hide
+        when: ~.selectedCategory
+        isNot: "technology"
+  - type: CheckBoxField
+    dataLocation: ~.businessSkills
+    dynamicOptions: ~.skillCategories.business
+    actions:
+      - what: hide
+        when: ~.selectedCategory
+        isNot: "business"
+  - type: CheckBoxField
+    dataLocation: ~.creativeSkills
+    dynamicOptions: ~.skillCategories.creative
+    actions:
+      - what: hide
+        when: ~.selectedCategory
+        isNot: "creative"
+
+data:
+  selectedCategory: ""
+  techSkills: []
+  businessSkills: []
+  creativeSkills: []
+  skillCategories:
+    technology:
+      - label: "JavaScript"
+        value: "javascript"
+      - label: "Python"
+        value: "python"
+      - label: "React"
+        value: "react"
+      - label: "Node.js"
+        value: "nodejs"
+    business:
+      - label: "Project Management"
+        value: "pm"
+      - label: "Marketing"
+        value: "marketing"
+      - label: "Sales"
+        value: "sales"
+      - label: "Finance"
+        value: "finance"
+    creative:
+      - label: "Graphic Design"
+        value: "design"
+      - label: "Photography"
+        value: "photo"
+      - label: "Writing"
+        value: "writing"
+      - label: "Video Editing"
+        value: "video"
+```
+
+### Why Not Dynamic Paths?
+
+```yaml
+# ❌ This does NOT work in Reactive-JSON:
+renderView:
+  - type: CheckBoxField
+    dynamicOptions: ~.categories[~.selectedCategory]
+
+# ✅ Use this approach instead:
+renderView:
+  - type: CheckBoxField
+    dynamicOptions: ~.categories.technology
+    actions:
+      - what: hide
+        when: ~.selectedCategory
+        isNot: "technology"
+```
+
+This technique ensures clean separation of data and provides predictable behavior.
+
+## Option Attributes
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.notifications
+    options:
+      - label: "Email notifications"
+        value: "email"
+        attributes:
+          style:
+            color: "blue"
+      - label: "SMS notifications (premium feature)"
+        value: "sms"
+        attributes:
+          disabled: true
+          title: "This feature requires a premium subscription"
+      - label: "Push notifications"
+        value: "push"
+        attributes:
+          style:
+            fontWeight: "bold"
+
+data:
+  notifications: []
+```
+
+## Limitations
+
+### Value Types
+- **Numeric values**: May cause issues due to string conversion in HTML input elements
+- **Complex objects**: Cannot be used as option values in array mode
+- **Recommendation**: Use string values for most cases. Numeric and complex value type support may be improved in future versions.
+
+### General Limitations
+- Option labels support template evaluation but with limited View component rendering
+- No support for indeterminate checkbox state
+- No built-in option grouping or hierarchical structure
+- Array mode may not preserve object key order in older JavaScript engines
+- No built-in validation for minimum/maximum selections
+- Limited styling options compared to custom checkbox implementations
+
+## Value Type Handling
+
+The component handles special string values in radio mode:
+- Empty string `""` becomes `undefined`
+- String `"true"` becomes boolean `true`
+- String `"false"` becomes boolean `false`
+- String `"null"` becomes `null`
+- Other strings remain as strings