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

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

@@ -0,0 +1,384 @@
+# SelectField
+
+The `SelectField` component provides a native HTML select dropdown with automatic data synchronization, intelligent value type handling, and support for dynamic options. It combines the simplicity of native HTML with the convenience of automatic data binding.
+
+## Basic Syntax
+
+```yaml
+- type: SelectField
+  dataLocation: ~.category
+  label: "Select category:"
+  options:
+    - label: "Choose category..."
+      value: ""
+    - label: "Technology"
+      value: "tech"
+    - label: "Sports"
+      value: "sports"
+```
+
+## 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 with `label` and `value` properties.
+- `dynamicOptions` (string, optional): Template path to dynamic options array (e.g., `~.availableCategories`). Takes precedence over `options` if both are provided.
+- `allowEmptyStringAsValue` (boolean, optional): Preserve empty strings as `""` instead of converting to `undefined` (default: `false`).
+- `attributes` (object, optional): Attributes applied to the container div (or merged with inputAttributes if no wrapper).
+- `inputAttributes` (object, optional): Attributes applied directly to the select element.
+- `labelAttributes` (object, optional): Attributes applied to the 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. It handles different value types intelligently:
+
+### Value Type Conversion
+
+- **Empty strings**: Become `undefined` by default, or preserved as `""` if `allowEmptyStringAsValue: true`
+- **Boolean strings**: `"true"` becomes boolean `true`, `"false"` becomes boolean `false`
+- **Null string**: `"null"` becomes `null`
+- **Other values**: Stored as strings and matched by string comparison
+
+### Empty String Handling
+
+SelectField makes an important distinction between "no selection made" and "explicit selection of empty value":
+
+- **Default behavior**: `value: ""` → stored as `undefined`
+  - Useful for validation and conditional logic
+  - Indicates "no selection made"
+- **With `allowEmptyStringAsValue: true`**: `value: ""` → stored as `""`
+  - Semantic meaning: "User explicitly selected the empty option"
+  - Useful when empty string is a legitimate business value
+
+This distinction is crucial for validation logic and conditional actions in reactive-json.
+
+## 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 select in a div container. If no label is present, the select is rendered directly without a 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 htmlFor="select-abc123">Select category:</label>
+  <select id="select-abc123">
+    <option value="">Choose category...</option>
+    <option value="tech">Technology</option>
+  </select>
+</div>
+```
+
+**Without label (no wrapper):**
+```html
+<select id="select-xyz789">
+  <option value="">Choose category...</option>
+  <option value="tech">Technology</option>
+</select>
+```
+
+### Attribute Merging
+
+When a wrapper is present, the `attributes` are applied to the div container and `inputAttributes` are applied to the select element. When no wrapper is present, both `attributes` and `inputAttributes` are merged and applied to the select element.
+
+## Label Support
+
+The `label` property supports both simple strings and View component rendering, allowing for dynamic and complex label content:
+
+```yaml
+- type: SelectField
+  dataLocation: ~.category
+  label:
+    type: div
+    content:
+      - "Select category ("
+      - type: strong
+        content: ~.requiredText
+      - "):"
+  dynamicOptions: ~.categories
+```
+
+## Option Labels
+
+Option labels support template evaluation, allowing dynamic content:
+
+```yaml
+- type: SelectField
+  dataLocation: ~.item
+  options:
+    - label: "Item: ~.itemName"
+      value: "item1"
+    - label: ["Count: ", ~.count]
+      value: "item2"
+```
+
+## Empty Options Handling
+
+If `options` is empty or not an array, the component displays a single option: "No options available". This is useful for conditional rendering scenarios where options may be loaded dynamically.
+
+## Examples
+
+### Basic SelectField
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.priority
+    label: "Priority:"
+    options:
+      - label: "Select priority"
+        value: ""
+      - label: "Low"
+        value: "low"
+      - label: "Medium"
+        value: "medium"
+      - label: "High"
+        value: "high"
+
+data:
+  priority: ""
+```
+
+### Boolean and Special Values
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.isActive
+    label: "Status:"
+    options:
+      - label: "Select status"
+        value: ""
+      - label: "Active"
+        value: "true"
+      - label: "Inactive"
+        value: "false"
+      - label: "Not set"
+        value: "null"
+
+data:
+  isActive: ""
+```
+
+### Empty String as Value
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.description
+    label: "Description:"
+    allowEmptyStringAsValue: true
+    options:
+      - label: "No description"
+        value: ""
+      - label: "Brief description"
+        value: "brief"
+      - label: "Detailed description"
+        value: "detailed"
+
+data:
+  description: ""
+```
+
+### Dynamic Options
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.selectedCategory
+    label: "Category:"
+    dynamicOptions: ~.availableCategories
+
+data:
+  availableCategories:
+    - label: "Technology"
+      value: "tech"
+    - label: "Sports"
+      value: "sports"
+    - label: "Music"
+      value: "music"
+  selectedCategory: ""
+```
+
+### Custom Attributes
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.country
+    label: "Country:"
+    inputAttributes:
+      required: true
+      style:
+        width: "100%"
+        padding: "8px"
+    attributes:
+      style:
+        marginBottom: "10px"
+    options:
+      - label: "Select country"
+        value: ""
+      - label: "United States"
+        value: "us"
+      - label: "Canada"
+        value: "ca"
+
+data:
+  country: ""
+```
+
+### Wrapper Control
+
+```yaml
+renderView:
+  # No label → no wrapper automatically
+  - type: SelectField
+    dataLocation: ~.noWrapper
+    options:
+      - label: "Option 1"
+        value: "opt1"
+    
+  # With label → automatic wrapper
+  - type: SelectField
+    dataLocation: ~.autoWrapper
+    label: "With automatic wrapper:"
+    options:
+      - label: "Option 1"
+        value: "opt1"
+    
+  # Force wrapper even without label
+  - type: SelectField
+    dataLocation: ~.forceWrapper
+    options:
+      - label: "Option 1"
+        value: "opt1"
+    forceWrapper: true
+    attributes:
+      style:
+        border: "2px solid blue"
+        padding: "10px"
+        
+  # No wrapper even with label
+  - type: SelectField
+    dataLocation: ~.noWrapperForced
+    label: "Label without wrapper:"
+    options:
+      - label: "Option 1"
+        value: "opt1"
+    forceWrapper: false
+
+data:
+  noWrapper: ""
+  autoWrapper: ""
+  forceWrapper: ""
+  noWrapperForced: ""
+```
+
+### Custom Label Attributes
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.customLabel
+    label: "Custom label:"
+    labelAttributes:
+      style:
+        color: "blue"
+        fontWeight: "bold"
+        fontSize: "14px"
+      className: "custom-label"
+    options:
+      - label: "Option 1"
+        value: "opt1"
+
+data:
+  customLabel: ""
+```
+
+### With Actions
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.category
+    label: "Category:"
+    options:
+      - label: "Select category"
+        value: ""
+      - label: "Technology"
+        value: "tech"
+      - label: "Sports"
+        value: "sports"
+    actions:
+      - what: setData
+        when: ~.category
+        isEmpty: true
+        path: ~.hasCategory
+        value: false
+      - what: setData
+        when: ~.category
+        isNot: ""
+        path: ~.hasCategory
+        value: true
+
+data:
+  category: ""
+  hasCategory: false
+```
+
+### Multiple Select (using `multiple` attribute)
+
+```yaml
+renderView:
+  - type: SelectField
+    dataLocation: ~.selectedItems
+    label: "Select multiple items:"
+    inputAttributes:
+      multiple: true
+    options:
+      - label: "Item 1"
+        value: "item1"
+      - label: "Item 2"
+        value: "item2"
+      - label: "Item 3"
+        value: "item3"
+
+data:
+  selectedItems: []
+```
+
+**Note**: For multiple selection, the component stores an array. However, native HTML select multiple is limited. Consider using `CheckBoxField` with `multiple: true` for better UX.
+
+## Advantages
+
+- **No external dependencies**: Works without any CSS framework
+- **Full control**: Custom styling and behavior
+- **Performance**: Lighter than component libraries
+- **Accessibility**: Direct control over ARIA attributes, automatic htmlFor
+- **Automatic synchronization**: Unlike raw HTML elements that require manual setData actions
+- **Flexible wrapper**: Avoids unnecessary HTML when not needed
+- **Intelligent value handling**: Automatic conversion of boolean and null strings
+- **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+- **Label flexibility**: Supports both simple strings and View component rendering
+- **Empty state handling**: Gracefully handles empty options
+
+## Limitations
+
+- No built-in validation beyond HTML5 select validation
+- No support for option grouping (use multiple SelectField components or custom styling)
+- Styling must be provided via external CSS or style attributes
+- Multiple selection via `multiple` attribute has limited UX (consider CheckBoxField for better multiple selection)
+- Template evaluation for option labels should return strings or arrays of strings
+- Empty string handling requires explicit `allowEmptyStringAsValue` for semantic distinction
+

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

