@ea-lab/reactive-json-docs 0.1.2

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

@@ -0,0 +1,315 @@
+renderView:
+  - type: Markdown
+    content: |
+      # DataFilter
+
+      The `DataFilter` component allows you to filter data from the global or template context before rendering its content. It is particularly useful for conditional display of elements based on dynamic complex criteria, such as filtering lists, trees, or data subsets.
+
+      ## Properties
+      - `filters` (array, required): Array of filter objects, each specifying properties and conditions to check
+        - `subjectsWithProperty` (string): Property to check in the data, acts as namespace
+        - `andConditions` (array): List of conditions that must all be true
+        - `orConditions` (array): List of conditions where at least one must be true
+        - Available conditions:
+          - `when`: Checks a condition on a value
+          - `is`: Compares exact equality
+          - `isNot`: Checks inequality
+          - `isEmpty`: Checks if a value is empty
+          - `contains`: Checks if a value contains a substring
+          - `>=`, `<=`, `>`, `<`: Numeric comparisons
+          - `compareAsDates`: Boolean to compare values as dates
+          - `whenFilterableData`: Specifies the data path to filter, must include the namespace
+      - `context` (string, optional): Context to filter (`global` or `template`). Default: `global`
+      - `content` (object/array, required): Content to render after filtering
+
+      ## Behavior
+      - Applies all filters to the selected context before content rendering
+      - Supports complex filtering conditions with `andConditions` and `orConditions`
+      - Allows recursive filtering while preserving data structure
+      - Can be combined with other components to create interactive filtering interfaces
+      - Supports dynamic filtering based on application state
+
+      ## Filterable Data Structure
+
+      DataFilter uses a specific pattern to identify and filter data. This pattern relies on an identification key (namespace) that must be consistent between the data structure and filtering conditions.
+
+      ### Namespace Pattern
+
+      1. **In the data structure**:
+      ```yaml
+      data:
+        filteredItems:
+          - item:           # <- Identification key (namespace)
+              id: 1
+              title: "..."
+          - item:           # <- Same key for each item
+              id: 2
+              title: "..."
+      ```
+
+      2. **In filtering conditions**:
+      ```yaml
+      type: DataFilter
+      context: global
+      filters:
+        - subjectsWithProperty: item    # <- Declares the namespace
+          andConditions:
+            - orConditions:
+                - whenFilterableData: item.title  # <- Uses the namespace
+                  contains: "..."
+      ```
+
+      The identification key (here "item"):
+      - Can have any name (`itemXyz`, `element`, etc.)
+      - Must be consistent between data structure and conditions
+      - Serves as a namespace for accessing properties in `whenFilterableData`
+      - Is required for DataFilter to correctly identify filterable elements
+
+  - type: RjBuildDescriber
+    title: Advanced Example
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: "container-fluid"
+          content:
+            - type: div
+              attributes:
+                class: "row mb-4"
+              content:
+                - type: div
+                  attributes:
+                    class: "col-md-6"
+                  content:
+                    - type: div
+                      attributes:
+                        class: "card h-100"
+                      content:
+                        - type: div
+                          attributes:
+                            class: "card-header bg-secondary text-white"
+                          content:
+                            - type: h5
+                              attributes:
+                                class: "card-title mb-0"
+                              content: "📋 All Items (Unfiltered)"
+                        - type: div
+                          attributes:
+                            class: "card-body"
+                          content:
+                            - type: div
+                              attributes:
+                                class: "list-group list-group-flush"
+                              content:
+                                type: Switch
+                                content: ~.filteredItems
+                                singleOption:
+                                  load: item
+                - type: div
+                  attributes:
+                    class: "col-md-6"
+                  content:
+                    - type: div
+                      attributes:
+                        class: "card h-100"
+                      content:
+                        - type: div
+                          attributes:
+                            class: "card-header bg-primary text-white"
+                          content:
+                            - type: h5
+                              attributes:
+                                class: "card-title mb-0"
+                              content: "🔍 Filtered Results"
+                        - type: div
+                          attributes:
+                            class: "card-body"
+                          content:
+                            - type: DataFilter
+                              context: global
+                              filters:
+                                - subjectsWithProperty: item
+                                  andConditions:
+                                    # Text search filter
+                                    - orConditions:
+                                        - when: ~~._filters.search
+                                          isEmpty:
+                                        - whenFilterableData: item.searchableContent
+                                          contains: ~~._filters.search
+
+                                    # Date filter
+                                    - orConditions:
+                                        - when: ~~._filters.since
+                                          isEmpty:
+                                        - whenFilterableData: item.creationDate
+                                          ">=": ~~._filters.since
+                                          compareAsDates: true
+
+                                    # Status filter
+                                    - orConditions:
+                                        - when: ~~._filters.status
+                                          isNot: active_only
+                                        - whenFilterableData: item.status
+                                          is: active
+
+                              content:
+                                - type: div
+                                  attributes:
+                                    class: "list-group list-group-flush"
+                                  content:
+                                    type: Switch
+                                    content: ~~.filteredItems
+                                    singleOption:
+                                      load: item
+            - type: div
+              attributes:
+                class: "row mt-4"
+              content:
+                - type: div
+                  attributes:
+                    class: "col-12"
+                  content:
+                    - type: div
+                      attributes:
+                        class: "card"
+                      content:
+                        - type: div
+                          attributes:
+                            class: "card-header bg-info text-white"
+                          content:
+                            - type: h5
+                              attributes:
+                                class: "card-title mb-0"
+                              content: "⚙️ Filter Controls"
+                        - type: div
+                          attributes:
+                            class: "card-body"
+                          content:
+                            # Filtering interface
+                            - type: div
+                              attributes:
+                                class: "row g-3"
+                              content:
+                                - type: div
+                                  attributes:
+                                    class: "col-md-4"
+                                  content:
+                                    - type: TextField
+                                      placeholder: "Search..."
+                                      dataLocation: ~~._filters.search
+                                - type: div
+                                  attributes:
+                                    class: "col-md-4"
+                                  content:
+                                    - # TODO: replace this by the DateField when DateField will support type="date".
+                                      type: TextField
+                                      inputType: date
+                                      dataLocation: ~~._filters.since
+                                - type: div
+                                  attributes:
+                                    class: "col-md-4"
+                                  content:
+                                    - type: SelectField
+                                      dataLocation: ~~._filters.status
+                                      options:
+                                        - label: "All"
+                                          value: all
+                                        - label: "Active only"
+                                          value: active_only
+
+      templates:
+        item:
+          type: div
+          attributes:
+            class: "list-group-item d-flex justify-content-between align-items-center border-start-0 border-end-0 py-3"
+          content:
+            - type: div
+              attributes:
+                class: "d-flex align-items-center gap-3"
+              content:
+                - type: CheckBoxField
+                  attributes:
+                    class: "form-check"
+                  options:
+                    - value: true
+                      label: ""
+                  dataLocation: ~.item.isSelected
+                - type: div
+                  attributes:
+                    class: "d-flex flex-column"
+                  content:
+                    - type: div
+                      attributes:
+                        class: "fw-bold mb-1"
+                      content: ~.item.searchableContent
+                    - type: div
+                      attributes:
+                        class: "text-muted small"
+                      content: ~.item.creationDate
+            - type: div
+              attributes:
+                class: "d-flex gap-2"
+              content:
+                - type: span
+                  attributes:
+                    class: "badge rounded-pill"
+                    style:
+                      backgroundColor: "#198754"
+                      color: "white"
+                  content: ~.item.status
+                  actions:
+                    - what: hide
+                      when: ~.item.status
+                      isNot: active
+                - type: span
+                  attributes:
+                    class: "badge rounded-pill"
+                    style:
+                      backgroundColor: "#dc3545"
+                      color: "white"
+                  content: ~.item.status
+                  actions:
+                    - what: hide
+                      when: ~.item.status
+                      is: active
+      data:
+        _filters:
+          search: ""
+          since: ""
+          status: "all"
+        filteredItems:
+          - item:
+              id: 1
+              searchableContent: "First item"
+              status: "active"
+              creationDate: "2024-03-20"
+              isSelected: true
+          - item:
+              id: 2
+              searchableContent: "Second item"
+              status: "inactive"
+              creationDate: "2024-03-19"
+              isSelected: false
+
+  - type: Markdown
+    content: |
+      ## Advanced Use Cases
+      - Multi-criteria filtering with combined conditions
+      - Real-time search interface
+      - Hierarchical data filtering (trees, sub-elements)
+      - Complex state management (conflicts, modifications, new elements)
+      - Integration with pagination components
+      - Date-based filtering and numeric comparisons
+
+      ## Best Practices
+      - Organize filters by logical category
+      - Use comments to document complex conditions
+      - Combine with UI components for interactive experience
+      - Consider performance with large datasets
+      - Use reusable templates for common filters
+
+      ## Limitations
+      - Filtering is based on simple comparisons
+      - Performance may be impacted with very large datasets
+      - Does not support custom filtering functions
+      - Filtering is applied recursively on the entire structure

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

