@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,50 @@
+# 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:
+- Dynamic data binding via `dataLocation` or automatic field naming
+- Template evaluation for labels, placeholders, and options
+- Action system integration for conditional logic
+- React Bootstrap styling and attributes
+- Automatic state synchronization with the global data context
+
+## Available Components
+
+- **TextField**: Single-line text input with customizable input types
+- **NumberField**: Numeric input field with number-specific validation
+- **TextAreaField**: Multi-line text input with configurable rows
+- **SelectField**: Dropdown selection with static or dynamic options
+- **CheckBoxField**: Checkbox/radio button groups with multiple selection modes
+- **DateField**: Date and datetime input field (limited support)
+
+## Common Properties
+
+All form components share these common 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)
+- `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
+
+Form elements use two approaches for data management:
+
+1. **Explicit data location**: Use `dataLocation` to specify exact path in global data
+2. **Automatic field naming**: Use the component's `datafield` parameter for template-scoped data
+
+The data is automatically synchronized with the global data context on user input changes.
+
+## Limitations
+
+- No built-in form validation beyond basic HTML5 validation
+- No support for file upload inputs
+- Limited date field support (only datetime-local type)
+- No built-in error handling or validation messages
+- No support for complex nested form structures
+- No automatic form submission handling 

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

@@ -0,0 +1,96 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Form Elements
+
+      Interactive demonstration of Reactive-JSON form components with real-time data binding.
+
+  - type: RjBuildDescriber
+    title: "Complete Form Example"
+    description: "All form components working together with data binding"
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            style:
+              display: grid
+              gridTemplateColumns: "1fr 1fr"
+              gap: "20px"
+          content:
+            - type: div
+              content:
+                - type: TextField
+                  dataLocation: ~.name
+                  label: "Full Name:"
+                  placeholder: "Enter your full name"
+                - type: NumberField
+                  dataLocation: ~.age
+                  label: "Age:"
+                  placeholder: "Enter your age"
+                - type: SelectField
+                  dataLocation: ~.country
+                  label: "Country:"
+                  options:
+                    - label: "Select a country"
+                      value: ""
+                    - label: "France"
+                      value: "fr"
+                    - label: "United States"
+                      value: "us"
+                    - label: "Canada"
+                      value: "ca"
+                - type: CheckBoxField
+                  dataLocation: ~.interests
+                  label: "Interests:"
+                  options:
+                    - label: "Technology"
+                      value: "tech"
+                    - label: "Sports"
+                      value: "sports"
+                    - label: "Music"
+                      value: "music"
+                - type: TextAreaField
+                  dataLocation: ~.comments
+                  label: "Comments:"
+                  placeholder: "Additional comments..."
+                  rows: 4
+            - type: div
+              content:
+                - type: strong
+                  content: "Live Data Preview:"
+                - type: PreformattedMarkup
+                  content: ["<pre>", ~.formData, "</pre>"]
+                  actions:
+                    - what: setData
+                      when: ~.formData
+                      is: undefined
+                      key: formData
+                      value: "{}"
+                - type: div
+                  content:
+                    - "Name: "
+                    - ~.name
+                - type: div
+                  content:
+                    - "Age: "
+                    - ~.age
+                - type: div
+                  content:
+                    - "Country: "
+                    - ~.country
+                - type: div
+                  content: "Interests selected in checkbox above"
+                - type: div
+                  content:
+                    - "Comments: "
+                    - ~.comments
+      data:
+        name: ""
+        age: ""
+        country: ""
+        interests: []
+        comments: ""
+        formData: ""
+
+templates: {}
+data: {} 

package/public/rjbuild/component-doc/core/element/html/AccordionItem.yaml

@@ -0,0 +1,47 @@
+renderView:
+  - type: Markdown
+    content: |
+      # AccordionItem
+
+      The `AccordionItem` component is used inside a parent `BsAccordion` component. This parent is a React-Bootstrap Accordion adapted for Reactive-JSON, supporting templates and actions via the `BootstrapElement` system.
+
+      **Important:** `AccordionItem` must be a direct child of `BsAccordion`.
+
+      ## Properties
+      - `header` (object, optional): Content for the accordion header
+      - `body` (object, optional): Content for the accordion body
+      - `attributes` (object, optional): Additional attributes for the Accordion.Item
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Accordion with multiple sections"
+    description:
+      - type: Markdown
+        content: |
+          Click the headers to expand/collapse each section. Each section is an AccordionItem with its own header and body. The parent BsAccordion supports templates and actions.
+    toDescribe:
+      renderView:
+        - type: BsAccordion
+          content:
+            - type: AccordionItem
+              header: General Info
+              body:
+                type: Markdown
+                content: "This section contains general information."
+            - type: AccordionItem
+              header:
+                type: div
+                content:
+                  - type: strong
+                    content: Important!
+                  - " Details"
+              body:
+                type: Markdown
+                content: "This section contains more details."
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only works inside a parent BsAccordion component
+      - No built-in support for nested accordions
+      - The eventKey is set automatically; custom keys are not supported directly
+      - No animation customization beyond what react-bootstrap provides

package/public/rjbuild/component-doc/core/element/html/FolderSortableTree.yaml

@@ -0,0 +1,81 @@
+renderView:
+  - type: Markdown
+    content: |
+      # FolderSortableTree
+
+      The `FolderSortableTree` component displays a drag-and-drop tree for hierarchical data. Each node is rendered using a template, and the structure is fully editable by the user.
+
+      This component is based on the [dnd-kit-sortable-tree](https://github.com/shaddix/dnd-kit-sortable-tree) library. For advanced configuration and available options, see the library documentation.
+
+      **Note:** For each node, all properties to display in the template (like `name`, `age`, etc.) must be placed inside a `value` object. The itemTemplate only has access to the fields inside `value` for each node. Children are listed in the `children` array.
+
+      ## Properties
+      - `dataLocation` (string, required): Path to the tree data
+      - `itemTemplate` (object, required): Template for each tree item
+      - `maxDepth` (number, optional): Maximum allowed depth
+      - `maxDepthIsAbsolute` (boolean, optional): If true, maxDepth is absolute from the root (default: true)
+      - `treeRootPath` (string, optional): Path to a subtree to display as the root
+      - `keepBaseItem` (boolean, optional): If true, keeps the base item when using treeRootPath
+      - `sortableTreeOptions` (object, optional): Additional options for SortableTree
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Editable family tree"
+    description:
+      - type: Markdown
+        content: |
+          Drag and drop nodes to reorder or nest them. Each node is rendered using the template below, showing both name and age.
+    toDescribe:
+      renderView:
+        - type: FolderSortableTree
+          dataLocation: ~.tree
+          itemTemplate:
+            - type: div
+              content:
+                - type: strong
+                  content: "Name: "
+                - ~.name
+                - ", "
+                - type: strong
+                  content: "Age: "
+                - ~.age
+      data:
+        tree:
+          - id: 1
+            value:
+              name: "Alice (grandmother)"
+              age: 78
+            children:
+              - id: 2
+                value:
+                  name: "Bob (son)"
+                  age: 50
+                children:
+                  - id: 4
+                    value:
+                      name: "Diana (granddaughter)"
+                      age: 20
+                    children: []
+                  - id: 5
+                    value:
+                      name: "Eve (grandson)"
+                      age: 18
+                    children: []
+              - id: 3
+                value:
+                  name: "Carol (daughter)"
+                  age: 48
+                children:
+                  - id: 6
+                    value:
+                      name: "Frank (grandson)"
+                      age: 22
+                    children: []
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Tree data must be an array of objects with `id`, `children`, and `value` keys
+      - No built-in async loading of children
+      - No built-in search/filter UI
+      - Only one tree can be edited at a time per component instance
+      - No animation customization beyond what dnd-kit-sortable-tree provides

package/public/rjbuild/component-doc/core/element/html/FormatNumeral.yaml

@@ -0,0 +1,58 @@
+renderView:
+  - type: Markdown
+    content: |
+      # FormatNumeral
+
+      The `FormatNumeral` component displays a number as a Roman numeral or Latin letter. Useful for sections, lists, or any context where a non-Arabic numeral is needed.
+
+      ## Properties
+      - `content` (number, required): The number to format
+      - `format` (string, required): One of `roman-upper`, `roman-lower`, `latin-upper`, `latin-lower`
+      - `attributes` (object, optional): Additional attributes for the root element
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Format a number"
+    description:
+      - type: Markdown
+        content: |
+          Change the number and format to see the result. Only positive integers are supported.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: NumberField
+              label: "Number:"
+              dataLocation: ~.num
+              inputAttributes:
+                min: 1
+                max: 3999
+            - type: SelectField
+              label: "Format:"
+              dataLocation: ~.fmt
+              options:
+                - label: "Roman Upper (I, II, III)"
+                  value: roman-upper
+                - label: "Roman Lower (i, ii, iii)"
+                  value: roman-lower
+                - label: "Latin Upper (A, B, C)"
+                  value: latin-upper
+                - label: "Latin Lower (a, b, c)"
+                  value: latin-lower
+        - type: div
+          content:
+            - type: strong
+              content: "Result: "
+            - type: FormatNumeral
+              content: ~.num
+              format: ~.fmt
+      data:
+        num: 3
+        fmt: roman-upper
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only positive integers are supported (no zero, negative, or fractional numbers)
+      - No support for custom numeral systems
+      - No localization or language-specific formatting
+      - No error message for invalid input; nothing is rendered if the input is invalid

package/public/rjbuild/component-doc/core/element/html/Html.yaml

@@ -0,0 +1,67 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Html
+
+      The `Html` component renders any HTML tag with static attributes and content. Use it to create custom wrappers, sections, or inject arbitrary tags with full template support.
+
+      **Note:** The `tag` property must be a static string. It cannot be set dynamically via template or data.
+
+      ## Properties
+      - `tag` (string, required): The HTML tag to render (e.g., div, span, section)
+      - `attributes` (object, optional): Attributes for the tag (class, id, etc.)
+      - `content` (object/array, optional): Content to render inside the tag (any Reactive-JSON view or array)
+      - `extra` (object, optional): Additional content rendered after the main tag
+
+  - type: BsAlert
+    attributes:
+      variant: info
+    content:
+      - "In most cases, you do not need to use the Html component directly. It is more convenient to use 'type: tagName' (e.g., 'type: div', 'type: span') instead of 'type: Html, tag: tagName'. The Html component is used internally by the engine as a fallback when no specific component is found for a given type."
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Custom HTML tag (static tag only)"
+    description:
+      - type: Markdown
+        content: |
+          Change the priority and content to see how the Html component renders dynamic HTML.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: SelectField
+              dataLocation: ~.class
+              label: "Priority:"
+              options:
+                - label: "Normal"
+                  value: ""
+                - label: "Important (blue)"
+                  value: "text-primary"
+                - label: "Warning (orange)"
+                  value: "text-warning"
+                - label: "Critical (red)"
+                  value: "text-danger"
+            - type: TextField
+              dataLocation: ~.txt
+              label: "Content"
+        - type: div
+          content:
+            type: strong
+            content: "Rendered:"
+        - type: Html
+          tag: div
+          attributes:
+            class: ~.class
+          content: ~.txt
+      data:
+        class: ""
+        txt: Hello world!
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - The `tag` property does not support template evaluation and must be a static string
+      - No validation of tag names; invalid tags may cause rendering errors
+      - No support for dangerouslySetInnerHTML (use PreformattedMarkup for raw HTML)
+      - No built-in support for event handlers (use actions system for interactivity)
+      - No automatic support for custom attributes beyond React's attribute normalization

package/public/rjbuild/component-doc/core/element/html/LabelFromValue.yaml

@@ -0,0 +1,54 @@
+renderView:
+  - type: Markdown
+    content: |
+      # LabelFromValue
+
+      The `LabelFromValue` component displays the label associated with a value, using an option-like structure. It is useful for showing the display label of a value selected in a SelectField or any value/label mapping.
+
+      ## Properties
+      - `dataLocation` (string, required): Path to the value
+      - `options` (array, optional): Array of `{label, value}` objects
+      - `dynamicOptions` (any, optional): Template value for dynamic options
+      - `defaultFieldValue` (any, optional): Default value if none is set
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Display label from value"
+    description:
+      - type: Markdown
+        content: |
+          Select a status to see the corresponding label displayed below.
+    toDescribe:
+      renderView:
+        - type: SelectField
+          dataLocation: ~.status
+          label: "Status"
+          options:
+            - label: "Active"
+              value: 1
+            - label: "Inactive"
+              value: 2
+            - label: "Pending"
+              value: 3
+        - type: div
+          content:
+            - type: strong
+              content: "Label: "
+            - type: LabelFromValue
+              dataLocation: ~.status
+              options:
+                - label: "Active"
+                  value: 1
+                - label: "Inactive"
+                  value: 2
+                - label: "Pending"
+                  value: 3
+      data:
+        status: 3
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only the first matching label is displayed; duplicate values in options are not supported
+      - No support for grouped options or nested structures
+      - No built-in formatting for the label (use a wrapper if needed)
+      - If no options are provided, the raw value is shown

package/public/rjbuild/component-doc/core/element/html/Modal.yaml

@@ -0,0 +1,93 @@
+# Example usage of Modal component in Reactive-JSON
+renderView:
+  - type: Markdown
+    content: |
+      # Modal
+
+      The `Modal` component displays a dialog that can be controlled by local state or by a boolean in the global data context. It is useful for confirmations, information, or any overlay content.
+
+      ## Properties
+      - `headerTitle` (object, optional): Content for the modal header (any Reactive-JSON view)
+      - `body` (object, optional): Content for the modal body (any Reactive-JSON view)
+      - `closeButton` (boolean, optional): Show a close button in the header (default: false)
+      - `showBoolPath` (string or boolean, optional): If a string, path to a boolean in data controlling visibility; otherwise, local state is used
+      - `attributes` (object, optional): Additional attributes for the modal (size, centered, etc.)
+      - `className` (string, optional): Additional CSS classes (always includes `reactive-json`)
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Modal controlled by data path"
+    description:
+      - type: Markdown
+        content: |
+          Click the button to open the modal. The modal's visibility is controlled by the `show_modal` value in the data context. Closing the modal sets `show_modal` to false.
+    toDescribe:
+      renderView:
+        - type: button
+          content: "Open Modal"
+          actions:
+            - what: setData
+              on: click
+              path: ~.show_modal
+              value: true
+        - type: Modal
+          showBoolPath: ~.show_modal
+          headerTitle:
+            type: Markdown
+            content: "Modal Title"
+          body:
+            type: Markdown
+            content: "This modal is controlled by global data."
+          closeButton: true
+      data:
+        show_modal: false
+
+  - type: RjBuildDescriber
+    title: "Multiple Modals Example"
+    description: This example demonstrates how to have multiple modals open simultaneously. Each modal is controlled by a different data path, allowing independent visibility control.
+    toDescribe:
+      renderView:
+        - type: div
+          content:
+            - type: button
+              content: "Open First Modal"
+              actions:
+                - what: setData
+                  on: click
+                  path: ~.modal_one
+                  value: true
+        - type: Modal
+          showBoolPath: ~.modal_one
+          headerTitle: "First Modal"
+          body:
+            - type: Markdown
+              content: "This is the first modal. You can open another one!"
+            - type: button
+              content: "Open Second Modal"
+              actions:
+                - what: setData
+                  on: click
+                  path: ~.modal_two
+                  value: true
+          closeButton: true
+        - type: Modal
+          showBoolPath: ~.modal_two
+          headerTitle: "Second Modal"
+          body:
+            type: Markdown
+            content: "This is the second modal. Both can be open at the same time!"
+          closeButton: true
+      data:
+        modal_one: false
+        modal_two: false
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - No built-in async or loading state
+      - No advanced accessibility beyond react-bootstrap
+      - If `showBoolPath` is a data path, it must resolve to a boolean
+      - No animation customization beyond react-bootstrap
+
+      ## Notes
+      - Multiple modals can be displayed simultaneously by using different `showBoolPath` values or state-controlled modals
+      - Each modal is independently controlled and managed

package/public/rjbuild/component-doc/core/element/html/PreformattedMarkup.yaml

@@ -0,0 +1,37 @@
+renderView:
+  - type: Markdown
+    content: |
+      # PreformattedMarkup
+
+      The `PreformattedMarkup` component renders HTML content with a strict allowlist of tags for safety. Use it to display rich text or HTML snippets, with filtering to prevent unwanted markup.
+
+      ## Properties
+      - `content` (string, required): The HTML string to render (can use template values)
+      - `htmlTagAllowList` (array, optional): List of allowed tags (overrides default)
+      - `additionalAllowedTags` (array, optional): Tags to add to the allowlist
+
+      **Default allowed tags:** abbr, acronym, b, blockquote, br, caption, code, div, em, h1-h6, i, li, ol, p, span, sup, strong, table, tbody, td, tfoot, th, thead, tr, ul
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Filtered HTML rendering"
+    description:
+      - type: Markdown
+        content: |
+          Only allowed tags are rendered. Try editing the content to add disallowed tags (like `<script>`, `<u>`, or `<img>`): they will be stripped.
+    toDescribe:
+      renderView:
+        - type: TextField
+          label: "HTML Content"
+          dataLocation: ~.html_content
+        - type: PreformattedMarkup
+          content: ~.html_content
+      data:
+        html_content: "<h2>Welcome</h2><p>This <b>component</b> only allows certain tags.<br><u>Underline</u> <img src='x' /></p>"
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only allowed tags are rendered; all others are stripped
+      - No support for custom attributes or inline styles
+      - No script, style, or event attributes are executed
+      - Not suitable for rendering untrusted HTML with complex requirements

package/public/rjbuild/component-doc/core/element/html/SortableTreeItemCollapseButton.yaml

@@ -0,0 +1,92 @@
+renderView:
+  - type: Markdown
+    content: |
+      # SortableTreeItemCollapseButton
+
+      The `SortableTreeItemCollapseButton` component provides a collapse/expand button for tree items in a `FolderSortableTree`.
+
+      Use this component when you want to customize the location of this button in the tree item.
+
+      It's especially useful when the `manualDrag` option of the parent SortableTree is `true`, which causes the
+      disappearance of the default collapse button.
+
+      ## Properties
+      No properties.
+
+      ## Technical Details
+      - Renders a button with CSS classes for styling
+      - Only appears when the tree item has children and supports collapsing
+
+  - type: RjBuildDescriber
+    title: "Interactive Example: Tree with a right aligned collapse button"
+    description:
+      - type: Markdown
+        content: |
+          This example shows a `FolderSortableTree` with `SortableTreeItemCollapseButton` components in each item
+          template. Click the collapse buttons to expand/collapse tree nodes.
+    toDescribe:
+      renderView:
+        - # Inline style, because we want to style an element that is internally handled by the SortableTree lib.
+          # It's better to put this in a CSS file or in the <head> though.
+          # This code simply makes the item grow, and is needed only for a nicer presentation of the collapse button.
+          type: style
+          content: ".dnd-sortable-tree_folder_tree-item { flex-grow: 1; }"
+        - type: FolderSortableTree
+          sortableTreeOptions:
+            disableCollapseOnItemClick: true
+            manualDrag: true
+            showDragHandle: true
+          dataLocation: ~.tree
+          itemTemplate:
+            type: div
+            attributes:
+              class: align-items-center d-flex flex-grow-1 gap-2
+            content:
+              - type: div
+                content:
+                  - type: span
+                    content: ~.name
+              - type: div
+                attributes:
+                  class: d-grid flex-grow-1 justify-content-end
+                  style:
+                    gridTemplateColumns: 1fr 8em 2em
+                content:
+                  - # Takes the remaining space (1fr).
+                    type: div
+                  - type: div
+                    attributes:
+                      class: text-end
+                    content: [" (", ~.count, " items)"]
+                  - type: SortableTreeItemCollapseButton
+      data:
+        tree:
+          - id: 1
+            value:
+              name: "Root Folder"
+              count: 3
+            children:
+              - id: 2
+                value:
+                  name: "Subfolder 1"
+                  count: 1
+                children:
+                  - id: 3
+                    value:
+                      name: "File 1"
+                      count: 0
+                    children: []
+              - id: 4
+                value:
+                  name: "Subfolder 2"
+                  count: 0
+                children: []
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only works within the template context of a `FolderSortableTree` item
+      - The button only appears when the tree item has children (`childCount > 0`)
+      - No customization of the collapse/expand behavior beyond what the underlying SortableTree provides
+      - The styling is controlled by the dnd-kit-sortable-tree CSS classes. You will need to provide CSS to override
+        the default styling.