robobyte-front-builder 1.0.26 → 1.0.27

package/training/28-wizard.md

@@ -0,0 +1,126 @@
+# Component: wizard
+
+A multi-step stepper form. Contains `wizard-step` children. Handles navigation (Back/Next/Finish) with optional linear enforcement and lifecycle hooks.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier for the wizard. |
+| `orientation` | select | `horizontal` — stepper bar across the top. `vertical` — stepper on the left side. |
+| `variant` | select | `standard` — step numbers above connector lines. `alternativeLabel` — step labels below the circles. |
+| `linear` | boolean | `true` (default) forces sequential completion — user cannot jump to a later step without completing previous. `false` allows clicking any step. |
+| `hideNavigation` | boolean | `true` hides Back/Next/Finish buttons. Use when you control navigation via custom buttons in step content. |
+| `activeStep` | expression | Controlled active step index. When set, wizard is fully controlled from external state. |
+| `backLabel` | expression | Label for the Back button. Default: `"Back"`. |
+| `nextLabel` | expression | Label for the Next button. Default: `"Next"`. |
+| `finishLabel` | expression | Label for the Finish button on the last step. Default: `"Finish"`. |
+| `nextColor` | select | `primary` · `secondary` · `success` · `error` · `warning` · `info` · `inherit` |
+| `nextVariant` | select | `text` · `outlined` · `contained` |
+| `backColor` | select | Same options as nextColor. |
+| `backVariant` | select | Same options as nextVariant. |
+| `onStepChange` | code | Runs when the active step changes. Available variables: `from`, `to`, `direction` (`"next"` / `"back"` / `"jump"`), `goToStep`, `nextStep`, `prevStep`. |
+| `onFinish` | code | Runs when the user clicks Finish on the last step. Available variables: `goToStep`, `nextStep`, `prevStep`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Layout via parent cell.
+
+---
+
+## Props — Actions Tab
+
+No action tab — use `onStepChange` and `onFinish` code fields in Main.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Multi-step registration/onboarding forms.
+- Checkout flows: Cart → Shipping → Payment → Review.
+- Guided configuration wizards.
+- Any process where steps have dependencies and need validation before proceeding.
+
+**When NOT to use:**
+- Simple tabbed content without sequential logic → use `menu`.
+- Unlimited, non-linear navigation → use `menu`.
+- Single form that doesn't need step structure.
+
+---
+
+## Schema Examples
+
+### Basic 3-step wizard
+```json
+{
+  "type": "wizard",
+  "props": {
+    "key": "registrationWizard",
+    "orientation": "horizontal",
+    "variant": "standard",
+    "linear": true,
+    "nextLabel": "Continue",
+    "finishLabel": "Submit Registration",
+    "nextColor": "primary",
+    "nextVariant": "contained"
+  },
+  "children": [
+    {
+      "type": "wizard-step",
+      "props": {
+        "key": "personal",
+        "label": "Personal Info",
+        "description": "Your basic details"
+      },
+      "children": [
+        { "type": "input", "props": { "key": "firstName", "label": "First Name", "required": true } },
+        { "type": "input", "props": { "key": "lastName", "label": "Last Name", "required": true } }
+      ]
+    },
+    {
+      "type": "wizard-step",
+      "props": {
+        "key": "contact",
+        "label": "Contact",
+        "description": "How to reach you"
+      },
+      "children": [
+        { "type": "input", "props": { "key": "email", "label": "Email", "required": true } },
+        { "type": "input", "props": { "key": "phone", "label": "Phone" } }
+      ]
+    },
+    {
+      "type": "wizard-step",
+      "props": {
+        "key": "confirm",
+        "label": "Review & Submit"
+      },
+      "children": [
+        { "type": "label", "props": { "text": "Please review your details before submitting.", "variant": "body2" } }
+      ]
+    }
+  ]
+}
+```
+
+### Wizard with onFinish submission
+```json
+{
+  "type": "wizard",
+  "props": {
+    "key": "checkoutWizard",
+    "orientation": "horizontal",
+    "linear": true,
+    "finishLabel": "Place Order",
+    "nextColor": "primary",
+    "nextVariant": "contained",
+    "onFinish": "submitOrder({ cart: data.cart, shipping: form })"
+  },
+  "children": []
+}
+```

