@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,134 @@
+# TextAreaField
+
+The `TextAreaField` component renders a multi-line text input field using React Bootstrap. It provides a resizable textarea for longer text content with automatic data binding to the global data context.
+
+## 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 (supports template evaluation)
+- `placeholder` (string, optional): Placeholder text (supports template evaluation)
+- `rows` (number, optional): Number of visible text lines (default: 3)
+- `attributes` (object, optional): Attributes applied to the Form.Group container
+- `inputAttributes` (object, optional): Attributes applied directly to the textarea element
+- `actions` (array, optional): Actions to execute based on field state
+
+## Data Management
+
+The component automatically synchronizes its value with the global data context. 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`.
+
+## Textarea Features
+
+The component provides standard HTML textarea functionality:
+- Multi-line text input
+- Automatic line breaks and wrapping
+- Resizable by default (can be controlled via CSS)
+- Character counting support via attributes
+- Scrollable content when exceeding visible area
+
+## Basic Example
+
+```yaml
+renderView:
+  - type: TextAreaField
+    dataLocation: ~.comments
+    label: "Comments:"
+    placeholder: "Enter your comments here..."
+    rows: 4
+
+data:
+  comments: ""
+```
+
+## Character Limiter
+
+```yaml
+renderView:
+  - type: TextAreaField
+    dataLocation: ~.feedback
+    label: "Feedback (max 200 characters):"
+    placeholder: "Your feedback..."
+    rows: 4
+    inputAttributes:
+      maxLength: 200
+
+data:
+  feedback: ""
+```
+
+## Custom Styling
+
+```yaml
+renderView:
+  - type: TextAreaField
+    dataLocation: ~.code
+    label: "Code Snippet:"
+    placeholder: "Enter your code here..."
+    rows: 6
+    inputAttributes:
+      style:
+        fontFamily: "monospace"
+        fontSize: "14px"
+        backgroundColor: "#f8f9fa"
+        border: "1px solid #ced4da"
+        resize: "vertical"
+      spellCheck: false
+  - type: TextAreaField
+    dataLocation: ~.poetry
+    label: "Poetry (no resize):"
+    placeholder: "Write your poem..."
+    rows: 4
+    inputAttributes:
+      style:
+        fontStyle: "italic"
+        resize: "none"
+        backgroundColor: "#fff8dc"
+
+data:
+  code: ""
+  poetry: ""
+```
+
+## Complete Example
+
+A comprehensive example showing different TextAreaField configurations:
+
+```yaml
+renderView:
+  - type: TextAreaField
+    dataLocation: ~.comments
+    label: "Comments:"
+    placeholder: "Enter your comments here..."
+    rows: 4
+    inputAttributes:
+      maxLength: 500
+  - type: TextAreaField
+    dataLocation: ~.description
+    label: "Product Description:"
+    placeholder: "Describe the product features..."
+    rows: 6
+    inputAttributes:
+      style:
+        resize: "vertical"
+  - type: div
+    content:
+      - "Comments: "
+      - ~.comments
+  - type: div
+    content:
+      - "Description: "
+      - ~.description
+
+data:
+  comments: ""
+  description: ""
+```
+
+## Limitations
+
+- No built-in rich text editing capabilities
+- No automatic text formatting or markdown support
+- No built-in character counting display
+- No built-in validation beyond HTML5 attributes
+- No support for auto-resizing based on content
+- No built-in spell checking configuration options 

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

@@ -0,0 +1,146 @@
+renderView:
+  - type: Markdown
+    content: |
+      # TextAreaField
+
+      The `TextAreaField` component renders a multi-line text input field using React Bootstrap. It provides a resizable textarea for longer text content with automatic data binding to the global data context.
+
+      ## 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 (supports template evaluation)
+      - `placeholder` (string, optional): Placeholder text (supports template evaluation)
+      - `rows` (number, optional): Number of visible text lines (default: 3)
+      - `attributes` (object, optional): Attributes applied to the Form.Group container
+      - `inputAttributes` (object, optional): Attributes applied directly to the textarea element
+      - `actions` (array, optional): Actions to execute based on field state
+
+      ## Data Management
+
+      The component automatically synchronizes its value with the global data context. 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`.
+
+      ## Textarea Features
+
+      The component provides standard HTML textarea functionality:
+      - Multi-line text input
+      - Automatic line breaks and wrapping
+      - Resizable by default (can be controlled via CSS)
+      - Character counting support via attributes
+      - Scrollable content when exceeding visible area
+
+  - type: RjBuildDescriber
+    title: "Basic TextAreaField Usage"
+    description: "Simple multi-line text input with label and placeholder"
+    toDescribe:
+      renderView:
+        - type: TextAreaField
+          dataLocation: ~.comments
+          label: "Comments:"
+          placeholder: "Enter your comments here..."
+          rows: 4
+        - type: div
+          content:
+            - "Current value: "
+            - type: strong
+              content: ~.comments
+      data:
+        comments: ""
+
+  - type: RjBuildDescriber
+    title: "Character Limiter"
+    description: "TextAreaField with character limit restriction"
+    toDescribe:
+      renderView:
+        - type: TextAreaField
+          dataLocation: ~.feedback
+          label: "Feedback (max 200 characters):"
+          placeholder: "Your feedback..."
+          rows: 4
+          inputAttributes:
+            maxLength: 200
+        - type: div
+          content:
+            - "Feedback: "
+            - ~.feedback
+      data:
+        feedback: ""
+
+  - type: RjBuildDescriber
+    title: "Custom Styling"
+    description: "TextAreaField with custom styles and attributes"
+    toDescribe:
+      renderView:
+        - type: TextAreaField
+          dataLocation: ~.code
+          label: "Code Snippet:"
+          placeholder: "Enter your code here..."
+          rows: 6
+          inputAttributes:
+            style:
+              fontFamily: "monospace"
+              fontSize: "14px"
+              backgroundColor: "#f8f9fa"
+              border: "1px solid #ced4da"
+              resize: "vertical"
+            spellCheck: false
+        - type: TextAreaField
+          dataLocation: ~.poetry
+          label: "Poetry (no resize):"
+          placeholder: "Write your poem..."
+          rows: 4
+          inputAttributes:
+            style:
+              fontStyle: "italic"
+              resize: "none"
+              backgroundColor: "#fff8dc"
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+          content:
+            - type: strong
+              content: "Preview:"
+            - type: div
+              attributes:
+                style:
+                  fontFamily: "monospace"
+                  backgroundColor: "#f8f9fa"
+                  padding: "10px"
+                  borderRadius: "4px"
+                  marginTop: "5px"
+              content: ~.code
+              actions:
+                - what: hide
+                  when: ~.code
+                  is: ""
+            - type: div
+              attributes:
+                style:
+                  fontStyle: "italic"
+                  backgroundColor: "#fff8dc"
+                  padding: "10px"
+                  borderRadius: "4px"
+                  marginTop: "5px"
+              content: ~.poetry
+              actions:
+                - what: hide
+                  when: ~.poetry
+                  is: ""
+      data:
+        code: ""
+        poetry: ""
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - No built-in rich text editing capabilities
+      - No automatic text formatting or markdown support
+      - No built-in character counting display
+      - No built-in validation beyond HTML5 attributes
+      - No support for auto-resizing based on content
+      - No built-in spell checking configuration options
+
+templates: {}
+data: {} 

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

