@ea-lab/reactive-json-docs 0.1.2

package/public/rjbuild/component-doc/core/element/special/Phantom.md

@@ -0,0 +1,31 @@
+# Phantom
+
+## Introduction
+
+The `Phantom` component allows you to define actions or logic in your rjbuild without rendering any DOM element. It is useful for triggering actions, conditions, or data manipulations invisibly, without affecting the visual structure of your application.
+
+## Properties
+- `content` (object/array/string, optional): Content to evaluate or trigger (actions, conditions, etc.)
+- `actions` (array, optional): Actions to attach to the phantom logic (e.g., Tooltip)
+
+## Behavior
+- Does not render any visible DOM element
+- Can be used to attach actions, conditions, or data manipulations without UI
+- The `content` property can include any valid Reactive-JSON view, action, or string
+- The `actions` property allows you to attach logic such as tooltips or data updates
+
+## Example
+```yaml
+renderView:
+  - type: Phantom
+    content: "Hover me"
+    actions:
+      - what: tooltip
+        content: "This tooltip is attached via an action, not a visible wrapper."
+        placement: right
+```
+
+## Limitations
+- Does not produce any visible output in the DOM
+- Only useful for logic, actions, or invisible data manipulations
+- Not intended for displaying content to the user 

package/public/rjbuild/component-doc/core/element/special/Phantom.yaml

@@ -0,0 +1,34 @@
+renderView:
+  - type: Markdown
+    content: |
+      # Phantom
+
+      The `Phantom` component allows you to define actions or logic in your rjbuild without rendering any DOM element. It is useful for triggering actions, conditions, or data manipulations invisibly, without affecting the visual structure of your application.
+
+      ## Properties
+      - `content` (object/array/string, optional): Content to evaluate or trigger (actions, conditions, etc.)
+      - `actions` (array, optional): Actions to attach to the phantom logic (e.g., Tooltip)
+
+      ## Behavior
+      - Does not render any visible DOM element
+      - Can be used to attach actions, conditions, or data manipulations without UI
+      - The `content` property can include any valid Reactive-JSON view, action, or string
+      - The `actions` property allows you to attach logic such as tooltips or data updates
+
+  - type: RjBuildDescriber
+    title: Example
+    toDescribe:
+      renderView:
+        - type: Phantom
+          content: "Hover me"
+          actions:
+            - what: tooltip
+              content: "This tooltip is attached via an action, not a visible wrapper."
+              placement: right
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Does not produce any visible output in the DOM
+      - Only useful for logic, actions, or invisible data manipulations
+      - Not intended for displaying content to the user

package/public/rjbuild/component-doc/core/element/special/ReactiveJsonSubroot.md

@@ -0,0 +1,27 @@
+# ReactiveJsonSubroot
+
+## Introduction
+
+The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
+
+## Properties
+- `rjOptions` (object, required): Options to pass to the subroot (such as `dataUrl`, `data`, `renderView`, etc.)
+- Other properties are passed to the underlying `ReactiveJsonRoot`
+
+## Behavior
+- Renders a new `ReactiveJsonRoot` with the provided options
+- The subroot is isolated from the parent for data, templates, and rendering
+- Plugins from the parent are reused in the subroot
+- If `rjOptions` is not a valid object, nothing is rendered
+
+## Example
+```yaml
+renderView:
+  - type: ReactiveJsonSubroot
+    rjOptions:
+      dataUrl: "/rjs-build/home.yaml"
+```
+
+## Limitations
+- The subroot is isolated from the parent; data and state are not shared
+- No built-in communication between parent and subroot (except via plugins or explicit data passing) 

package/public/rjbuild/component-doc/core/element/special/ReactiveJsonSubroot.yaml