package/training/29-wizard-step.md

@@ -0,0 +1,92 @@
+# Component: wizard-step
+
+A single step inside a `wizard`. Must be a direct child of `wizard`. Contains the form fields or content for that step.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Step identifier. Used in navigation logic. |
+| `label` | expression | Step label shown in the stepper header, e.g. `"Personal Info"`. |
+| `description` | expression | Short subtitle shown below the step label in the stepper. |
+| `optional` | boolean | `true` shows `"(Optional)"` below the step label. |
+| `completed` | expression | Expression returning `true` marks the step with a checkmark icon. |
+| `error` | expression | Expression returning `true` marks the step in error state (red). |
+| `onEnter` | code | Runs when this step becomes active. Available: `stepIndex`, `goToStep`, `nextStep`, `prevStep`. Use to load data or reset form state. |
+| `onNext` | code | Runs before leaving this step when clicking Next. Return `true`/`undefined` to allow navigation. Return `false` to silently block. Return a string to block and display as an error message. Available: `stepIndex`, `goToStep`, `nextStep`, `prevStep`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No action tab — lifecycle code is in the Main tab via `onEnter` and `onNext`.
+
+---
+
+## Use Cases
+
+- Each step in a `wizard` flow.
+- `onNext` for step validation: return `"Email is required"` if `!form.email`.
+- `onEnter` to pre-load data for the step: fetch the user's address when entering the shipping step.
+- `completed` expression to show a green checkmark when step data is valid.
+- `error` expression to highlight a step that failed server-side validation.
+
+---
+
+## Schema Examples
+
+### Step with validation
+```json
+{
+  "type": "wizard-step",
+  "props": {
+    "key": "personalInfo",
+    "label": "Personal Info",
+    "description": "Your basic details",
+    "required": false,
+    "onNext": "if (!form.firstName || !form.email) return 'Please fill in all required fields.'"
+  },
+  "children": [
+    { "type": "input", "props": { "key": "firstName", "label": "First Name", "required": true } },
+    { "type": "input", "props": { "key": "email", "label": "Email", "required": true } }
+  ]
+}
+```
+
+### Step with data load on enter
+```json
+{
+  "type": "wizard-step",
+  "props": {
+    "key": "shipping",
+    "label": "Shipping",
+    "onEnter": "fetchAddresses({ userId: data.userId })"
+  },
+  "children": [
+    { "type": "dropdown", "props": { "key": "addressId", "label": "Select Address", "options": "data.addresses" } }
+  ]
+}
+```
+
+### Optional step with completion indicator
+```json
+{
+  "type": "wizard-step",
+  "props": {
+    "key": "documents",
+    "label": "Documents",
+    "optional": true,
+    "completed": "data.documentsUploaded",
+    "error": "data.documentError"
+  },
+  "children": []
+}
+```

package/training/30-repeater.md