@@ -0,0 +1,51 @@
+# DelayedActions
+
+## Introduction
+
+The `DelayedActions` component allows you to execute one or more actions after a delay or at regular intervals. It is useful for implementing polling, periodic updates, or delayed reactions in your Reactive-JSON applications.
+
+## Properties
+- `delayedActions` (array, required): Array of action objects to execute after the delay or at each interval
+- `interval` (number, required): The delay or interval in milliseconds between executions
+- `once` (boolean, optional): If true, actions are executed only once after the delay; if false (default), actions repeat at each interval
+- `content` (object/array, optional): Content to render inside the component
+
+## Behavior
+- Executes all actions in `delayedActions` after the specified delay or at each interval
+- If `once` is true, actions are executed only once; otherwise, they repeat at each interval
+- Actions are executed without requiring a user event (time is the trigger)
+- The component can render content, but the main purpose is to trigger actions
+- If `interval` is not provided, no actions are executed
+
+## Example
+```yaml
+renderView:
+  - type: Phantom
+    actions:
+      - # This will prevent infinite add.
+        what: hide
+        andConditions:
+          - whenDataCountOf: $.tick[*]
+            ">": 1000
+    content:
+      - type: DelayedActions
+        interval: 2000
+        delayedActions:
+          - what: addData
+            path: ~~.tick
+            value: "Ticked!"
+        content:
+          - type: p
+            content:
+              - "Tick count: "
+              - type: Count
+                jsonPathPattern: "$.tick[*]"
+
+data: {}
+```
+
+## Limitations
+- Only supports time-based triggering (no event-based delay)
+- All actions are executed in the order provided
+- No built-in error handling for action execution
+- If `interval` is missing or invalid, nothing happens 

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

