@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,338 @@
+renderView:
+  - type: Markdown
+    content: |
+      # 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
+
+  - type: RjBuildDescriber
+    title: "Multiple Checkboxes"
+    description: "CheckBoxField with multiple options storing values in an array"
+    toDescribe:
+      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
+
+  - type: RjBuildDescriber
+    title: "Radio Buttons"
+    description: "CheckBoxField as radio buttons for single selection"
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.priority
+          controlType: "radio"
+          options:
+            - label: "Low"
+              value: "low"
+            - label: "Medium"
+              value: "medium"
+            - label: "High"
+              value: "high"
+            - label: "Critical"
+              value: "critical"
+        - type: div
+          content:
+            - "Selected priority: "
+            - type: strong
+              content: ~.priority
+      data:
+        priority: ""
+
+  - type: RjBuildDescriber
+    title: "Single Checkbox"
+    description: "Single checkbox for boolean values"
+    toDescribe:
+      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
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+              padding: "10px"
+              backgroundColor: "#f8f9fa"
+              borderRadius: "5px"
+          content:
+            - type: strong
+              content: "Current Values:"
+            - type: div
+              content:
+                - "Terms accepted: "
+                - type: span
+                  content: "✓ Yes"
+                  attributes:
+                    style:
+                      color: "green"
+                  actions:
+                    - what: hide
+                      when: ~.acceptTerms
+                      isNot: true
+                - type: span
+                  content: "✗ No"
+                  attributes:
+                    style:
+                      color: "red"
+                  actions:
+                    - what: hide
+                      when: ~.acceptTerms
+                      is: true
+            - type: div
+              content:
+                - "Newsletter: "
+                - type: span
+                  content: "✓ Yes"
+                  attributes:
+                    style:
+                      color: "green"
+                  actions:
+                    - what: hide
+                      when: ~.newsletter
+                      isNot: true
+                - type: span
+                  content: "✗ No"
+                  attributes:
+                    style:
+                      color: "red"
+                  actions:
+                    - what: hide
+                      when: ~.newsletter
+                      is: true
+      data:
+        acceptTerms: false
+        newsletter: false
+
+  - type: Markdown
+    content: |
+      ## 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
+      ```
+
+  - type: RjBuildDescriber
+    title: "Dynamic Options"
+    description:
+      type: Markdown
+      content: |
+        CheckBoxField with conditional display using `dynamicOptions` and `hide` actions.
+        
+        **Technique**: Since dynamic path selection like `~.data[~.key]` is not supported, 
+        we create one CheckBoxField per category and use conditional `hide` actions to show 
+        only the relevant one based on the selection.
+    toDescribe:
+      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"
+
+  - type: RjBuildDescriber
+    title: "Option Attributes"
+    description: "CheckBoxField with custom attributes on options"
+    toDescribe:
+      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"
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+              padding: "10px"
+              backgroundColor: "#f8f9fa"
+              borderRadius: "5px"
+          content:
+            - type: strong
+              content: "Selected Notifications:"
+            - type: div
+              content:
+                - "Current: "
+                - ~.notifications
+            - type: div
+              content: "Note: SMS is disabled (premium feature)"
+              attributes:
+                style:
+                  fontSize: "12px"
+                  color: "#666"
+      data:
+        notifications: []
+
+  - type: Markdown
+    content: |
+      ## 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
+
+templates: {}
+data: {} 

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

@@ -0,0 +1,189 @@
+# DateField
+
+The `DateField` component renders a date and time input field using React Bootstrap. It provides a datetime-local input type for selecting both date and time values with automatic data binding to the global data context.
+
+> **Warning**
+> This component has limited support and is marked as TODO in the codebase. Currently only supports `datetime-local` input type.
+
+## Properties
+
+- `dataLocation` (string, optional): Path to bind the field value in the data context
+- `defaultFieldValue` (string, optional): Default value when no data is present
+- `label` (string, optional): Field label text
+- `attributes` (object, optional): Attributes applied to the Form.Group container
+- `actions` (array, optional): Actions to execute based on field state. Supports both actions (hide, tooltip, etc.) and conditional reactions (setData, fetchData, etc.) with full conditional logic support
+
+## Data Management
+
+The component automatically synchronizes its value with the global data context as an ISO 8601 datetime string format (YYYY-MM-DDTHH:mm). When using `dataLocation`, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.
+
+## Date Format
+
+The component uses the HTML5 `datetime-local` input type which:
+- Displays a date and time picker in the browser
+- Returns values in ISO 8601 format: `YYYY-MM-DDTHH:mm`
+- Does not include timezone information
+- Appearance varies by browser and operating system
+
+## Basic Example
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.eventDate
+    label: "Event Date and Time:"
+
+data:
+  eventDate: null
+```
+
+## DateField with Default Value
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.deadline
+    label: "Project Deadline:"
+    defaultFieldValue: "2024-12-31T17:00"
+
+data:
+  deadline: null
+```
+
+## Multiple DateFields
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.startDate
+    label: "Start Date:"
+  - type: DateField
+    dataLocation: ~.endDate
+    label: "End Date:"
+  - type: DateField
+    dataLocation: ~.reminderDate
+    label: "Reminder Date:"
+
+data:
+  startDate: null
+  endDate: null
+  reminderDate: null
+```
+
+## Interactive Date Management
+
+Advanced example with conditional reactions and dynamic messaging:
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.meetingDate
+    label: "Meeting Date:"
+  - type: button
+    content: "Set to Tomorrow"
+    actions:
+      - what: setData
+        on: click
+        path: ~.meetingDate
+        value: "2024-12-25T14:00"
+  - type: button
+    content: "Clear Date"
+    actions:
+      - what: setData
+        on: click
+        path: ~.meetingDate
+        value: null
+  - type: button
+    content: "Validate Meeting"
+    actions:
+      - what: setData
+        on: click
+        path: ~.message
+        value: "✓ Meeting date is set!"
+        when: ~.meetingDate
+        isEmpty: "not"
+      - what: setData
+        on: click
+        path: ~.message
+        value: "⚠ Please select a meeting date first"
+        when: ~.meetingDate
+        isEmpty: true
+
+data:
+  meetingDate: null
+  message: null
+```
+
+## Complete Example
+
+A comprehensive example showing DateField in different contexts:
+
+```yaml
+renderView:
+  - type: DateField
+    dataLocation: ~.eventDate
+    label: "Event Date and Time:"
+  - type: DateField
+    dataLocation: ~.deadline
+    label: "Deadline:"
+    defaultFieldValue: "2024-12-31T23:59"
+  - type: div
+    content:
+      - "Event: "
+      - ~.eventDate
+  - type: div
+    content:
+      - "Deadline: "
+      - ~.deadline
+
+data:
+  eventDate: null
+  deadline: null
+```
+
+## Current Limitations
+
+> **Development Status**
+> The DateField component is currently limited and marked as TODO in the codebase. However, it integrates fully with reactive-json's action and reaction system for rich interactivity.
+
+### Component Limitations
+- Only supports `datetime-local` input type (hardcoded)
+- No support for `date` input type (date only)
+- No support for `time` input type (time only)
+- No support for `month` or `week` input types
+- No built-in date formatting or localization
+- No timezone handling or conversion
+- No support for inputAttributes property (not implemented)
+- No template evaluation support for label property
+
+### Browser and Validation Limitations
+- No date validation beyond browser defaults
+- No support for date ranges or multiple date selection
+- No support for custom date picker libraries
+- Limited browser compatibility for datetime-local input
+
+### Workarounds Available
+- ✅ **Date validation**: Use conditional reactions with `isEmpty`, `andConditions`, `orConditions`
+- ✅ **Interactive behavior**: Full support for conditional actions and reactions
+- ✅ **Dynamic messaging**: Use setData reactions to provide user feedback
+- ✅ **Complex logic**: Combine multiple DateFields with sophisticated conditional logic
+
+## Browser Compatibility
+
+The `datetime-local` input type has varying support across browsers:
+- Modern browsers provide native date/time pickers
+- Older browsers may fall back to text input
+- Mobile browsers typically provide optimized date/time selection interfaces
+- Appearance and behavior can vary significantly between browsers
+
+## Future Improvements
+
+The component is marked for future enhancement to support:
+- Dedicated `date` input type for date-only selection
+- Dedicated `time` input type for time-only selection
+- Better validation and error handling
+- Custom date formatting options
+- Timezone support
+- Integration with date picker libraries
+- Support for inputAttributes property
+- Template evaluation for label property