@@ -0,0 +1,123 @@
+# Component: repeater
+
+Renders a template multiple times — once per item in an array (or a fixed count). Each repetition has its own scoped `dataItem` and `itemIndex` available in expressions.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. When combined with `dataKey`, the complete array is accessible at `data[key]`. |
+| `items` | expression | Array of objects to iterate, e.g. `data.employees`. Each item is exposed as `dataItem` in child expressions. |
+| `count` | expression | Fixed number of repetitions when `items` is not set. The repeater generates `count` empty slots. |
+| `dataKey` | expression | Parent data key where item values are stored/read back. When set, each item's inputs write to `data[dataKey][index]`, and the full array is readable at `data[dataKey]`. |
+| `itemKey` | expression | Property on each item to use as the React key for stable rendering, e.g. `"id"`. Falls back to index. |
+| `widgetId` | expression | ID of a saved widget to render as the item template. When set, the repeater fetches that widget and renders it instead of inline children. |
+| `direction` | select | `vertical` — items stack top-to-bottom. `horizontal` — items flow left-to-right. `wrap` — horizontal flow that wraps to next line. |
+| `gap` | expression | Spacing between items, e.g. `"16px"`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control via parent layout-cell.
+
+---
+
+## Props — Actions Tab
+
+No actions. Each child component inside the repeater handles its own events.
+
+---
+
+## Available Variables Inside Repeater Children
+
+- `dataItem` — the current item object from `items` array.
+- `itemIndex` — the zero-based index of the current item.
+- `data[dataKey][itemIndex]` — scoped form data for this item's inputs.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Rendering a list of cards: employee cards, product tiles.
+- Line-item entry: invoice lines, order items (with `dataKey` for editable rows).
+- Dynamic form: "Add another contact" pattern.
+- Grid of similar items: photo gallery, tag list.
+
+**When NOT to use:**
+- Tabular data with sorting/filtering → use `dataGrid`.
+- Static content that doesn't repeat → use `layout` cells.
+- Server-paged large datasets → use `reportViewer`.
+
+---
+
+## Schema Examples
+
+### Read-only list of employee cards
+```json
+{
+  "type": "repeater",
+  "props": {
+    "key": "employeeList",
+    "items": "data.employees",
+    "itemKey": "id",
+    "direction": "vertical",
+    "gap": "12px"
+  },
+  "children": [
+    {
+      "type": "layout-cell",
+      "style": { "backgroundColor": "#fff", "borderRadius": "8px", "padding": "16px", "boxShadow": "0 1px 4px rgba(0,0,0,0.08)" },
+      "children": [
+        { "type": "header", "props": { "text": "dataItem.name", "variant": "h6" } },
+        { "type": "label", "props": { "text": "dataItem.role", "variant": "body2", "color": "textSecondary" } }
+      ]
+    }
+  ]
+}
+```
+
+### Editable line items (with dataKey)
+```json
+{
+  "type": "repeater",
+  "props": {
+    "key": "invoiceLines",
+    "items": "data.lines",
+    "dataKey": "lines",
+    "itemKey": "id",
+    "direction": "vertical",
+    "gap": "8px"
+  },
+  "children": [
+    {
+      "type": "layout",
+      "props": { "cols": 3, "gap": 8 },
+      "children": [
+        { "type": "layout-cell", "children": [{ "type": "input", "props": { "key": "description", "label": "Description", "value": "dataItem.description" } }] },
+        { "type": "layout-cell", "children": [{ "type": "number", "props": { "key": "qty", "label": "Qty", "value": "dataItem.qty" } }] },
+        { "type": "layout-cell", "children": [{ "type": "number", "props": { "key": "price", "label": "Price", "value": "dataItem.price", "formatType": "currency", "currencySymbol": "$" } }] }
+      ]
+    }
+  ]
+}
+```
+
+### Fixed count (no data)
+```json
+{
+  "type": "repeater",
+  "props": {
+    "key": "ratings",
+    "count": 5,
+    "direction": "horizontal",
+    "gap": "8px"
+  },
+  "children": [
+    { "type": "label", "props": { "text": "itemIndex + 1 + ' - Rating slot'", "variant": "caption" } }
+  ]
+}
+```

package/training/31-dialog.md