@@ -0,0 +1,55 @@
+renderView:
+  - type: Markdown
+    content: |
+      # DelayedActions
+
+      The `DelayedActions` component allows you to execute one or more actions after a delay or at regular intervals. It is useful for implementing polling, periodic updates, or delayed reactions in your Reactive-JSON applications.
+
+      ## Properties
+      - `delayedActions` (array, required): Array of action objects to execute after the delay or at each interval
+      - `interval` (number, required): The delay or interval in milliseconds between executions
+      - `once` (boolean, optional): If true, actions are executed only once after the delay; if false (default), actions repeat at each interval
+      - `content` (object/array, optional): Content to render inside the component
+
+      ## Behavior
+      - Executes all actions in `delayedActions` after the specified delay or at each interval
+      - If `once` is true, actions are executed only once; otherwise, they repeat at each interval
+      - Actions are executed without requiring a user event (time is the trigger)
+      - The component can render content, but the main purpose is to trigger actions
+      - If `interval` is not provided, no actions are executed
+
+  - type: RjBuildDescriber
+    title: Example
+    description: This example adds an item in a data array every 2 seconds, and shows the item count.
+    toDescribe:
+      renderView:
+        - type: Phantom
+          actions:
+            - # This will prevent infinite add.
+              what: hide
+              andConditions:
+                - whenDataCountOf: $.tick[*]
+                  ">": 1000
+          content:
+            - type: DelayedActions
+              interval: 2000
+              delayedActions:
+                - what: addData
+                  path: ~~.tick
+                  value: "Ticked!"
+              content:
+                - type: p
+                  content:
+                    - "Tick count: "
+                    - type: Count
+                      jsonPathPattern: "$.tick[*]"
+
+      data: {}
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only supports time-based triggering (no event-based delay)
+      - All actions are executed in the order provided
+      - No built-in error handling for action execution
+      - If `interval` is missing or invalid, nothing happens 

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

