@ea-lab/reactive-json-docs 0.6.0 → 0.8.0

package/public/rjbuild/docs/core/element/debug/VariablesDebug.md

@@ -0,0 +1,59 @@
+# VariablesDebug
+
+The `VariablesDebug` component renders a floating debug panel that lets you inspect the current template data at runtime. It is intended for development and debugging purposes to quickly see the values available in the active template context.
+
+## Properties
+None
+
+## Behavior
+- Renders a floating panel that can be expanded/collapsed.
+- Displays the current template path.
+- Switches between two modes: a flattened key/value list or a formatted JSON view.
+- Copies the current view to the clipboard (list or JSON).
+- Uses a portal (`#rj-debug-root`) injected into `document.body`.
+- Returns `null` when `document` is not available (e.g., SSR).
+- Multiple `VariablesDebug` components can be used in the same page.
+
+## Example
+This example shows how to use the `VariablesDebug` component to display the current template data.
+
+Click the button to open the debug panel.
+
+As the `VariablesDebug` declaration is located at the RjBuild root, it will show the global data assigned to the root.
+
+```yaml
+renderView:
+  - type: VariablesDebug
+    actions:
+      - what: hide
+        when: ~.openDebug
+        isEmpty:
+
+  - type: button
+    content: Open/close the debug panel
+    actions:
+      - what: setData
+        on: click
+        path: ~.openDebug
+        value: true
+        when: ~.openDebug
+        isNot: true
+        stopPropagation: true
+      - what: setData
+        on: click
+        path: ~.openDebug
+        value: false
+        when: ~.openDebug
+        isNot: false
+        stopPropagation: true
+
+data:
+  user:
+    name: "Alice"
+    email: "alice@example.com"
+```
+
+## Notes
+- Best used only in development environments. You should not ship it in production UIs.
+- Clipboard access depends on browser permissions/policies.
+- Do not include too many `VariablesDebug` components in the same page; otherwise, the vertical space available will be too small to be useful.

package/public/rjbuild/docs/core/element/debug/VariablesDebug.yaml

@@ -0,0 +1,71 @@
+renderView:
+  - type: Markdown
+    content: |
+      # VariablesDebug
+
+      The `VariablesDebug` component renders a floating debug panel that lets you inspect the
+      current template data at runtime. It is intended for development and debugging purposes
+      to quickly see the values available in the active template context.
+
+      ## Properties
+
+      None.
+
+      ## Behavior
+      - Renders a floating panel that can be expanded/collapsed.
+      - Displays the current template path.
+      - Switches between two modes: a flattened key/value list or a formatted JSON view.
+      - Copies the current view to the clipboard (list or JSON).
+      - Uses a portal (`#rj-debug-root`) injected into `document.body`.
+      - Returns `null` when `document` is not available (e.g., SSR).
+      - Multiple `VariablesDebug` components can be used in the same page.
+
+  - type: RjBuildDescriber
+    title: "Example"
+    description:
+      type: Markdown
+      content: |
+        This example shows how to use the `VariablesDebug` component to display the current template data.
+
+        Click the button to open the debug panel.
+
+        As the `VariablesDebug` declaration is located at the RjBuild root, it will show the global data assigned to the root.
+
+    toDescribe:
+      renderView:
+        - type: VariablesDebug
+          actions:
+            - what: hide
+              when: ~.openDebug
+              isEmpty:
+
+        - type: button
+          content: Open/close the debug panel
+          actions:
+            - what: setData
+              on: click
+              path: ~.openDebug
+              value: true
+              when: ~.openDebug
+              isNot: true
+              stopPropagation: true
+            - what: setData
+              on: click
+              path: ~.openDebug
+              value: false
+              when: ~.openDebug
+              isNot: false
+              stopPropagation: true
+
+      data:
+        user:
+          name: "Alice"
+          email: "alice@example.com"
+
+  - type: Markdown
+    content: |
+      ## Notes
+      - Best used only in development environments. You should not ship it in production UIs.
+      - Clipboard access depends on browser permissions/policies.
+      - Do not include too many `VariablesDebug` components in the same page; otherwise,
+        the vertical space available will be too small to be useful.

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

@@ -4,14 +4,14 @@ The `CheckBoxField` component renders checkbox or radio button groups using Reac
 
 ## 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
+- `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
 

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

@@ -7,15 +7,47 @@ renderView:
 
       ## 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
+  - 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: 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."
+      - term:
+          code: controlType
+          after: "(string, optional)"
+        details: "Type of control - `checkbox` (default) or `radio`."
+      - term:
+          code: multiple
+          after: "(boolean, optional)"
+        details: "Force array storage for checkboxes (default: auto-detected)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the Form.Group container."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on field state."
 
+  - type: Markdown
+    content: |
       ## Option Format
 
       Each option object must have:

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

@@ -7,11 +7,11 @@ The `DateField` component renders a date and time input field using React Bootst
 
 ## 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
+- `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
 

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

@@ -10,12 +10,34 @@ renderView:
 
       ## 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
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: Path to bind the field value in the data context.
+      - term:
+          code: defaultFieldValue
+          after: "(string, optional)"
+        details: Default value when no data is present.
+      - term:
+          code: label
+          after: "(string, optional)"
+        details: Field label text.
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: Attributes applied to the Form.Group container.
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details:
+          type: Markdown
+          content: |
+            Actions to execute based on field state. Supports both actions (hide, tooltip, etc.) and conditional reactions (setData, fetchData, etc.) with full conditional logic support.
 
+  - type: Markdown
+    content: |
       ## 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`.

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

@@ -4,13 +4,13 @@ The `NumberField` component renders a numeric input field using React Bootstrap.
 
 ## Properties
 