@@ -0,0 +1,131 @@
+# Component: dialog
+
+A modal dialog overlay. Opened/closed via `openDialog(key)` / `closeDialog(key)` actions. Can contain inline child components or embed an entire saved view via `viewId`.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | **Required.** The key passed to `openDialog(key)` and `closeDialog(key)` in action code. |
+| `viewId` | expression | ID of a saved view to render as the dialog body. Leave blank to use inline dropped children. |
+| `title` | expression | Dialog title shown in the header bar. |
+| `hideTitle` | boolean | `true` hides the entire title bar (including close button). |
+| `maxWidth` | select | `xs` · `sm` · `md` · `lg` · `xl` — Maximum width of the dialog. |
+| `fullWidth` | boolean | Dialog stretches to the full `maxWidth`. |
+| `fullScreen` | boolean | Dialog occupies the entire screen. |
+| `showCloseButton` | boolean | Shows an × close button in the title bar. |
+| `closeOnBackdrop` | boolean | Clicking outside the dialog closes it. |
+| `dialogActions` | actions-config-editor | Buttons rendered in a DialogActions bar at the bottom. Each button has `label`, `color`, `variant`, and custom code. `closeDialog(key)` is available in action code. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No action tab. Dialog lifecycle is controlled via `openDialog`/`closeDialog` in other components' action code.
+
+---
+
+## How to Open and Close
+
+From any action code (e.g. button onClick):
+```javascript
+openDialog('myDialog')   // opens the dialog
+closeDialog('myDialog')  // closes the dialog
+```
+
+---
+
+## Use Cases
+
+**When to use:**
+- Confirmation dialogs: "Are you sure you want to delete?"
+- Edit forms in a modal: click a row → open edit dialog.
+- Detail panels: view full record without leaving the page.
+- Multi-step forms inside a dialog.
+- Loading a complex sub-view (via `viewId`).
+
+**When NOT to use:**
+- Tooltips or small floating panels → use `popover`.
+- Navigation between pages → use `viewRenderer` or routing.
+- Inline expanding content → use `card` or conditional visibility.
+
+---
+
+## Schema Examples
+
+### Confirmation dialog
+```json
+{
+  "type": "dialog",
+  "props": {
+    "key": "confirmDelete",
+    "title": "Confirm Delete",
+    "maxWidth": "sm",
+    "fullWidth": true,
+    "showCloseButton": true,
+    "closeOnBackdrop": false,
+    "dialogActions": [
+      {
+        "label": "Cancel",
+        "variant": "text",
+        "color": "inherit",
+        "code": "closeDialog('confirmDelete')"
+      },
+      {
+        "label": "Delete",
+        "variant": "contained",
+        "color": "error",
+        "code": "deleteRecord({ id: data.selectedId }); closeDialog('confirmDelete')"
+      }
+    ]
+  },
+  "children": [
+    { "type": "label", "props": { "text": "This action cannot be undone. Are you sure?", "variant": "body1" } }
+  ]
+}
+```
+
+### Edit dialog with embedded view
+```json
+{
+  "type": "dialog",
+  "props": {
+    "key": "editEmployee",
+    "title": "Edit Employee",
+    "viewId": "data.editViewId",
+    "maxWidth": "md",
+    "fullWidth": true,
+    "showCloseButton": true,
+    "closeOnBackdrop": true,
+    "dialogActions": [
+      { "label": "Close", "variant": "outlined", "color": "inherit", "code": "closeDialog('editEmployee')" }
+    ]
+  }
+}
+```
+
+### Full-screen form dialog
+```json
+{
+  "type": "dialog",
+  "props": {
+    "key": "newOrderForm",
+    "title": "New Order",
+    "fullScreen": true,
+    "showCloseButton": true,
+    "dialogActions": [
+      { "label": "Cancel", "variant": "text", "color": "inherit", "code": "closeDialog('newOrderForm')" },
+      { "label": "Submit", "variant": "contained", "color": "primary", "code": "submitForm(); closeDialog('newOrderForm')" }
+    ]
+  },
+  "children": []
+}
+```

package/training/32-breadcrumb.md