@@ -0,0 +1,51 @@
+renderView:
+  - type: Markdown
+    content: |
+      # ReactiveJsonSubroot
+
+      The `ReactiveJsonSubroot` component allows you to render a new Reactive-JSON root inside an existing application. It is useful for embedding a sub-application, isolating a part of the data tree, or rendering a separate rjbuild with its own options.
+
+      ## Properties
+      - `rjOptions` (object, required): Options to pass to the subroot (such as `dataUrl`, `data`, `renderView`, etc.)
+      - Other properties are passed to the underlying `ReactiveJsonRoot`
+
+      ## Behavior
+      - Renders a new `ReactiveJsonRoot` with the provided options
+      - The subroot is isolated from the parent for data, templates, and rendering
+      - Plugins from the parent are reused in the subroot
+      - If `rjOptions` is not a valid object, nothing is rendered
+
+  - type: RjBuildDescriber
+    title: Example
+    description: This example demonstrates how to embed a separate Reactive-JSON application using ReactiveJsonSubroot. The component loads and renders an independent rjbuild file, creating an isolated sub-application within the current view.
+    toDescribe:
+      renderView:
+        - type: ReactiveJsonSubroot
+          rjOptions:
+            dataUrl: "/rjbuild/component/message.yaml"
+
+  - type: RjBuildDescriber
+    title: Example with inline JSON data
+    description: This example demonstrates two approaches for using ReactiveJsonSubroot with inline data. The first shows passing JSON data directly as a string via maybeRawAppData. The second shows loading subroot options dynamically from the main RjBuild's data using template interpolation. Both approaches are useful for embedding sub-applications without external files.
+    toDescribe:
+      renderView:
+        - type: ReactiveJsonSubroot
+          rjOptions:
+            maybeRawAppData: '{"data":{"userName":"Alice","messageCount":3},"renderView":[{"type":"div","attributes":{"style":{"padding":"1rem","border":"1px solid #ddd","borderRadius":"8px","backgroundColor":"#f9f9f9"}},"content":[{"type":"h3","content":"~~.userName"},{"type":"p","content":["You have ","~~.messageCount"," new messages."]},{"type":"button","content":"Mark as read","attributes":{"style":{"backgroundColor":"#007bff","color":"white","border":"none","padding":"0.5rem 1rem","borderRadius":"4px"}}}]}]}'
+
+        - type: hr
+
+        - type: ReactiveJsonSubroot
+          rjOptions: ~~.subrootToLoad
+      data:
+        subrootToLoad:
+          maybeRawAppData:
+            renderView:
+              - type: div
+                content: This second subroot is loaded from the "data" key of the main root.
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - The subroot is isolated from the parent; data and state are not shared
+      - No built-in communication between parent and subroot (except via plugins or explicit data passing) 

package/public/rjbuild/component-doc/core/element/special/Switch.md

