@ea-lab/reactive-json-docs 0.7.0 → 1.0.0-alpha.0

package/public/rjbuild/docs/core/element/special/Switch.yaml

@@ -6,24 +6,61 @@ renderView:
       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` (object/array/string, required): The data or path to the data to iterate over
-      - `options` (object, optional): Mapping of keys to templates for rendering each item (used for object/array of objects)
-      - `singleOption` (object, optional): Template to use for each item when all items share the same structure
-      - `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)
 
+  - type: DefinitionList
+    content:
+      - term:
+          code: content
+          after: "(object|array|string, required)"
+        details:
+          type: Markdown
+          content: "Data or path to the data to iterate over."
+      - term:
+          code: options
+          after: "(object, optional)"
+        details: "Mapping of keys to templates for rendering each item (used for object/array of objects)."
+      - term:
+          code: singleOption
+          after: "(object, optional)"
+        details: "Template to use for each item when all items share the same structure."
+      - term:
+          code: cardinality
+          after: "(number, optional)"
+        details: "Maximum number of items to render (default: unlimited)."
+      - term:
+          code: paginated
+          after: "(boolean, optional)"
+        details: "Whether to enable pagination (default: false)."
+      - term:
+          code: paginationProps
+          after: "(object, optional)"
+        details: "Pagination configuration (page size, etc.)."
+      - term:
+          code: before
+          after: "(object, optional)"
+        details: "Content to render before the list."
+      - term:
+          code: after
+          after: "(object, optional)"
+        details: "Content to render after the list."
+      - term:
+          code: contentWrapper
+          after: "(object, optional)"
+        details:
+          type: Markdown
+          content: |
+            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)
+
+  - type: Markdown
+    content: |
       ## 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
-      - If `singleOption` is provided, uses the same template for all items
-      - Supports limiting the number of items with `cardinality`
-      - Supports pagination if `paginated` is true
+      - 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.
+      - If `singleOption` is provided, uses the same template 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`
 
@@ -88,7 +125,7 @@ renderView:
       ```
 
   - type: RjBuildDescriber
-    title: "1. Simple usage with `singleOption` (no pagination)"
+    title: "Simple usage with `singleOption` (no pagination)"
     description: |
       This example shows a basic Switch rendering a list of users with a single template.
     toDescribe:
@@ -108,7 +145,7 @@ renderView:
           - name: "Charlie"
 
   - type: RjBuildDescriber
-    title: "2. Usage with `options` (different templates per key)"
+    title: "Usage with `options` (different templates per key)"
     description: |
       This example shows how to use different templates for each key in the data.
     toDescribe:
@@ -139,7 +176,7 @@ renderView:
               value: 25
 
   - type: RjBuildDescriber
-    title: "3. Usage with `singleOption` and pagination (4 per page, 10 items)"
+    title: "Usage with `singleOption` and pagination (4 per page, 10 items)"
     description: |
       This example demonstrates pagination with 4 items per page and 10 items in total. PageControls is added to the end of the list.
     toDescribe:
@@ -173,7 +210,7 @@ renderView:
           - value: 10
 
   - type: RjBuildDescriber
-    title: "4. Usage with `contentWrapper` for CSS Grid Layout"
+    title: "Usage with `contentWrapper` for CSS Grid Layout"
     description: |
       This example demonstrates how to use contentWrapper to apply a CSS Grid layout to the Switch items.
     toDescribe:
@@ -190,7 +227,7 @@ renderView:
                 gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))"
                 gap: 1rem
                 padding: 1rem
-                backgroundColor: "#f8f9fa"
+                border: "1px solid currentColor"
                 borderRadius: 8px
           before:
             type: h3
@@ -201,31 +238,28 @@ renderView:
               style:
                 textAlign: center
                 marginTop: 1rem
-                color: "#666"
             content: "End of product list"
       templates:
         productCard:
           type: div
           attributes:
             style:
-              border: "1px solid #ddd"
+              border: "1px solid currentColor"
               borderRadius: 8px
               padding: 1rem
-              backgroundColor: white
               textAlign: center
           content:
             - type: h4
               attributes:
                 style:
                   margin: "0 0 0.5rem 0"
-                  color: "#333"
               content: ~.name
             - type: p
               attributes:
                 style:
                   margin: 0
-                  color: "#666"
                   fontSize: "0.9rem"
+                  opacity: 0.8
               content: ~.description
       data:
         products:
@@ -239,7 +273,7 @@ renderView:
             description: "Affordable product D"
 
   - type: RjBuildDescriber
-    title: "5. Usage with `contentWrapper` and Pagination"
+    title: "Usage with `contentWrapper` and Pagination"
     description: |
       This example shows how contentWrapper works seamlessly with pagination.
     toDescribe:
@@ -261,7 +295,7 @@ renderView:
                 gap: 1rem
                 justifyContent: center
                 padding: 1rem
-                border: "2px dashed #ccc"
+                border: "2px dashed currentColor"
                 borderRadius: 8px
           after:
             type: PageControls