@@ -0,0 +1,129 @@
+# TextField
+
+The `TextField` component renders a single-line text input field using React Bootstrap. It supports various input types, template evaluation for dynamic content, and automatic data binding to the global data context.
+
+## 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 (supports template evaluation)
+- `placeholder` (string, optional): Placeholder text (supports template evaluation)
+- `inputType` (string, optional): HTML input type (default: "text", supports template evaluation)
+- `attributes` (object, optional): Attributes applied to the Form.Group container
+- `inputAttributes` (object, optional): Attributes applied directly to the input element
+- `actions` (array, optional): Actions to execute based on field state
+
+## Data Management
+
+The component automatically synchronizes its value with the global data context. 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`.
+
+## Input Types
+
+The `inputType` property supports all HTML5 input types:
+- `text` (default): Standard text input
+- `email`: Email validation
+- `password`: Masked password input
+- `url`: URL validation
+- `tel`: Telephone number input
+- `search`: Search input with clear button
+
+## Basic Example
+
+```yaml
+renderView:
+  - type: TextField
+    dataLocation: ~.username
+    label: "Username:"
+    placeholder: "Enter your username"
+
+data:
+  username: ""
+```
+
+## Different Input Types
+
+```yaml
+renderView:
+  - type: TextField
+    dataLocation: ~.email
+    label: "Email:"
+    placeholder: "user@example.com"
+    inputType: "email"
+  - type: TextField
+    dataLocation: ~.password
+    label: "Password:"
+    placeholder: "Enter password"
+    inputType: "password"
+  - type: TextField
+    dataLocation: ~.website
+    label: "Website:"
+    placeholder: "https://example.com"
+    inputType: "url"
+
+data:
+  email: ""
+  password: ""
+  website: ""
+```
+
+## Input Attributes
+
+```yaml
+renderView:
+  - type: TextField
+    dataLocation: ~.productCode
+    label: "Product Code:"
+    placeholder: "ABC-123"
+    inputAttributes:
+      pattern: "[A-Z]{3}-[0-9]{3}"
+      title: "Format: ABC-123 (3 letters, dash, 3 numbers)"
+      maxLength: 7
+      style:
+        textTransform: "uppercase"
+
+data:
+  productCode: ""
+```
+
+## Complete Example
+
+A comprehensive example showing different TextField configurations:
+
+```yaml
+renderView:
+  - type: TextField
+    dataLocation: ~.username
+    label: "Username:"
+    placeholder: "Enter your username"
+    inputType: "text"
+    inputAttributes:
+      maxLength: 50
+      autoComplete: "username"
+  - type: TextField
+    dataLocation: ~.email
+    label: "Email Address:"
+    placeholder: "user@example.com"
+    inputType: "email"
+    inputAttributes:
+      required: true
+  - type: div
+    content:
+      - "Username: "
+      - ~.username
+  - type: div
+    content:
+      - "Email: "
+      - ~.email
+
+data:
+  username: ""
+  email: ""
+```
+
+## Limitations
+
+- No built-in validation beyond HTML5 input type validation
+- No support for input masking or formatting
+- No built-in error message display
+- Template evaluation for `inputType` should return valid HTML input types
+- No support for complex input patterns beyond HTML5 pattern attribute 

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

@@ -0,0 +1,147 @@
+renderView:
+  - type: Markdown
+    content: |
+      # TextField
+
+      The `TextField` component renders a single-line text input field using React Bootstrap. It supports various input types, template evaluation for dynamic content, and automatic data binding to the global data context.
+
+      ## 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 (supports template evaluation)
+      - `placeholder` (string, optional): Placeholder text (supports template evaluation)
+      - `inputType` (string, optional): HTML input type (default: "text", supports template evaluation)
+      - `attributes` (object, optional): Attributes applied to the Form.Group container
+      - `inputAttributes` (object, optional): Attributes applied directly to the input element
+      - `actions` (array, optional): Actions to execute based on field state
+
+      ## Data Management
+
+      The component automatically synchronizes its value with the global data context. 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`.
+
+      ## Input Types
+
+      The `inputType` property supports all HTML5 input types:
+      - `text` (default): Standard text input
+      - `email`: Email validation
+      - `password`: Masked password input
+      - `url`: URL validation
+      - `tel`: Telephone number input
+      - `search`: Search input with clear button
+
+  - type: RjBuildDescriber
+    title: "Basic TextField Usage"
+    description: "Simple text input with label and placeholder"
+    toDescribe:
+      renderView:
+        - type: TextField
+          dataLocation: ~.username
+          label: "Username:"
+          placeholder: "Enter your username"
+        - type: div
+          content:
+            - "Current value: "
+            - type: strong
+              content: ~.username
+      data:
+        username: ""
+
+  - type: RjBuildDescriber
+    title: "Different Input Types"
+    description: "TextField with various HTML5 input types"
+    toDescribe:
+      renderView:
+        - type: TextField
+          dataLocation: ~.email
+          label: "Email:"
+          placeholder: "user@example.com"
+          inputType: "email"
+        - type: TextField
+          dataLocation: ~.password
+          label: "Password:"
+          placeholder: "Enter password"
+          inputType: "password"
+        - type: TextField
+          dataLocation: ~.website
+          label: "Website:"
+          placeholder: "https://example.com"
+          inputType: "url"
+        - type: div
+          attributes:
+            style:
+              marginTop: "20px"
+              padding: "10px"
+              backgroundColor: "#f8f9fa"
+              borderRadius: "5px"
+          content:
+            - type: strong
+              content: "Current Values:"
+            - type: div
+              content:
+                - "Email: "
+                - ~.email
+            - type: div
+              content:
+                - "Password: "
+                - ~.password
+            - type: div
+              content:
+                - "Website: "
+                - ~.website
+      data:
+        email: ""
+        password: ""
+        website: ""
+
+  - type: RjBuildDescriber
+    title: "Input Attributes"
+    description: "TextField with custom input attributes and validation styling (pattern: ABC-123 format)"
+    toDescribe:
+      renderView:
+        - type: BsAlert
+          attributes:
+            variant: warning
+          content:
+            - type: strong
+              content: "Note: "
+            - "CSS styles are defined inline in this example for demonstration purposes. In practice, it is recommended to define these styles in an external CSS file for better maintainability."
+        - type: style
+          content: |
+            input[pattern]:valid {
+              border-color: #28a745;
+              box-shadow: 0 0 0 0.2rem rgba(40, 167, 69, 0.25);
+            }
+            input[pattern]:invalid {
+              border-color: #dc3545;
+              box-shadow: 0 0 0 0.2rem rgba(220, 53, 69, 0.25);
+            }
+        - type: TextField
+          dataLocation: ~.productCode
+          label: "Product Code:"
+          placeholder: "ABC-123"
+          inputAttributes:
+            pattern: "[A-Z]{3}-[0-9]{3}"
+            title: "Format: ABC-123 (3 letters, dash, 3 numbers)"
+            maxLength: 7
+            style:
+              textTransform: "uppercase"
+        - type: div
+          content:
+            - "Product Code: "
+            - ~.productCode
+      data:
+        productCode: ""
+
+  - type: Markdown
+    content: |
+      ## Limitations
+
+      - No built-in validation beyond HTML5 input type validation
+      - No support for input masking or formatting
+      - No built-in error message display
+      - Template evaluation for `inputType` should return valid HTML input types
+      - No support for complex input patterns beyond HTML5 pattern attribute
+
+templates: {}
+data: {} 

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