@@ -0,0 +1,262 @@
+# Switch
+
+## Introduction
+
+The `Switch` component allows you to render a list or collection of items using a template, with support for dynamic data, options, and pagination. It is useful for displaying arrays, lists, or collections where each item can be rendered with a specific template or configuration.
+
+## Properties
+- `content` (array/object, required): The data or path to the data to iterate over
+- `options` (object, optional): Mapping of keys to templates for rendering each item (referenced by `load`)
+- `singleOption` (object, optional): Template to use for each item when all items share the same structure (referenced by `load`)
+- `cardinality` (number, optional): Maximum number of items to render (default: unlimited)
+- `paginated` (boolean, optional): Whether to enable pagination (default: false)
+- `paginationProps` (object, optional): Pagination configuration (page size, etc.)
+- `before` (object, optional): Content to render before the list
+- `after` (object, optional): Content to render after the list
+- `contentWrapper` (object, optional): HTML element configuration to wrap the main content (items only, not before/after)
+  - `tag` (string, optional): HTML tag name (default: "div")
+  - `attributes` (object, optional): HTML attributes to apply to the wrapper element (supports template evaluation)
+- `templates` (object, optional): Named templates referenced by `load` in `singleOption` or `options`
+
+## Behavior
+- Iterates over the provided data and renders each item using the specified template(s)
+- If `options` is provided, uses the corresponding template for each key (with `load`)
+- If `singleOption` is provided, uses the template referenced by `load` for all items
+- Supports limiting the number of items with `cardinality`
+- Supports pagination if `paginated` is true
+- Renders optional `before` and `after` content
+- Can wrap the main content (items) with a custom HTML element using `contentWrapper`
+- Templates are defined in the `templates` object and referenced by name
+
+## Content Wrapper Feature
+
+The `contentWrapper` property allows you to wrap the rendered items in a custom HTML element without affecting the `before` and `after` content. This is particularly useful for applying CSS layouts like Grid or Flexbox to the items.
+
+**Note**: The `attributes` property of `contentWrapper` supports template evaluation, allowing you to create dynamic wrapper configurations based on your data.
+
+### Structure
+```
+before (optional)
+└── contentWrapper (optional)
+    └── rendered items
+after (optional)
+```
+
+The wrapper only affects the main content items and does not interfere with pagination or other Switch features.
+
+## Examples
+
+### 1. Simple usage with `singleOption` (no pagination)
+```yaml
+renderView:
+  - type: Switch
+    content: ~.users
+    singleOption:
+      load: opt
+    templates:
+      opt:
+        type: div
+        content: ~.name
+
+data:
+  users:
+    - name: "Alice"
+    - name: "Bob"
+    - name: "Charlie"
+```
+
+### 2. Usage with `options` (different templates per key)
+```yaml
+renderView:
+  - type: Switch
+    content: ~.items
+    options:
+      name:
+        load: name
+      age:
+        load: age
+    templates:
+      name:
+        type: div
+        content: ["Name: ", ~.value]
+      age:
+        type: div
+        content: ["Age: ", ~.value]
+data:
+  items:
+    - name:
+        value: "Alice"
+    - age:
+        value: 30
+    - name:
+        value: "Bob"
+    - age:
+        value: 25
+```
+
+### 3. Usage with `singleOption`, pagination, before/after, and PageControls
+```yaml
+renderView:
+  - type: Switch
+    content: ~.numbers
+    singleOption:
+      load: opt
+    paginated: true
+    paginationProps:
+      pageMaxItemCount: 4
+    before:
+      type: div
+      content: "User list:"
+    after:
+      type: PageControls
+    templates:
+      opt:
+        type: div
+        content: ["Number: ", ~.value]
+data:
+  numbers:
+    - value: 1
+    - value: 2
+    - value: 3
+    - value: 4
+    - value: 5
+    - value: 6
+    - value: 7
+    - value: 8
+    - value: 9
+    - value: 10
+```
+
+### 4. Usage with `contentWrapper` for CSS Grid Layout
+```yaml
+renderView:
+  - type: Switch
+    content: ~.products
+    singleOption:
+      load: productCard
+    contentWrapper:
+      tag: div
+      attributes:
+        style:
+          display: grid
+          gridTemplateColumns: "repeat(auto-fill, minmax(300px, 1fr))"
+          gap: 1rem
+          padding: 1rem
+    after:
+      type: div
+      content: "End of products"
+    templates:
+      productCard:
+        type: div
+        attributes:
+          style:
+            border: "1px solid #ccc"
+            borderRadius: 8px
+            padding: 1rem
+        content:
+          - type: h3
+            content: ~.name
+          - type: p
+            content: ~.description
+data:
+  products:
+    - name: "Product A"
+      description: "Description of product A"
+    - name: "Product B"
+      description: "Description of product B"
+    - name: "Product C"
+      description: "Description of product C"
+```
+
+### 5. Usage with `contentWrapper` for Flexbox Layout
+```yaml
+renderView:
+  - type: Switch
+    content: ~.items
+    singleOption:
+      load: flexItem
+    contentWrapper:
+      tag: section
+      attributes:
+        class: "flex-container"
+        style:
+          display: flex
+          flexWrap: wrap
+          justifyContent: space-between
+          alignItems: center
+    templates:
+      flexItem:
+        type: div
+        attributes:
+          style:
+            flex: "1 1 200px"
+            margin: 0.5rem
+            padding: 1rem
+            backgroundColor: "#f0f0f0"
+        content: ~.text
+data:
+  items:
+    - text: "Item 1"
+    - text: "Item 2"
+    - text: "Item 3"
+```
+
+### 6. Dynamic `contentWrapper` with Template Evaluation
+```yaml
+renderView:
+  - type: Switch
+    content: ~.galleries
+    singleOption:
+      load: imageItem
+    contentWrapper:
+      tag: div
+      attributes:
+        class: ~.layoutClass
+        style:
+          display: grid
+          gridTemplateColumns: ~.gridColumns
+          gap: ~.spacing
+          backgroundColor: ~.theme.backgroundColor
+    templates:
+      imageItem:
+        type: div
+        attributes:
+          style:
+            padding: 1rem
+            border: "1px solid #ddd"
+        content: ~.title
+data:
+  layoutClass: "photo-gallery"
+  gridColumns: "repeat(3, 1fr)"
+  spacing: "2rem"
+  theme:
+    backgroundColor: "#f5f5f5"
+  galleries:
+    - title: "Photo 1"
+    - title: "Photo 2"
+    - title: "Photo 3"
+```
+
+## Limitations
+- The data must be an array or object; strings and numbers are not supported
+- If both `options` and `singleOption` are provided, `singleOption` takes precedence
+- No built-in support for filtering or sorting (use DataFilter or custom logic)
+- Pagination requires the `paginated` property to be set to true
+- Templates must be defined in the `templates` object and referenced by `load`
+
+### Data Structure Requirements
+Switch requires each item in the data to be an object, not a primitive value:
+
+```yaml
+# ❌ This will NOT work:
+data:
+  items: ["string1", "string2", "string3"]
+
+# ✅ This will work:
+data:
+  items: 
+    - name: "string1"
+    - name: "string2"
+    - name: "string3"
+```
+