@@ -0,0 +1,126 @@
+# PageControls
+
+## Introduction
+
+The `PageControls` component displays the pagination controls provided by the current `PaginationContext`. It is useful for rendering navigation controls (such as next/previous buttons or page numbers) in paginated lists or tables.
+
+## Properties
+- (none)
+
+## Behavior
+- Renders the pagination controls from the current `PaginationContext` if available
+- If no pagination controls are present in the context, renders nothing
+- Intended to be used inside paginated views or lists
+
+## Pagination Context
+The pagination context is provided by components like `Switch` when the `paginated` property is set to `true`.
+
+## Interactive Example with Switch
+
+This example shows how PageControls works with a paginated Switch component to display a list of users.
+
+```yaml
+renderView:
+  - type: div
+    attributes:
+      class: container-fluid p-3
+    content:
+      - type: h3
+        content: Paginated User List
+      
+      - type: div
+        attributes:
+          class: mb-3
+        content:
+          - type: strong
+            content: "Total number of users: "
+          - type: Count
+            context: global
+            count: ~.users
+            
+      - type: Switch
+        content: ~.users
+        singleOption:
+          load: userItem
+        paginated: true
+        paginationProps:
+          pageMaxItemCount: 3
+          maxPageButtonsCount: 5
+        before:
+          type: div
+          attributes:
+            class: alert alert-info
+          content: "Here are the users (3 per page):"
+        after:
+          - type: div
+            attributes:
+              class: d-flex justify-content-center mt-3
+            content:
+              type: PageControls
+          - type: div
+            attributes:
+              class: text-center mt-2 text-muted
+            content: "Use the controls above to navigate between pages"
+
+templates:
+  userItem:
+    type: div
+    attributes:
+      class: card mb-2
+    content:
+      type: div
+      attributes:
+        class: card-body
+      content:
+        - type: h5
+          attributes:
+            class: card-title
+          content: ~.name
+        - type: div
+          attributes:
+            class: card-text
+          content:
+            - type: div
+              content: ["Email: ", ~.email]
+            - type: div
+              content: ["Department: ", ~.department]
+
+data:
+  users:
+    - name: "Alice Martin"
+      email: "alice.martin@example.com"
+      department: "Development"
+    - name: "Bob Dupont"
+      email: "bob.dupont@example.com"
+      department: "Design"
+    - name: "Claire Bernard"
+      email: "claire.bernard@example.com"
+      department: "Marketing"
+    - name: "David Rousseau"
+      email: "david.rousseau@example.com"
+      department: "Development"
+    - name: "Emma Leroy"
+      email: "emma.leroy@example.com"
+      department: "Support"
+    - name: "François Moreau"
+      email: "francois.moreau@example.com"
+      department: "Design"
+    - name: "Gabrielle Petit"
+      email: "gabrielle.petit@example.com"
+      department: "Marketing"
+    - name: "Henri Blanc"
+      email: "henri.blanc@example.com"
+      department: "Development"
+    - name: "Isabelle Roux"
+      email: "isabelle.roux@example.com"
+      department: "Support"
+    - name: "Julien Vincent"
+      email: "julien.vincent@example.com"
+      department: "Design"
+```
+
+## Limitations
+- Only works if a `PaginationContext` is present and provides controls
+- Does not manage pagination state itself; only renders controls from the context
+- No customization of the controls via props
+- Entirely depends on the parent component (like Switch) for pagination logic 

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

