robobyte-front-builder 1.0.26 → 1.0.28

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)"
+  }
+}
+```

package/training/33-dataGrid.md

@@ -0,0 +1,129 @@
+# Component: dataGrid
+
+An AG Grid-powered editable data table. Supports inline editing, row actions, column configuration, add/delete rows, row selection, and pagination. Primarily used for editable grid forms (not just read-only display).
+
+> ⚠️ Use `dataGrid` for **editable forms** with tabular data (line items, bulk editing). For read-only data display use `reportViewer`. For simple static tables use `dataTableViewer`.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Grid data is accessible at `data[key]`. |
+| `dataKey` | expression | Data key pointing to the rows array, e.g. `data.invoiceLines`. |
+| `columns` | expression | Column definitions array (AG Grid colDef format), e.g. `[{ headerName: 'Name', field: 'name' }]`. |
+| `extraCols` | extra-cols-editor | Additional columns defined via the visual editor. Each entry is a full AG Grid colDef object. Useful for computed columns or action columns. |
+| `columnsConfig` | columns-config-editor | Per-field overrides applied to existing columns (matched by field name). E.g. make a field editable, add a custom valueGetter. |
+| `actionsConfig` | actions-config-editor | Row action buttons shown in a popover "Actions" cell. Each action has: `label`, `color`, `variant`, `icon`, `code`, `confirmation?`, `disabled?`. Inside action code, `data.row` is the AG Grid row node. |
+| `addLabel` | expression | Label for the "Add Row" button, e.g. `"+ Add Line"`. |
+| `addRow` | code | Code returning the template object for a new row. E.g. `return { id: uuid(), qty: 1, price: 0 }`. |
+| `readOnly` | expression | Expression that when `true` disables all editing. |
+| `showAddBtn` | boolean | Shows/hides the Add Row button. |
+| `showDeleteCol` | boolean | Shows/hides the delete (×) column on each row. |
+| `height` | expression | Grid height, e.g. `"400px"`, `"60vh"`. |
+| `rowSelection` | select | `none` · `single` · `multiple` — Enables row selection mode. |
+| `pagination` | boolean | Enables pagination controls. |
+| `pageSize` | number | Rows per page when pagination is enabled. Default: `20`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control via parent layout-cell.
+
+---
+
+## Props — Actions Tab
+
+No dedicated action tab. Row actions are defined in `actionsConfig`.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Invoice line items: editable rows with qty, price, description.
+- Bulk data entry: import-like screens with many rows to fill.
+- Editable configuration tables.
+- Any tabular form where users add/edit/delete rows.
+
+**When NOT to use:**
+- Read-only server-fetched data displays → use `reportViewer`.
+- Simple static tables without editing → use `dataTableViewer`.
+- Single record forms → use individual form fields.
+
+---
+
+## Schema Examples
+
+### Editable invoice lines
+```json
+{
+  "type": "dataGrid",
+  "props": {
+    "key": "invoiceLines",
+    "dataKey": "data.lines",
+    "columns": "[{ headerName: 'Description', field: 'description', editable: true }, { headerName: 'Qty', field: 'qty', editable: true, width: 100 }, { headerName: 'Price', field: 'price', editable: true, width: 120 }]",
+    "showAddBtn": true,
+    "showDeleteCol": true,
+    "addLabel": "+ Add Line",
+    "addRow": "return { id: Date.now(), description: '', qty: 1, price: 0 }",
+    "height": "350px"
+  }
+}
+```
+
+### Read-only grid with row actions
+```json
+{
+  "type": "dataGrid",
+  "props": {
+    "key": "employeeTable",
+    "dataKey": "data.employees",
+    "columns": "data.employeeColumns",
+    "readOnly": true,
+    "showAddBtn": false,
+    "showDeleteCol": false,
+    "rowSelection": "single",
+    "pagination": true,
+    "pageSize": 25,
+    "height": "500px",
+    "actionsConfig": [
+      {
+        "label": "Edit",
+        "color": "primary",
+        "variant": "text",
+        "icon": "EditOutlined",
+        "code": "setData({ selectedEmployee: data.row.data }); openDialog('editEmployee')"
+      },
+      {
+        "label": "Delete",
+        "color": "error",
+        "variant": "text",
+        "icon": "DeleteOutlined",
+        "confirmation": "Are you sure you want to delete this employee?",
+        "code": "deleteEmployee({ id: data.row.data.id })"
+      }
+    ]
+  }
+}
+```
+
+### Multi-select with pagination
+```json
+{
+  "type": "dataGrid",
+  "props": {
+    "key": "orderItems",
+    "dataKey": "data.orders",
+    "columns": "data.orderColumns",
+    "rowSelection": "multiple",
+    "pagination": true,
+    "pageSize": 50,
+    "height": "600px",
+    "showAddBtn": false,
+    "showDeleteCol": false
+  }
+}
+```

package/training/34-dataTableViewer.md

@@ -0,0 +1,115 @@
+# Component: dataTableViewer
+
+A simple read-only HTML table for displaying data arrays. Fully styleable (header, cell, row, border). No editing, no sorting, no pagination.
+
+> ⚠️ Use this for **simple display tables** where the data is already loaded in `data`. For server-fetched paginated data use `reportViewer`. For editable rows use `dataGrid`.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `dataKey` | expression | Key in page data pointing to the rows array, e.g. `"summaryRows"`. |
+| `columns` | table-columns-editor | Column definitions: `[{ label: 'Column Header', field: 'rowProperty' }]`. `label` = header text, `field` = property key on each row object. |
+| `testData` | expression | JSON array of sample rows used when `data[dataKey]` is empty (preview/edit mode), e.g. `[{ name: "Alice", amount: 100 }]`. |
+| `tableWidth` | expression | Overall table width, e.g. `"100%"` or `"800px"`. |
+| `showHeader` | boolean | Show/hide the header row. Default: `true`. |
+| `headerBgColor` | expression | Header row background color, e.g. `"#1976d2"` or `"primary.main"`. |
+| `headerTextColor` | expression | Header text color. |
+| `headerFontSize` | expression | Header font size in px, e.g. `"14"`. |
+| `headerAlign` | select | `left` · `center` · `right` — Header text alignment. |
+| `headerPaddingH` | expression | Header horizontal padding in px. |
+| `headerPaddingV` | expression | Header vertical padding in px. |
+| `fontSize` | expression | Cell font size in px. |
+| `cellTextColor` | expression | Cell text color. |
+| `cellAlign` | select | `left` · `center` · `right` — Cell text alignment. |
+| `cellPaddingH` | expression | Cell horizontal padding in px. |
+| `cellPaddingV` | expression | Cell vertical padding in px. |
+| `cellVerticalAlign` | select | `top` · `middle` · `bottom` — Vertical alignment of cell content. |
+| `striped` | boolean | Alternating row background colors. |
+| `stripedColor` | expression | Color used for alternating rows, e.g. `"#f5f5f5"`. |
+| `rowHover` | boolean | Highlights rows on mouse hover. |
+| `rowHoverColor` | expression | Hover background color. |
+| `bordered` | boolean | Adds cell borders. |
+| `borderColor` | expression | Border color, e.g. `"#e0e0e0"`. |
+| `borderWidth` | expression | Border thickness in px, e.g. `"1"`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Use parent layout-cell.
+
+---
+
+## Props — Actions Tab
+
+No actions. Table is read-only.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Display a summary table from data already available in `data`.
+- Read-only reference tables (pricing tiers, feature comparison).
+- Report sections inside a dashboard.
+- Print-ready data tables.
+
+**When NOT to use:**
+- Editable rows → use `dataGrid`.
+- Server-fetched paginated data → use `reportViewer`.
+- Large datasets needing sorting/filtering → use `reportViewer`.
+
+---
+
+## Schema Examples
+
+### Basic data table
+```json
+{
+  "type": "dataTableViewer",
+  "props": {
+    "dataKey": "summaryData",
+    "columns": [
+      { "label": "Name", "field": "name" },
+      { "label": "Department", "field": "department" },
+      { "label": "Salary", "field": "salary" }
+    ],
+    "showHeader": true,
+    "tableWidth": "100%",
+    "headerBgColor": "#1976d2",
+    "headerTextColor": "#ffffff",
+    "striped": true,
+    "stripedColor": "#f5f5f5",
+    "rowHover": true
+  }
+}
+```
+
+### Styled bordered table
+```json
+{
+  "type": "dataTableViewer",
+  "props": {
+    "dataKey": "pricingTiers",
+    "columns": [
+      { "label": "Plan", "field": "plan" },
+      { "label": "Price", "field": "price" },
+      { "label": "Users", "field": "maxUsers" },
+      { "label": "Storage", "field": "storage" }
+    ],
+    "tableWidth": "100%",
+    "headerBgColor": "#263238",
+    "headerTextColor": "#ffffff",
+    "headerAlign": "center",
+    "cellAlign": "center",
+    "bordered": true,
+    "borderColor": "#cfd8dc",
+    "borderWidth": "1",
+    "cellPaddingH": "12",
+    "cellPaddingV": "10"
+  }
+}
+```