robobyte-front-builder 1.0.25 → 1.0.27

package/training/36-viewRenderer.md

@@ -0,0 +1,110 @@
+# Component: viewRenderer
+
+Embeds another saved view (by ID) inside the current page. Supports isolated data state, data seeding, refresh triggers, and height control.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Optional identifier. |
+| `viewId` | expression | **Required.** Numeric ID of the view to embed, e.g. `data.selectedViewId` or `"42"`. |
+| `refreshKey` | expression | When this expression's value changes, the child view is re-fetched and remounted. Use a counter or a reactive data value. |
+| `initialData` | expression | Object merged into the child view's data state on first load (and on each `refreshKey` change). One-time seed. E.g. `{ userId: data.user.id, mode: 'edit' }`. |
+| `externalData` | expression | Object pushed into the child view on every parent re-render. Reactive — child always sees the latest value. E.g. `{ selectedRow: data.selectedRow }`. |
+| `isolated` | boolean | `true` (default) — child has its own independent data/form stores. `false` — child shares the parent page's `data`/`setData`/`form`. |
+| `heightMode` | select | `auto` — wraps content height. `full` — fills parent flex container. `fixed` — exact pixel height, content scrolls. |
+| `height` | number | Exact height in pixels when `heightMode: fixed`. |
+| `minHeight` | number | Minimum height floor in pixels when `heightMode: auto`. |
+| `title` | expression | Optional title label shown above the embedded view. |
+| `showBorder` | boolean | Shows a border around the embedded view container. |
+| `showRefresh` | boolean | Shows a refresh button in the container header. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Embedding a complex sub-form that is maintained as a separate view.
+- Master-detail layouts: a table on top, an embedded detail view below.
+- Dynamically swapping which view is shown based on selection (`viewId: data.selectedViewId`).
+- Modular dashboards where each panel is a standalone view.
+- Sharing a sub-form across multiple parent pages.
+
+**When NOT to use:**
+- Simple inline content → just drop components directly.
+- Dialog body → use `dialog`'s `viewId` prop instead.
+- Static content → no need for a separate view.
+
+---
+
+## Schema Examples
+
+### Embedding a static view
+```json
+{
+  "type": "viewRenderer",
+  "props": {
+    "key": "userDetails",
+    "viewId": "45",
+    "heightMode": "auto",
+    "showBorder": true
+  }
+}
+```
+
+### Master-detail: embed detail view for selected row
+```json
+{
+  "type": "viewRenderer",
+  "props": {
+    "key": "detailPanel",
+    "viewId": "data.detailViewId",
+    "externalData": "{ selectedId: data.selectedEmployeeId }",
+    "refreshKey": "data.selectedEmployeeId",
+    "heightMode": "fixed",
+    "height": 400,
+    "isolated": true
+  }
+}
+```
+
+### Sub-form sharing parent state
+```json
+{
+  "type": "viewRenderer",
+  "props": {
+    "key": "addressForm",
+    "viewId": "12",
+    "isolated": false,
+    "heightMode": "auto"
+  }
+}
+```
+
+### Dynamic view switching
+```json
+{
+  "type": "viewRenderer",
+  "props": {
+    "key": "dynamicContent",
+    "viewId": "data.activeViewId",
+    "refreshKey": "data.activeViewId",
+    "heightMode": "full",
+    "showRefresh": true
+  }
+}
+```

package/training/37-treeView.md