@@ -0,0 +1,121 @@
+# Component: breadcrumb
+
+A navigation trail or step indicator. Two visual modes: classic breadcrumb links, or a chevron-style step progress bar.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. |
+| `items` | expression | Array of items: `[{ label, href?, disabled? }]`. Last item = current page in breadcrumb mode. |
+| `variant` | select | `breadcrumb` — classic path trail with separator. `chevron` — arrow/step progress bar. |
+| `mode` | select | `link` — items use `href` for navigation. `click` — items call `onClick` code. `none` — display only. |
+| `separator` | expression | Separator character/string for breadcrumb variant, e.g. `"/"`, `">"`. Default: `"/"`. |
+| `maxItems` | number | Maximum items shown before collapsing with an ellipsis (breadcrumb variant). |
+| `linkUnderline` | select | `hover` · `always` · `none` — Link underline behavior. |
+| `currentColor` | select | `text.primary` · `primary.main` · `text.secondary` · `inherit` — Color of the current (last) item. |
+| `activeIndex` | expression | Active step index (chevron variant). Drives which step is highlighted. |
+| `itemSize` | select | `small` · `medium` · `large` — Size of each step (chevron variant). |
+| `fullWidth` | boolean | Chevron steps stretch to fill the full width. |
+| `completedColor` | text | Background color of completed steps (chevron variant), e.g. `"#4caf50"`. |
+| `activeColor` | text | Background color of the active step, e.g. `"#1976d2"`. |
+| `pendingColor` | text | Background color of pending steps, e.g. `"#e0e0e0"`. |
+| `completedTextColor` | text | Text color of completed steps. |
+| `activeTextColor` | text | Text color of the active step. |
+| `pendingTextColor` | text | Text color of pending steps. |
+| `onClick` | code | Code run when an item is clicked (mode: click). Available: `item`, `index`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No dedicated action tab. Click behavior via `onClick` code in Main.
+
+---
+
+## Use Cases
+
+**When to use (breadcrumb variant):**
+- Navigation trail showing the user's location in an app hierarchy.
+- "Home > Category > Subcategory > Item" trails in detail pages.
+
+**When to use (chevron variant):**
+- Visual progress indicator for a multi-step process without built-in navigation.
+- Status display: "Submitted → Under Review → Approved → Completed".
+- Non-interactive pipeline status viewer.
+
+**When NOT to use:**
+- Interactive multi-step navigation with form fields per step → use `wizard`.
+- Tab switching → use `menu`.
+
+---
+
+## Schema Examples
+
+### Classic breadcrumb (link mode)
+```json
+{
+  "type": "breadcrumb",
+  "props": {
+    "key": "navBreadcrumb",
+    "variant": "breadcrumb",
+    "mode": "link",
+    "items": [
+      { "label": "Home", "href": "/" },
+      { "label": "Employees", "href": "/employees" },
+      { "label": "data.employee.name" }
+    ],
+    "separator": "/",
+    "linkUnderline": "hover",
+    "currentColor": "text.primary"
+  }
+}
+```
+
+### Chevron status bar (display only)
+```json
+{
+  "type": "breadcrumb",
+  "props": {
+    "key": "orderStatus",
+    "variant": "chevron",
+    "mode": "none",
+    "items": [
+      { "label": "Order Placed" },
+      { "label": "Processing" },
+      { "label": "Shipped" },
+      { "label": "Delivered" }
+    ],
+    "activeIndex": "data.order.statusIndex",
+    "fullWidth": true,
+    "completedColor": "#4caf50",
+    "activeColor": "#1976d2",
+    "pendingColor": "#e0e0e0",
+    "completedTextColor": "#ffffff",
+    "activeTextColor": "#ffffff",
+    "pendingTextColor": "#9e9e9e"
+  }
+}
+```
+
+### Clickable breadcrumb
+```json
+{
+  "type": "breadcrumb",
+  "props": {
+    "key": "folderNav",
+    "variant": "breadcrumb",
+    "mode": "click",
+    "items": "data.folderPath",
+    "onClick": "setData({ currentFolder: item.id }); loadFolder(item.id)"
+  }
+}
+```