@@ -0,0 +1,252 @@
+renderView:
+  - type: Markdown
+    content: |
+      # SelectField
+
+      The `SelectField` component provides a native HTML select dropdown with automatic data synchronization, intelligent value type handling, and support for dynamic options. It combines the simplicity of native HTML with the convenience of automatic data binding.
+
+  - type: Markdown
+    content: |
+      ## Basic Syntax
+
+      ```yaml
+      - type: SelectField
+        dataLocation: ~.category
+        label: "Select category:"
+        options:
+          - label: "Choose category..."
+            value: ""
+          - label: "Technology"
+            value: "tech"
+          - label: "Sports"
+            value: "sports"
+      ```
+
+      ## 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 with `label` and `value` properties."
+      - term:
+          code: dynamicOptions
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "Template path to dynamic options array (e.g., `~.availableCategories`). Takes precedence over `options` if both are provided."
+      - term:
+          code: allowEmptyStringAsValue
+          after: "(boolean, optional)"
+        details: "Preserve empty strings as `\"\"` instead of converting to `undefined` (default: `false`)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the container div (or merged with inputAttributes if no wrapper)."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the select element."
+      - term:
+          code: labelAttributes
+          after: "(object, optional)"
+        details: "Attributes applied to the 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. It handles different value types intelligently:
+
+      ### Value Type Conversion
+
+      - **Empty strings**: Become `undefined` by default, or preserved as `""` if `allowEmptyStringAsValue: true`
+      - **Boolean strings**: `"true"` becomes boolean `true`, `"false"` becomes boolean `false`
+      - **Null string**: `"null"` becomes `null`
+      - **Other values**: Stored as strings and matched by string comparison
+
+      ### Empty String Handling
+
+      SelectField makes an important distinction between "no selection made" and "explicit selection of empty value":
+
+      - **Default behavior**: `value: ""` → stored as `undefined`
+        - Useful for validation and conditional logic
+        - Indicates "no selection made"
+      - **With `allowEmptyStringAsValue: true`**: `value: ""` → stored as `""`
+        - Semantic meaning: "User explicitly selected the empty option"
+        - Useful when empty string is a legitimate business value
+
+      This distinction is crucial for validation logic and conditional actions in reactive-json.
+
+  - type: RjBuildDescriber
+    title: "Basic SelectField"
+    description: "Simple dropdown selection"
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.priority
+          label: "Priority:"
+          options:
+            - label: "Select priority"
+              value: ""
+            - label: "Low"
+              value: "low"
+            - label: "Medium"
+              value: "medium"
+            - label: "High"
+              value: "high"
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Selected priority: "
+            - ~.priority
+      data:
+        priority: ""
+
+  - type: RjBuildDescriber
+    title: "Boolean and Special Values"
+    description: "Handling boolean and null values"
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.isActive
+          label: "Status:"
+          options:
+            - label: "Select status"
+              value: ""
+            - label: "Active"
+              value: "true"
+            - label: "Inactive"
+              value: "false"
+            - label: "Not set"
+              value: "null"
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Status value: "
+            - ~.isActive
+            - type: div
+              attributes:
+                class: "mt-1 text-xs text-gray-600 dark:text-gray-400"
+              content:
+                - "Type: "
+                - type: Code
+                  content: ~.isActive
+      data:
+        isActive: ""
+
+  - type: RjBuildDescriber
+    title: "Empty String as Value"
+    description: "Preserving empty strings as legitimate values"
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.description
+          label: "Description:"
+          allowEmptyStringAsValue: true
+          options:
+            - label: "No description"
+              value: ""
+            - label: "Brief description"
+              value: "brief"
+            - label: "Detailed description"
+              value: "detailed"
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Selected description: "
+            - type: Code
+              content: ~.description
+            - type: div
+              attributes:
+                class: "mt-1 text-xs text-gray-600 dark:text-gray-400"
+              content:
+                - "Note: Empty string is preserved as \"\" (not undefined)"
+      data:
+        description: ""
+
+  - type: RjBuildDescriber
+    title: "Dynamic Options"
+    description: "Options provided via template evaluation using dynamicOptions"
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.selectedCategory
+          label: "Category:"
+          dynamicOptions: ~.availableCategories
+        - type: div
+          attributes:
+            class: "mt-5 p-2.5 rounded border border-gray-300 dark:border-gray-600"
+          content:
+            - type: strong
+              content: "Selected category: "
+            - ~.selectedCategory
+      data:
+        availableCategories:
+          - label: "Technology"
+            value: "tech"
+          - label: "Sports"
+            value: "sports"
+          - label: "Music"
+            value: "music"
+          - label: "Science"
+            value: "science"
+        selectedCategory: ""
+
+
+  - type: Markdown
+    content: |
+      ## Advantages
+
+      - **No external dependencies**: Works without any CSS framework
+      - **Full control**: Custom styling and behavior
+      - **Performance**: Lighter than component libraries
+      - **Accessibility**: Direct control over ARIA attributes, automatic htmlFor
+      - **Automatic synchronization**: Unlike raw HTML elements that require manual setData actions
+      - **Flexible wrapper**: Avoids unnecessary HTML when not needed
+      - **Intelligent value handling**: Automatic conversion of boolean and null strings
+      - **Dynamic options**: Options can be provided via template evaluation using `dynamicOptions`
+      - **Label flexibility**: Supports both simple strings and View component rendering
+      - **Empty state handling**: Gracefully handles empty options
+
+      ## Limitations
+
+      - No built-in validation beyond HTML5 select validation
+      - No support for option grouping (use multiple SelectField components or custom styling)
+      - Styling must be provided via external CSS or style attributes
+      - Multiple selection via `multiple` attribute has limited UX (consider CheckBoxField for better multiple selection)
+      - Template evaluation for option labels should return strings or arrays of strings
+      - Empty string handling requires explicit `allowEmptyStringAsValue` for semantic distinction
+
+templates: {}
+data: {}
+