@@ -0,0 +1,170 @@
+# Component: treeView
+
+A hierarchical tree component. Accepts flat (parentId-linked) or nested (children arrays) data — auto-detected. Supports lazy loading, selection, checkboxes, search, icons, and row actions.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `dataKey` | expression | Key in page data pointing to the tree array. E.g. `"orgTree"` or `"data.departments"`. |
+| `idField` | expression | Property on each node used as its unique ID, e.g. `"id"`. |
+| `labelField` | expression | Property used as the display text for each node, e.g. `"name"`. |
+| `childrenField` | expression | Property that holds nested children (for nested arrays), e.g. `"children"`. |
+| `parentIdField` | expression | Property linking nodes to their parent (for flat arrays), e.g. `"parentId"`. |
+
+### Lazy Loading
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `hasChildrenField` | expression | Boolean flag property on each node indicating it has children to be loaded, e.g. `"hasChildren"`. When a node with this flag is expanded, `onExpandCode` runs. |
+| `onExpandCode` | code (action) | Runs when an expandable node is opened. Fetch children here and call `setData({ [dataKey]: updatedTree })`. |
+
+### Selection
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `selectedKey` | expression | Data key where selected node(s) are written, e.g. `"selectedNode"`. |
+| `selectable` | boolean | Enables node selection on click. |
+| `multiSelect` | boolean | Allows selecting multiple nodes. |
+| `checkboxSelection` | boolean | Shows checkboxes on each node for selection. |
+| `onSelectCode` | code (action) | Runs when a node is selected/deselected. Available: the selected node(s). |
+
+### Icons
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `iconField` | expression | Property on each node containing a MUI icon name, e.g. `"iconName"`. |
+| `defaultIcon` | expression | Fallback MUI icon name for all nodes, e.g. `"FolderOutlined"`. |
+| `leafIcon` | expression | Icon for leaf nodes (no children), e.g. `"InsertDriveFileOutlined"`. |
+
+### Expand Behavior
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `expandAll` | boolean | Expands all nodes on initial render. |
+| `defaultExpanded` | expression | Array of node IDs to expand by default. |
+
+### Search
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `showSearch` | boolean | Shows a search box above the tree. |
+| `searchPlaceholder` | expression | Placeholder text in the search box. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `dense` | boolean | Reduces node spacing for compact trees. |
+| `showLines` | boolean | Draws vertical connector lines between nodes. |
+| `showCount` | boolean | Shows a count badge next to each node with children. |
+| `indent` | expression | Indentation per level in px, e.g. `"20"`. |
+| `height` | expression | Tree container height, e.g. `"400px"`. |
+| `fontSize` | expression | Node label font size. |
+| `nodeColor` | expression | Default node text color. |
+| `selectedBg` | expression | Background color of selected nodes. |
+| `selectedColor` | expression | Text color of selected nodes. |
+| `hoverBg` | expression | Background color on hover. |
+| `borderRadius` | expression | Border radius of node rows. |
+| `actionsConfig` | actions-config-editor | Action buttons shown in a popover on each node. Inside action code, `data.row` is the node object. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No dedicated action tab. Use `onSelectCode`, `onExpandCode`, and `actionsConfig` in Main.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Organizational hierarchy browsers.
+- File/folder tree navigation.
+- Category trees for content management.
+- Permission/role hierarchies with checkbox selection.
+- Lazy-loading large trees (load children on expand).
+
+**When NOT to use:**
+- Flat lists → use `reportViewer` or `dataGrid`.
+- Only 2 levels deep → consider `dropdown` with grouping.
+- Non-hierarchical data → use a list component.
+
+---
+
+## Schema Examples
+
+### Basic tree from nested data
+```json
+{
+  "type": "treeView",
+  "props": {
+    "dataKey": "orgChart",
+    "idField": "id",
+    "labelField": "name",
+    "childrenField": "children",
+    "selectable": true,
+    "selectedKey": "selectedNode",
+    "defaultIcon": "PersonOutlined",
+    "leafIcon": "PersonOutlined",
+    "showSearch": true,
+    "height": "400px"
+  }
+}
+```
+
+### Flat tree with parentId
+```json
+{
+  "type": "treeView",
+  "props": {
+    "dataKey": "categories",
+    "idField": "id",
+    "labelField": "title",
+    "parentIdField": "parentId",
+    "selectable": true,
+    "selectedKey": "selectedCategoryId",
+    "showLines": true,
+    "dense": true,
+    "height": "350px"
+  }
+}
+```
+
+### Lazy loading tree
+```json
+{
+  "type": "treeView",
+  "props": {
+    "dataKey": "fileTree",
+    "idField": "id",
+    "labelField": "name",
+    "childrenField": "children",
+    "hasChildrenField": "hasChildren",
+    "onExpandCode": "loadChildren({ nodeId: data.node.id })",
+    "defaultIcon": "FolderOutlined",
+    "leafIcon": "InsertDriveFileOutlined",
+    "height": "500px"
+  }
+}
+```
+
+### Multi-select with checkboxes
+```json
+{
+  "type": "treeView",
+  "props": {
+    "dataKey": "permissionsTree",
+    "idField": "permId",
+    "labelField": "permName",
+    "childrenField": "children",
+    "checkboxSelection": true,
+    "multiSelect": true,
+    "selectedKey": "selectedPermissions",
+    "expandAll": true
+  }
+}
+```

package/training/38-kpi-metric.md