@@ -0,0 +1,133 @@
+renderView:
+  - type: Markdown
+    content: |
+      # PageControls
+
+      The `PageControls` component displays the pagination controls provided by the current `PaginationContext`. It is useful for rendering navigation controls (such as next/previous buttons or page numbers) in paginated lists or tables.
+
+      ## Properties
+      - (none)
+
+      ## Behavior
+      - Renders the pagination controls from the current `PaginationContext` if available
+      - If no pagination controls are present in the context, renders nothing
+      - Intended to be used inside paginated views or lists
+
+      ## Pagination Context
+      The pagination context is provided by components like `Switch` when the `paginated` property is set to `true`.
+
+  - type: RjBuildDescriber
+    title: Interactive Example with Switch
+    description:
+      - type: div
+        content: This example shows how PageControls works with a paginated Switch component to display a list of users.
+    toDescribe:
+      renderView:
+        - type: div
+          attributes:
+            class: container-fluid p-3
+          content:
+            - type: h3
+              content: Paginated User List
+            
+            - type: div
+              attributes:
+                class: mb-3
+              content:
+                - type: strong
+                  content: "Total number of users: "
+                - type: Count
+                  context: global
+                  count: ~.users
+                  
+            - type: Switch
+              content: ~.users
+              singleOption:
+                load: userItem
+              paginated: true
+              paginationProps:
+                pageMaxItemCount: 3
+                maxPageButtonsCount: 5
+              before:
+                type: div
+                attributes:
+                  class: alert alert-info
+                content: "Here are the users (3 per page):"
+              after:
+                - type: div
+                  attributes:
+                    class: d-flex justify-content-center mt-3
+                  content:
+                    type: PageControls
+                - type: div
+                  attributes:
+                    class: text-center mt-2 text-muted
+                  content: "Use the controls above to navigate between pages"
+
+      templates:
+        userItem:
+          type: div
+          attributes:
+            class: card mb-2
+          content:
+            type: div
+            attributes:
+              class: card-body
+            content:
+              - type: h5
+                attributes:
+                  class: card-title
+                content: ~.name
+              - type: div
+                attributes:
+                  class: card-text
+                content:
+                  - type: div
+                    content: ["Email: ", ~.email]
+                  - type: div
+                    content: ["Department: ", ~.department]
+
+      data:
+        users:
+          - name: "Alice Martin"
+            email: "alice.martin@example.com"
+            department: "Development"
+          - name: "Bob Dupont"
+            email: "bob.dupont@example.com"
+            department: "Design"
+          - name: "Claire Bernard"
+            email: "claire.bernard@example.com"
+            department: "Marketing"
+          - name: "David Rousseau"
+            email: "david.rousseau@example.com"
+            department: "Development"
+          - name: "Emma Leroy"
+            email: "emma.leroy@example.com"
+            department: "Support"
+          - name: "François Moreau"
+            email: "francois.moreau@example.com"
+            department: "Design"
+          - name: "Gabrielle Petit"
+            email: "gabrielle.petit@example.com"
+            department: "Marketing"
+          - name: "Henri Blanc"
+            email: "henri.blanc@example.com"
+            department: "Development"
+          - name: "Isabelle Roux"
+            email: "isabelle.roux@example.com"
+            department: "Support"
+          - name: "Julien Vincent"
+            email: "julien.vincent@example.com"
+            department: "Design"
+
+  - type: Markdown
+    content: |
+      ## Limitations
+      - Only works if a `PaginationContext` is present and provides controls
+      - Does not manage pagination state itself; only renders controls from the context
+      - No customization of the controls via props
+      - Entirely depends on the parent component (like Switch) for pagination logic
+
+templates:
+
+data: {}