@@ -272,10 +306,9 @@ renderView:
             style:
               flex: "0 1 150px"
               padding: 1rem
-              backgroundColor: "#e3f2fd"
+              border: "1px solid currentColor"
               borderRadius: 8px
               textAlign: center
-              border: "1px solid #90caf9"
           content: ~.title
       data:
         cards:
@@ -288,7 +321,7 @@ renderView:
           - title: "Card 7"
 
   - type: RjBuildDescriber
-    title: "6. Dynamic `contentWrapper` with Template Evaluation"
+    title: "Dynamic `contentWrapper` with Template Evaluation"
     description: |
       This example demonstrates how contentWrapper attributes can use template evaluation to create dynamic layouts.
     toDescribe:
@@ -306,15 +339,14 @@ renderView:
                 gridTemplateColumns: ~.wrapperConfig.columns
                 gap: ~.wrapperConfig.spacing
                 padding: ~.wrapperConfig.padding
-                backgroundColor: ~.theme.background
                 border: ~.theme.border
                 borderRadius: ~.theme.borderRadius
           before:
             type: h3
             attributes:
               style:
-                color: ~.theme.titleColor
                 textAlign: center
+                fontWeight: bold
             content: ~.title
       templates:
         dynamicCard:
@@ -322,10 +354,10 @@ renderView:
           attributes:
             style:
               padding: 1rem
-              backgroundColor: ~.theme.cardBackground
+              border: ~.theme.cardBorder
               borderRadius: 6px
               textAlign: center
-              color: ~.theme.textColor
+
           content: ~.name
       data:
         title: "Dynamic Gallery"
@@ -335,12 +367,8 @@ renderView:
           spacing: "1.5rem"
           padding: "2rem"
         theme:
-          background: "#e8f4fd"
-          border: "2px solid #2196f3"
+          border: "2px solid currentColor"
           borderRadius: "12px"
-          titleColor: "#1976d2"
-          cardBackground: "#ffffff"
-          textColor: "#333333"
         items:
           - name: "Element A"
           - name: "Element B"

package/public/rjbuild/docs/core/example/html.md

@@ -39,7 +39,7 @@ HTML attributes are supported through the `attributes` property. Each attribute
 > When using inline styles, you must use a specific structure:
 > - Use an object with CSS properties as keys
 > - Use camelCase for property names instead of hyphen-based CSS casing