@@ -0,0 +1,148 @@
+# Component: kpi-metric
+
+Displays a single numeric KPI value with label, sub-label, formatting, and conditional threshold colors. The most commonly used KPI component.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression returning the numeric value. Modes: string key (`"revenue"` → uses `data["revenue"]`) or direct expression (`data.price * data.qty`). |
+| `label` | expression | Primary label shown above or below the value. |
+| `sublabel` | expression | Secondary label shown below the label. |
+
+### Format
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `format` | select | `number` · `currency` · `percent` · `compact` · `bytes` · `duration` |
+| `decimals` | expression | Decimal places, e.g. `2`. |
+| `prefix` | expression | Text/symbol before the value, e.g. `"$"`. |
+| `suffix` | expression | Text/symbol after the value, e.g. `" units"`. |
+| `currency` | expression | ISO currency code for `currency` format, e.g. `"USD"`, `"EUR"`. |
+| `asRatio` | boolean | When `true`, treats percent values as 0–1 ratios (multiplies by 100 for display). |
+
+### Value Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `fontSize` | expression | Value font size, e.g. `"36px"`, `"2rem"`. |
+| `fontWeight` | select | `400` · `500` · `600` · `700` · `800` · `900` |
+| `align` | select | `left` · `center` · `right` |
+| `labelPosition` | select | `above` · `below` — Whether the label appears above or below the value. |
+
+### Label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelFontSize` | expression | Label text size. |
+| `labelFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` |
+| `labelColor` | expression | Label color, e.g. `"text.secondary"` or `"#555"`. |
+
+### Sub-label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `sublabelFontSize` | expression | Sub-label font size. |
+| `sublabelFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` |
+| `sublabelColor` | expression | Sub-label color, e.g. `"text.disabled"` or `"#999"`. |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Rules mapping value ranges to colors. E.g. `< 50 → error.main`, `>= 50 → success.main`. |
+
+### Actions
+| Prop | Type | Notes |
+|------|------|-------|
+| `onClick` | kpi-action | Fires when the metric is clicked. Available in action code: `clickedValue`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Dashboard KPI cards: revenue, orders, users, growth.
+- Summary statistics in reports.
+- Any single important numeric value that needs emphasis.
+- Metrics with conditional color based on value (green when positive, red when negative).
+
+**When NOT to use:**
+- Trend/change values → use `kpi-trend`.
+- Progress toward a goal → use `kpi-gauge` or `kpi-bullet`.
+- Status labels → use `kpi-badge`.
+
+---
+
+## Schema Examples
+
+### Revenue KPI
+```json
+{
+  "type": "kpi-metric",
+  "props": {
+    "valueKey": "data.totalRevenue",
+    "label": "Total Revenue",
+    "format": "currency",
+    "currency": "USD",
+    "decimals": 0,
+    "fontSize": "32px",
+    "fontWeight": "700",
+    "align": "center",
+    "labelPosition": "below",
+    "labelColor": "text.secondary"
+  }
+}
+```
+
+### Percentage with thresholds
+```json
+{
+  "type": "kpi-metric",
+  "props": {
+    "valueKey": "data.errorRate",
+    "label": "Error Rate",
+    "format": "percent",
+    "decimals": 1,
+    "asRatio": true,
+    "align": "center",
+    "thresholds": [
+      { "operator": "<", "value": 0.05, "color": "success.main" },
+      { "operator": "<", "value": 0.1, "color": "warning.main" },
+      { "operator": ">=", "value": 0.1, "color": "error.main" }
+    ]
+  }
+}
+```
+
+### Compact large number
+```json
+{
+  "type": "kpi-metric",
+  "props": {
+    "valueKey": "data.totalUsers",
+    "label": "Users",
+    "sublabel": "Active this month",
+    "format": "compact",
+    "align": "center",
+    "fontSize": "28px",
+    "fontWeight": "600",
+    "sublabelColor": "text.disabled"
+  }
+}
+```
+
+### Clickable metric
+```json
+{
+  "type": "kpi-metric",
+  "props": {
+    "valueKey": "data.pendingOrders",
+    "label": "Pending Orders",
+    "format": "number",
+    "align": "center",
+    "onClick": {
+      "type": "custom",
+      "code": "setData({ filterStatus: 'pending' }); navigateTo('/orders')"
+    }
+  }
+}
+```

package/training/39-kpi-trend.md

