@ea-lab/reactive-json-docs 1.2.0 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ea-lab/reactive-json-docs",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Complete documentation for Reactive-JSON - Components, examples and LLM-parsable guides",
   "main": "public/rjbuild/docs/index.yaml",
   "files": [
@@ -26,7 +26,7 @@
   "private": false,
   "devDependencies": {
     "@craco/craco": "^7.1.0",
-    "@ea-lab/reactive-json": "^1.1.0",
+    "@ea-lab/reactive-json": "^1.2.0",
     "@ea-lab/reactive-json-chartjs": "^1.0.0",
     "@npmcli/fs": "^4.0.0",
     "@reduxjs/toolkit": "^2.6.1",

package/public/rjbuild/docs/core/element/form/CheckBoxField.md

@@ -0,0 +1,364 @@
+# CheckBoxField
+
+The `CheckBoxField` component provides checkbox and radio button groups with automatic data synchronization. It supports single selection (radio buttons or single checkbox), multiple selection (multiple checkboxes), and flexible data storage formats.
+
+## Basic Syntax
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.preferences
+  label: "Select your preferences:"
+  options:
+    - label: "Option 1"
+      value: "opt1"
+    - label: "Option 2"
+      value: "opt2"
+    - label: "Option 3"
+      value: "opt3"
+```
+
+## Properties
+
+- `dataLocation` (string, optional): Path to bind the field value in the data context.
+- `defaultFieldValue` (any, optional): Default value when no data is present.
+- `label` (string or View props, optional): Field label text (supports template evaluation and View component rendering).
+- `options` (array, optional): Static array of option objects, each with:
+  - `label` (string, optional): Display text for the option (supports template evaluation).
+  - `value` (any, required): Value stored when this option is selected.
+  - `attributes` (object, optional): Attributes applied to the option's container div.
+- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided.
+- `controlType` (string, optional): Type of control - `"checkbox"` (default) or `"radio"`.
+- `multiple` (boolean, optional): Whether multiple selections are allowed. Defaults to `true` if more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`.
+- `attributes` (object, optional): Attributes applied to the wrapper div (or container div if no wrapper).
+- `inputAttributes` (object, optional): Attributes applied directly to each input element.
+- `labelAttributes` (object, optional): Attributes applied to the main label (htmlFor is automatically managed).
+- `forceWrapper` (boolean, optional): Forces the presence (true) or absence (false) of the wrapper div. If omitted, wrapper is automatic only if label is present.
+- `actions` (array, optional): Actions to execute based on field state.
+
+## Data Management
+
+The component automatically synchronizes its value with the global data context. The data format depends on the selection mode:
+
+- **Radio buttons**: Stores a single value (the selected option's value).
+- **Single checkbox**: Stores a boolean (`true`) or the option's value when checked, `false` when unchecked.
+- **Multiple checkboxes**: Stores an array of selected option values.
+
+When `dataLocation` is used, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.
+
+## Selection Modes
+
+### Radio Buttons (Single Selection)
+
+Radio buttons allow only one selection at a time. Set `controlType: "radio"`:
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.paymentMethod
+  label: "Payment Method:"
+  controlType: "radio"
+  options:
+    - label: "Credit Card"
+      value: "credit"
+    - label: "PayPal"
+      value: "paypal"
+    - label: "Bank Transfer"
+      value: "bank"
+```
+
+**Data stored**: Single value (e.g., `"credit"`)
+
+### Single Checkbox
+
+A single checkbox stores a boolean or the option's value:
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.agreeToTerms
+  label: "Terms and Conditions:"
+  multiple: false
+  options:
+    - label: "I agree to the terms and conditions"
+      value: true
+```
+
+**Data stored**: `true` when checked, `false` when unchecked (or the option's value if different from `true`)
+
+### Multiple Checkboxes
+
+Multiple checkboxes allow selecting several options simultaneously:
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.interests
+  label: "Select your interests:"
+  options:
+    - label: "Technology"
+      value: "tech"
+    - label: "Sports"
+      value: "sports"
+    - label: "Music"
+      value: "music"
+```
+
+**Data stored**: Array of selected values (e.g., `["tech", "music"]`)
+
+## Wrapper Control
+
+The component uses a flexible wrapper system similar to `Input`, adapting based on the presence of a label and the `forceWrapper` property.
+
+### Default Behavior
+
+When no `forceWrapper` is specified, the component automatically determines whether to use a wrapper div. If a label is present, the component wraps both the label and checkbox elements in a div container. If no label is present, the checkboxes are rendered in a container div without an outer wrapper.
+
+### Explicit Control with `forceWrapper`
+
+You can override the default behavior using the `forceWrapper` property. Setting `forceWrapper: true` will always create a wrapper div, even without a label. Setting `forceWrapper: false` will never create a wrapper, even when a label is present.
+
+### HTML Output Examples
+
+**With label (automatic wrapper):**
+```html
+<div>
+  <label>Select options:</label>
+  <div>
+    <div>
+      <input type="checkbox" id="checkbox-abc123-0" value="opt1" />
+      <label htmlFor="checkbox-abc123-0">Option 1</label>
+    </div>
+    <div>
+      <input type="checkbox" id="checkbox-abc123-1" value="opt2" />
+      <label htmlFor="checkbox-abc123-1">Option 2</label>
+    </div>
+  </div>
+</div>
+```
+
+**Without label (container div only):**
+```html
+<div>
+  <div>
+    <input type="checkbox" id="checkbox-xyz789-0" value="opt1" />
+    <label htmlFor="checkbox-xyz789-0">Option 1</label>
+  </div>
+</div>
+```
+
+## Label Support
+
+The `label` property supports both simple strings and View component rendering, allowing for dynamic and complex label content:
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.options
+  label:
+    type: div
+    content:
+      - "Select options ("
+      - type: strong
+        content: ~.requiredCount
+      - " required):"
+  options:
+    - label: "Option 1"
+      value: "opt1"
+```
+
+## Option Attributes
+
+Each option can have its own attributes applied to its container div:
+
+```yaml
+- type: CheckBoxField
+  dataLocation: ~.features
+  options:
+    - label: "Premium Feature"
+      value: "premium"
+      attributes:
+        class: "premium-option"
+        style:
+          backgroundColor: "#ffd700"
+    - label: "Standard Feature"
+      value: "standard"
+      attributes:
+        class: "standard-option"
+```
+
+## ID Management
+
+The component automatically generates unique IDs for each checkbox/radio button. If you provide an `id` in `inputAttributes`, it will be used as the base ID, and each option will have an index appended (e.g., `"my-id-0"`, `"my-id-1"`).
+
+## Empty Options Handling
+
+If `options` is empty or not an array, the component returns `null` and renders nothing. This is useful for conditional rendering scenarios.
+
+## Examples
+
+### Basic Checkbox Group
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.preferences
+    label: "Select your preferences:"
+    options:
+      - label: "Email notifications"
+        value: "email"
+      - label: "SMS notifications"
+        value: "sms"
+      - label: "Push notifications"
+        value: "push"
+
+data:
+  preferences: []
+```
+
+### Radio Button Group
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.size
+    label: "Select size:"
+    controlType: "radio"
+    options:
+      - label: "Small"
+        value: "small"
+      - label: "Medium"
+        value: "medium"
+      - label: "Large"
+        value: "large"
+
+data:
+  size: ""
+```
+
+### Single Checkbox (Agreement)
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.agreeToTerms
+    label: "Terms:"
+    multiple: false
+    options:
+      - label: "I agree to the terms and conditions"
+        value: true
+
+data:
+  agreeToTerms: false
+```
+
+### Custom Styling
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.categories
+    label: "Select categories:"
+    attributes:
+      class: "checkbox-group"
+      style:
+        border: "1px solid #ccc"
+        padding: "10px"
+        borderRadius: "5px"
+    inputAttributes:
+      style:
+        marginRight: "5px"
+    labelAttributes:
+      style:
+        fontWeight: "bold"
+        marginBottom: "10px"
+    options:
+      - label: "Category 1"
+        value: "cat1"
+      - label: "Category 2"
+        value: "cat2"
+
+data:
+  categories: []
+```
+
+### Dynamic Options
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.selectedItems
+    label: "Select items:"
+    dynamicOptions: ~.availableItems
+
+data:
+  availableItems:
+    - label: "Item 1"
+      value: "item1"
+    - label: "Item 2"
+      value: "item2"
+    - label: "Item 3"
+      value: "item3"
+  selectedItems: []
+```
+
+### With Actions
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.notifications
+    label: "Notification preferences:"
+    options:
+      - label: "Email"
+        value: "email"
+      - label: "SMS"
+        value: "sms"
+    actions:
+      - what: setData
+        when: ~.notifications
+        isArray: true
+        path: ~.hasNotifications
+        value: true
+
+data:
+  notifications: []
+  hasNotifications: false
+```
+
+### Conditional Rendering
+
+```yaml
+renderView:
+  - type: CheckBoxField
+    dataLocation: ~.features
+    label: "Select features:"
+    dynamicOptions: ~.availableFeatures
+    actions:
+      - what: hide
+        when: ~.availableFeatures
+        isEmpty: true
+
+data:
+  availableFeatures:
+    - label: "Feature A"
+      value: "a"
+    - label: "Feature B"
+      value: "b"
+  features: []
+```
+
+## Advantages
+
+- **Flexible selection modes**: Supports radio buttons, single checkbox, and multiple checkboxes
+- **Automatic data synchronization**: Values are automatically stored in the correct format
+- **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+- **Per-option customization**: Each option can have its own attributes
+- **Label flexibility**: Supports both simple strings and View component rendering
+- **Wrapper control**: Flexible wrapper system for styling control
+- **Accessibility**: Automatic label association with htmlFor attributes
+- **Empty state handling**: Gracefully handles empty options
+
+## Limitations
+
+- No built-in validation beyond HTML5 checkbox/radio validation
+- No support for option grouping (use multiple CheckBoxField components)
+- Styling must be provided via external CSS or style attributes
+- Options must be provided as an array; empty arrays result in no rendering
+- For radio buttons, `multiple` is automatically set to `false` regardless of the `multiple` property
+

package/public/rjbuild/docs/core/element/form/CheckBoxField.yaml

@@ -0,0 +1,222 @@
+renderView:
+  - type: Markdown
+    content: |
+      # CheckBoxField
+
+      The `CheckBoxField` component provides checkbox and radio button groups with automatic data synchronization. It supports single selection (radio buttons or single checkbox), multiple selection (multiple checkboxes), and flexible data storage formats.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: CheckBoxField
+        dataLocation: ~.preferences
+        label: "Select your preferences:"
+        options:
+          - label: "Option 1"
+            value: "opt1"
+          - label: "Option 2"
+            value: "opt2"
+          - label: "Option 3"
+            value: "opt3"
+      ```
+
+      ## Properties
+
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "Path to bind the field value in the data context."
+      - term:
+          code: defaultFieldValue
+          after: "(any, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string or View props, optional)"
+        details: "Field label text (supports template evaluation and View component rendering)."
+      - term:
+          code: options
+          after: "(array, optional)"
+        details:
+          type: Markdown
+          content: |
+            Static array of option objects, each with:
+            - `label` (string, optional): Display text for the option (supports template evaluation)
+            - `value` (any, required): Value stored when this option is selected
+            - `attributes` (object, optional): Attributes applied to the option's container div
+      - term:
+          code: dynamicOptions
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "Template path to dynamic options array (e.g., `~.availableItems`). Takes precedence over `options` if both are provided."
+      - term:
+          code: controlType
+          after: "(string, optional)"
+        details: "Type of control - `\"checkbox\"` (default) or `\"radio\"`."
+      - term:
+          code: multiple
+          after: "(boolean, optional)"
+        details: "Whether multiple selections are allowed. Defaults to `true` if more than one option exists, `false` otherwise. For radio buttons, this is automatically `false`."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the wrapper div (or container div if no wrapper)."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to each input element."
+      - term:
+          code: labelAttributes
+          after: "(object, optional)"
+        details: "Attributes applied to the main label (htmlFor is automatically managed)."
+      - term:
+          code: forceWrapper
+          after: "(boolean, optional)"
+        details: "Forces the presence (true) or absence (false) of the wrapper div. If omitted, wrapper is automatic only if label is present."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on field state."
+
+  - type: Markdown
+    content: |
+      ## Data Management
+
+      The component automatically synchronizes its value with the global data context. The data format depends on the selection mode:
+
+      - **Radio buttons**: Stores a single value (the selected option's value)
+      - **Single checkbox**: Stores a boolean (`true`) or the option's value when checked, `false` when unchecked
+      - **Multiple checkboxes**: Stores an array of selected option values
+
+      When `dataLocation` is used, the value is stored at the specified path. Without `dataLocation`, the value is stored in the template context using the component's `datafield`.
+
+      ## Selection Modes
+
+      ### Radio Buttons (Single Selection)
+
+      Radio buttons allow only one selection at a time. Set `controlType: "radio"`:
+
+      **Data stored**: Single value (e.g., `"credit"`)
+
+      ### Single Checkbox
+
+      A single checkbox stores a boolean or the option's value:
+
+      **Data stored**: `true` when checked, `false` when unchecked (or the option's value if different from `true`)
+
+      ### Multiple Checkboxes
+
+      Multiple checkboxes allow selecting several options simultaneously:
+
+      **Data stored**: Array of selected values (e.g., `["tech", "music"]`)
+
+  - type: RjBuildDescriber
+    title: "Basic Checkbox Group"
+    description: "Simple multiple selection checkbox group"
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.preferences
+          label: "Select your preferences:"
+          options:
+            - label: "Email notifications"
+              value: "email"
+            - label: "SMS notifications"
+              value: "sms"
+            - label: "Push notifications"
+              value: "push"
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+              padding: "10px"
+              borderRadius: "5px"
+          content:
+            - type: strong
+              content: "Selected: "
+            - ~.preferences
+      data:
+        preferences: []
+
+  - type: RjBuildDescriber
+    title: "Radio Button Group"
+    description: "Single selection using radio buttons"
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.size
+          label: "Select size:"
+          controlType: "radio"
+          options:
+            - label: "Small"
+              value: "small"
+            - label: "Medium"
+              value: "medium"
+            - label: "Large"
+              value: "large"
+            - label: "Extra Large"
+              value: "xl"
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+              padding: "10px"
+              borderRadius: "5px"
+          content:
+            - type: strong
+              content: "Selected size: "
+            - ~.size
+      data:
+        size: ""
+
+  - type: RjBuildDescriber
+    title: "Dynamic Options"
+    description: "Options provided via template evaluation using dynamicOptions"
+    toDescribe:
+      renderView:
+        - type: CheckBoxField
+          dataLocation: ~.selectedItems
+          label: "Select items:"
+          dynamicOptions: ~.availableItems
+      data:
+        availableItems:
+          - label: "Item 1"
+            value: "item1"
+          - label: "Item 2"
+            value: "item2"
+          - label: "Item 3"
+            value: "item3"
+          - label: "Item 4"
+            value: "item4"
+        selectedItems: []
+
+
+  - type: Markdown
+    content: |
+      ## Advantages
+
+      - **Flexible selection modes**: Supports radio buttons, single checkbox, and multiple checkboxes
+      - **Automatic data synchronization**: Values are automatically stored in the correct format
+      - **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+      - **Per-option customization**: Each option can have its own attributes
+      - **Label flexibility**: Supports both simple strings and View component rendering
+      - **Wrapper control**: Flexible wrapper system for styling control
+      - **Accessibility**: Automatic label association with htmlFor attributes
+      - **Empty state handling**: Gracefully handles empty options
+
+      ## Limitations
+
+      - No built-in validation beyond HTML5 checkbox/radio validation
+      - No support for option grouping (use multiple CheckBoxField components)
+      - Styling must be provided via external CSS or style attributes
+      - Options must be provided as an array; empty arrays result in no rendering
+      - For radio buttons, `multiple` is automatically set to `false` regardless of the `multiple` property
+
+templates: {}
+data: {}
+