@@ -0,0 +1,106 @@
+# Form Elements Common Utilities
+
+## Introduction
+
+The `formElementsCommon.jsx` file provides shared utilities for all form components in Reactive-JSON. These utilities handle data location resolution, path calculation, and default value management.
+
+## propsDataLocationToPathAndValue Function
+
+This utility function is the core of form data management across all form components. It resolves data location and provides the current value and path for form field synchronization.
+
+### Parameters
+
+- `currentPath` (string): The current path of the component in the template hierarchy
+- `datafield` (string): The field name of the component (used for template-scoped data)
+- `dataLocation` (string|undefined): The custom data location specified in the component
+- `defaultValue` (any): The default value to use when no data is present
+- `globalDataContext` (object): The global data context object
+- `templateContext` (object): The template context object
+
+### Return Value
+
+Returns an object with:
+- `formData`: The current value of the form field
+- `formDataPath`: The path array for updating the data
+
+### Data Location Resolution Logic
+
+The function implements two data binding strategies:
+
+#### 1. Custom Data Location
+When `dataLocation` is provided:
+- Evaluates the template value at the specified location
+- Uses the resolved path for data updates
+- Falls back to `defaultValue` if the location is undefined
+
+#### 2. Template-Scoped Data
+When no `dataLocation` is provided:
+- Uses the component's `datafield` as the key
+- Stores data in the template context under this key
+- Automatically initializes with `defaultValue` if not present
+- Creates the template data object if it doesn't exist
+
+### Usage Example
+
+```javascript
+const {formData, formDataPath} = propsDataLocationToPathAndValue({
+    currentPath: "user.profile",
+    datafield: "username",
+    dataLocation: "~.user.name",
+    defaultValue: "",
+    globalDataContext,
+    templateContext,
+});
+```
+
+## Implementation Details
+
+### Template Data Initialization
+```javascript
+if ((templateContext.templateData[datafield] ?? undefined) === undefined) {
+    templateContext.templateData = (typeof templateContext.templateData === "object") 
+        ? templateContext.templateData 
+        : {};
+    templateContext.templateData[datafield] = defaultValue;
+}
+```
+
+### Path Resolution
+The function uses `dataLocationToPath` to convert template paths to array paths suitable for the `updateData` function in the global data context.
+
+## Benefits
+
+- **Consistent data handling**: All form components use the same data resolution logic
+- **Flexible binding**: Supports both explicit paths and automatic field naming
+- **Safe initialization**: Handles missing data gracefully with default values
+- **Template integration**: Works seamlessly with the template system
+- **Performance**: Minimal overhead with efficient path resolution
+
+## Form Component Integration
+
+All form components follow this pattern:
+
+```javascript
+const {formData, formDataPath} = propsDataLocationToPathAndValue({
+    currentPath: path,
+    datafield: datafield,
+    dataLocation: props.dataLocation,
+    defaultValue: props.defaultFieldValue,
+    globalDataContext,
+    templateContext,
+});
+
+const onChange = (e) => {
+    globalDataContext.updateData(e.currentTarget.value, formDataPath);
+};
+```
+
+This ensures consistent behavior across TextField, NumberField, SelectField, CheckBoxField, TextAreaField, and DateField components.
+
+## Limitations
+
+- Template data modification may not be the ideal approach (noted in code comments)
+- No built-in validation of data location paths
+- No automatic type conversion or validation
+- Limited error handling for invalid paths or contexts
+- Template data is stored in the template context, which may not persist across template changes