@@ -0,0 +1,105 @@
+# Component: kpi-trend
+
+Displays a delta/change value with directional icon and color. Shows positive/negative trends with up/down arrows.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression returning the delta value (positive = up, negative = down). E.g. `"revenueDelta"` → `data.revenueDelta`. |
+| `label` | expression | Context label shown alongside the trend, e.g. `"vs last month"`. |
+
+### Format
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `isPercent` | boolean | `true` if the value is a percentage change (appends `%`). |
+| `decimals` | expression | Decimal places for the displayed value. |
+| `invertColors` | boolean | `true` inverts the color logic — down becomes good (green), up becomes bad (red). Useful for cost/expense metrics. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `variant` | select | `chip` — pill-shaped chip with icon. `text` — plain text with icon. `inline` — compact inline display. |
+| `size` | select | `small` · `medium` · `large` |
+| `showIcon` | boolean | Shows the up/down arrow icon. Default: `true`. |
+| `align` | select | `left` · `center` · `right` |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Paired with `kpi-metric` to show the change alongside the current value.
+- Revenue vs last month, users vs last week, etc.
+- Any delta that needs directional context (up/down) and color (green/red).
+
+**When NOT to use:**
+- Absolute values (not deltas) → use `kpi-metric`.
+- Percentage of a total → use `kpi-metric` with percent format.
+- Progress toward goal → use `kpi-gauge` or `kpi-bullet`.
+
+---
+
+## Schema Examples
+
+### Revenue change chip
+```json
+{
+  "type": "kpi-trend",
+  "props": {
+    "valueKey": "data.revenueGrowth",
+    "label": "vs last month",
+    "isPercent": true,
+    "decimals": 1,
+    "variant": "chip",
+    "size": "medium",
+    "showIcon": true,
+    "align": "center"
+  }
+}
+```
+
+### Inverted (cost reduction is good)
+```json
+{
+  "type": "kpi-trend",
+  "props": {
+    "valueKey": "data.costDelta",
+    "label": "cost change",
+    "isPercent": true,
+    "decimals": 1,
+    "invertColors": true,
+    "variant": "text",
+    "align": "left"
+  }
+}
+```
+
+### Inline compact trend
+```json
+{
+  "type": "kpi-trend",
+  "props": {
+    "valueKey": "data.userGrowth",
+    "isPercent": true,
+    "variant": "inline",
+    "size": "small",
+    "decimals": 0
+  }
+}
+```

package/training/40-kpi-badge.md

@@ -0,0 +1,112 @@
+# Component: kpi-badge
+
+A colored status badge/chip. Displays a value (text or number) as a colored pill. Threshold rules map values to colors.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression for the displayed value. String or number. E.g. `"status"` → `data.status`. |
+| `label` | expression | Static text override. Leave blank to display the raw value from `valueKey`. If set, shows this text instead of the value (color still driven by value through thresholds). |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `variant` | select | `soft` — light tinted background. `outlined` — border with no fill. `filled` — solid colored background. |
+| `size` | select | `small` · `medium` · `large` |
+| `dot` | boolean | Shows a small colored dot before the label text. |
+| `align` | select | `left` · `center` · `right` |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Rules mapping values to colors. String matching: `"== active"` → `success.main`. Numeric: `"> 80"` → `warning.main`. Threshold `label` field overrides the displayed text per rule. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Status displays: Active/Inactive/Pending, Open/Closed/Resolved.
+- Priority badges: Low/Medium/High/Critical.
+- Category or type labels in tables and cards.
+- Any value that maps cleanly to a color: green = good, red = bad, yellow = warning.
+
+**When NOT to use:**
+- Numeric metrics → use `kpi-metric`.
+- Progress → use `kpi-gauge` or `kpi-bullet`.
+- On/off dot only → use `kpi-status-dot`.
+
+---
+
+## Schema Examples
+
+### Status badge with thresholds
+```json
+{
+  "type": "kpi-badge",
+  "props": {
+    "valueKey": "data.record.status",
+    "variant": "soft",
+    "size": "medium",
+    "dot": true,
+    "align": "center",
+    "thresholds": [
+      { "operator": "==", "value": "active", "color": "success.main", "label": "Active" },
+      { "operator": "==", "value": "inactive", "color": "error.main", "label": "Inactive" },
+      { "operator": "==", "value": "pending", "color": "warning.main", "label": "Pending" }
+    ]
+  }
+}
+```
+
+### Priority badge (filled)
+```json
+{
+  "type": "kpi-badge",
+  "props": {
+    "valueKey": "data.task.priority",
+    "variant": "filled",
+    "size": "small",
+    "thresholds": [
+      { "operator": "==", "value": "critical", "color": "#d32f2f", "label": "CRITICAL" },
+      { "operator": "==", "value": "high", "color": "#f57c00", "label": "HIGH" },
+      { "operator": "==", "value": "medium", "color": "#1976d2", "label": "MEDIUM" },
+      { "operator": "==", "value": "low", "color": "#388e3c", "label": "LOW" }
+    ]
+  }
+}
+```
+
+### Outlined numeric badge
+```json
+{
+  "type": "kpi-badge",
+  "props": {
+    "valueKey": "data.score",
+    "label": "",
+    "variant": "outlined",
+    "size": "medium",
+    "thresholds": [
+      { "operator": ">=", "value": 80, "color": "success.main" },
+      { "operator": ">=", "value": 50, "color": "warning.main" },
+      { "operator": "<", "value": 50, "color": "error.main" }
+    ]
+  }
+}
+```