-> - For example, use `backgroundColor` instead of `background-color`
+> - For example, use `borderRadius` instead of `border-radius`
 
 ### Example with Attributes and Styles
 ```yaml
@@ -48,7 +48,7 @@ renderView:
     attributes:
       data-attr: Hello!
       style:
-        backgroundColor: rgb(250,242,0)
+        border: "2px solid rgb(250,242,0)"
         padding: 0.5em
     content:
       - "This is a "

package/public/rjbuild/docs/core/example/html.yaml

@@ -60,15 +60,14 @@ renderView:
             specify an object with the CSS property as the key, and CSS value as the value.
             Each key must be using **camelCase** instead of the usual hyphen-based CSS casing.
             
-            In the following example, `backgroundColor` is used for the `background-color`
-            CSS property.
+            In the following example, `border` is used to add visual styling.
     toDescribe:
       renderView:
         - type: div
           attributes:
             data-attr: Hello!
             style:
-              backgroundColor: rgb(250,242,0)
+              border: "2px solid rgb(250,242,0)"
               padding: 0.5em
           content:
             - "This is a "

package/public/rjbuild/docs/core/example/native-html-forms.md

@@ -0,0 +1,245 @@
+# Native HTML Forms
+
+This guide explains how to use native HTML form elements (`input`, `select`, `textarea`) with Reactive-JSON's reaction system to create interactive forms with proper data synchronization.
+
+## Core Concept: Reactions for Data Synchronization
+
+Native HTML elements require explicit **reactions** to synchronize user input with your data. This is done using the `setData` reaction triggered by user events.
+
+### Basic Structure
+
+```yaml
+- type: input
+  attributes:
+    type: "text"
+    value: ~.fieldName           # Display current data value
+  actions:
+    - what: setData              # Reaction to update data
+      on: input                  # Event that triggers the reaction
+      path: ~.fieldName          # Data path to update
+      value: "<reactive-json:event-new-value>"  # Value from the event
+```
+
+## Event Value Patterns
+
+### Forward Update Pattern (Recommended)
+
+Use `<reactive-json:event-new-value>` for automatic value detection:
+
+- **Auto-detects the correct property**: `event.target.value` for inputs, `event.target.checked` for checkboxes
+- **Simplifies configuration**: No need to specify which property to access
+- **Works for all form elements**: text, number, checkbox, select, textarea, etc.
+
+### Alternative Explicit Syntax
+
+For specific control, you can explicitly access event properties:
+
+- `<reactive-json:event>.target.value` - Direct access to input value
+- `<reactive-json:event>.target.checked` - Direct access to checkbox state
+- `<reactive-json:event>.target.selectedIndex` - Access to select index
+
+## Event Types for Different Use Cases
+
+- **`on: input`** - Real-time updates as user types (immediate feedback)
+- **`on: change`** - Updates when user commits the change (varies by element type):
+  - Text inputs: when value changes AND field loses focus
+  - Checkboxes/Radio: immediately when checked/unchecked
+  - Select: immediately when option is selected
+- **`on: blur`** - Updates when user leaves the field (regardless of value change)
+- **`on: focus`** - Triggered when user enters the field
+
+## Common Patterns
+
+### Label Association
+
+Use the `for` attribute to associate labels with form elements for accessibility:
+
+```yaml
+- type: label
+  attributes:
+    for: "username-field"
+  content: "Username:"
+- type: input
+  attributes:
+    id: "username-field"
+    type: "text"
+    value: ~.username
+  actions:
+    - what: setData
+      on: input
+      path: ~.username
+      value: "<reactive-json:event-new-value>"
+```
+
+**Note**: Reactive-JSON automatically converts the HTML `for` attribute to React's `htmlFor` property.
+
+### Text Input
+```yaml
+- type: input
+  attributes:
+    type: "text"
+    value: ~.fieldName
+  actions:
+    - what: setData
+      on: input
+      path: ~.fieldName
+      value: "<reactive-json:event-new-value>"
+```
+
+### Checkbox
+```yaml
+- type: input
+  attributes:
+    type: "checkbox"
+    checked: ~.isSelected
+  actions:
+    - what: setData
+      on: change
+      path: ~.isSelected
+      value: "<reactive-json:event-new-value>"
+```
+
+### Select Dropdown
+```yaml
+- type: select
+  attributes:
+    value: ~.selectedOption
+  content:
+    - type: option
+      attributes:
+        value: "option1"
+      content: "Option 1"
+  actions:
+    - what: setData
+      on: change
+      path: ~.selectedOption
+      value: "<reactive-json:event-new-value>"
+```
+
+### Textarea
+```yaml
+- type: textarea
+  attributes:
+    value: ~.description
+    placeholder: "Enter description..."
+    rows: 4
+  actions:
+    - what: setData
+      on: input
+      path: ~.description
+      value: "<reactive-json:event-new-value>"
+```
+
+### Number Input
+```yaml
+- type: input
+  attributes:
+    type: "number"
+    value: ~.quantity
+    min: 0
+    max: 100
+  actions:
+    - what: setData
+      on: input
+      path: ~.quantity
+      value: "<reactive-json:event-new-value>"
+```
+
+### Radio Buttons
+```yaml
+- type: input
+  attributes:
+    type: "radio"
+    name: "size"
+    value: "small"
+    checked: ~.selectedSize
+  actions:
+    - what: setData
+      on: change
+      path: ~.selectedSize
+      value: "small"
+
+- type: input
+  attributes:
+    type: "radio"
+    name: "size"
+    value: "large"
+    checked: ~.selectedSize
+  actions:
+    - what: setData
+      on: change
+      path: ~.selectedSize
+      value: "large"
+```
+
+## Advanced Patterns
+
+### Form Validation with Conditional Actions
+```yaml
+- type: input
+  attributes:
+    type: "email"
+    value: ~.email
+  actions:
+    - what: setData
+      on: input
+      path: ~.email
+      value: "<reactive-json:event-new-value>"
+    - what: setData
+      on: blur
+      path: ~.emailValid
+      value: "<reactive-json:event>.target.validity.valid"
+```
+
+### Multiple Field Updates
+```yaml
+- type: input
+  attributes:
+    type: "text"
+    value: ~.firstName
+  actions:
+    - what: setData
+      on: input
+      path: ~.firstName
+      value: "<reactive-json:event-new-value>"
+    - what: setData
+      on: input
+      path: ~.fullName
+      value: ["<reactive-json:event-new-value>", " ", ~.lastName]
+```
+
+## Simplification Alternatives
+
+For simpler configuration and built-in styling, consider using pre-built form components:
+
+- **Reactive-JSON Bootstrap**: `TextField`, `SelectField`, `CheckBoxField`, etc. with automatic data synchronization
+- **Custom component libraries**: Create your own reusable form components with embedded reactions
+
+Example with Bootstrap components:
+```yaml
+# Simpler alternative using reactive-json-bootstrap
+- type: TextField
+  label: "Username:"
+  dataLocation: ~.username  # Automatic synchronization
+
+# Equivalent native implementation
+- type: label
+  content: "Username:"
+- type: input
+  attributes:
+    type: "text"
+    value: ~.username
+  actions:
+    - what: setData
+      on: input
+      path: ~.username
+      value: "<reactive-json:event-new-value>"
+```
+
+## Best Practices
+
+1. **Always include `setData` reactions** for interactive elements
+2. **Choose appropriate events**: `input` for real-time updates, `change` for committed changes
+3. **Use `<reactive-json:event-new-value>`** for automatic value detection
+4. **Consider pre-built components** for complex forms to reduce configuration
+5. **Test data flow** to ensure changes are properly synchronized