-- `dataLocation` (string, optional): Path to bind the field value in the data context
-- `defaultFieldValue` (number, 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)
-- `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
+- `dataLocation` (string, optional): Path to bind the field value in the data context.
+- `defaultFieldValue` (number, 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).
+- `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
 

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

@@ -7,14 +7,39 @@ renderView:
 
       ## Properties
 
-      - `dataLocation` (string, optional): Path to bind the field value in the data context
-      - `defaultFieldValue` (number, 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)
-      - `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
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "Path to bind the field value in the data context."
+      - term:
+          code: defaultFieldValue
+          after: "(number, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string, optional)"
+        details: "Field label text (supports template evaluation)."
+      - term:
+          code: placeholder
+          after: "(string, optional)"
+        details: "Placeholder text (supports template evaluation)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the Form.Group container."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the input element."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on field state."
 
+  - type: Markdown
+    content: |
       ## Data Management
 
       The component stores the input value as a string in the data context. The browser's number input provides built-in validation, but the value should be converted to a number when needed for calculations.

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

@@ -4,15 +4,15 @@ The `SelectField` component renders a dropdown selection field using React Boots
 
 ## 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, optional): Field label text (supports template evaluation)
-- `options` (array, optional): Static array of option objects with `label` and `value` properties
-- `dynamicOptions` (string, optional): Template path to dynamic options array
-- `allowEmptyStringAsValue` (boolean, optional): Preserve empty strings as `""` instead of converting to `undefined` (default: false)
-- `attributes` (object, optional): Attributes applied to the Form.Group container
-- `inputAttributes` (object, optional): Attributes applied directly to the select element
-- `actions` (array, optional): Actions to execute based on field state
+- `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, optional): Field label text (supports template evaluation).
+- `options` (array, optional): Static array of option objects with `label` and `value` properties.
+- `dynamicOptions` (string, optional): Template path to dynamic options array.
+- `allowEmptyStringAsValue` (boolean, optional): Preserve empty strings as `""` instead of converting to `undefined` (default: false).
+- `attributes` (object, optional): Attributes applied to the Form.Group container.
+- `inputAttributes` (object, optional): Attributes applied directly to the select element.
+- `actions` (array, optional): Actions to execute based on field state.
 
 ## Option Format
 

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

@@ -7,16 +7,53 @@ renderView:
 
       ## 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, optional): Field label text (supports template evaluation)
-      - `options` (array, optional): Static array of option objects with `label` and `value` properties
-      - `dynamicOptions` (string, optional): Template path to dynamic options array
-      - `allowEmptyStringAsValue` (boolean, optional): Preserve empty strings as `""` instead of converting to `undefined` (default: false)
-      - `attributes` (object, optional): Attributes applied to the Form.Group container
-      - `inputAttributes` (object, optional): Attributes applied directly to the select element
-      - `actions` (array, optional): Actions to execute based on field state
+  - 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, optional)"
+        details: "Field label text (supports template evaluation)."
+      - 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."
+      - term:
+          code: allowEmptyStringAsValue
+          after: "(boolean, optional)"
+        details:
+          type: Markdown
+          content: "Preserve empty strings as `\"\"` instead of converting to `undefined` (default: false)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the Form.Group container."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the select element."
+      - term:
+          code: actions
+          after: "(array, optional)"
+        details: "Actions to execute based on field state."
 
+  - type: Markdown
+    content: |
       ## Option Format
 
       Each option object must have:

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

@@ -4,14 +4,14 @@ The `TextAreaField` component renders a multi-line text input field using React
 
 ## 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
+- `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
 

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

@@ -7,15 +7,43 @@ renderView:
 
       ## 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
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "Path to bind the field value in the data context."
+      - term:
+          code: defaultFieldValue
+          after: "(string, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string, optional)"
+        details: "Field label text (supports template evaluation)."
+      - term:
+          code: placeholder
+          after: "(string, optional)"
+        details: "Placeholder text (supports template evaluation)."
+      - term:
+          code: rows
+          after: "(number, optional)"
+        details: "Number of visible text lines (default: 3)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the Form.Group container."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the textarea element."
+      - 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. 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`.

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

@@ -4,14 +4,14 @@ The `TextField` component renders a single-line text input field using React Boo
 
 ## 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
+- `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
 

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

@@ -7,15 +7,45 @@ renderView:
 
       ## 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
+  - type: DefinitionList
+    content:
+      - term:
+          code: dataLocation
+          after: "(string, optional)"
+        details: "Path to bind the field value in the data context."
+      - term:
+          code: defaultFieldValue
+          after: "(string, optional)"
+        details: "Default value when no data is present."
+      - term:
+          code: label
+          after: "(string, optional)"
+        details: "Field label text (supports template evaluation)."
+      - term:
+          code: placeholder
+          after: "(string, optional)"
+        details: "Placeholder text (supports template evaluation)."
+      - term:
+          code: inputType
+          after: "(string, optional)"
+        details:
+          type: Markdown
+          content: "HTML input type (default: \"text\", supports template evaluation)."
+      - term:
+          code: attributes
+          after: "(object, optional)"
+        details: "Attributes applied to the Form.Group container."
+      - term:
+          code: inputAttributes
+          after: "(object, optional)"
+        details: "Attributes applied directly to the input element."
+      - 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. 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`.

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

@@ -1,7 +1,5 @@
 # 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
@@ -27,13 +25,13 @@ Returns an object with:
 
 The function implements two data binding strategies:
 
-#### 1. Custom Data Location
+#### 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
+#### 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

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

@@ -1,7 +1,5 @@
 # Form Elements
 
-## Introduction
-
 Form elements in Reactive-JSON provide interactive input components based on React Bootstrap. These components automatically manage state through the global data context and support template evaluation for dynamic content.
 
 All form elements support: