robobyte-front-builder 1.0.25 → 1.0.27

package/training/41-kpi-statusDot.md

@@ -0,0 +1,118 @@
+# Component: kpi-statusDot
+
+A small colored circle indicating status. Thresholds map values to dot colors. Optionally shows a pulse animation and a label.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression for the status value. E.g. `"serverStatus"` → `data.serverStatus`. |
+| `label` | expression | Static label displayed alongside the dot. Leave blank for dot-only. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `size` | expression | Dot diameter in px, e.g. `"12"`, `"16"`. |
+| `pulse` | boolean | `true` adds a pulsing glow animation (useful for "live" status indicators). |
+| `showLabel` | boolean | Shows the `label` text alongside the dot. |
+| `labelPosition` | select | `right` · `left` · `above` · `below` — Position of the label relative to the dot. |
+| `align` | select | `left` · `center` · `right` |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Rules mapping values to dot colors. E.g. `"== online"` → `success.main`, `"== offline"` → `error.main`. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Server/service status indicators (online/offline).
+- Connection health: active, degraded, down.
+- User presence: available, busy, away.
+- Any binary or categorical status that maps to a color.
+- Combined with text labels to show status inline.
+
+**When NOT to use:**
+- Complex status with multiple text states → use `kpi-badge`.
+- Numeric progress → use `kpi-gauge`.
+- Full status line with detailed info → use `kpi-badge` with `filled` variant.
+
+---
+
+## Schema Examples
+
+### Server status dot with pulse
+```json
+{
+  "type": "kpi-statusDot",
+  "props": {
+    "valueKey": "data.server.status",
+    "label": "API Status",
+    "showLabel": true,
+    "labelPosition": "right",
+    "size": "12",
+    "pulse": true,
+    "align": "left",
+    "thresholds": [
+      { "operator": "==", "value": "online", "color": "success.main" },
+      { "operator": "==", "value": "degraded", "color": "warning.main" },
+      { "operator": "==", "value": "offline", "color": "error.main" }
+    ]
+  }
+}
+```
+
+### User presence indicator (dot only)
+```json
+{
+  "type": "kpi-statusDot",
+  "props": {
+    "valueKey": "data.user.presence",
+    "size": "10",
+    "pulse": false,
+    "showLabel": false,
+    "thresholds": [
+      { "operator": "==", "value": "available", "color": "#4caf50" },
+      { "operator": "==", "value": "busy", "color": "#f44336" },
+      { "operator": "==", "value": "away", "color": "#ff9800" }
+    ]
+  }
+}
+```
+
+### Label above dot
+```json
+{
+  "type": "kpi-statusDot",
+  "props": {
+    "valueKey": "data.paymentStatus",
+    "label": "Payment",
+    "showLabel": true,
+    "labelPosition": "above",
+    "size": "14",
+    "align": "center",
+    "thresholds": [
+      { "operator": "==", "value": "paid", "color": "success.main" },
+      { "operator": "==", "value": "overdue", "color": "error.main" },
+      { "operator": "==", "value": "pending", "color": "warning.main" }
+    ]
+  }
+}
+```

package/training/42-kpi-iconBox.md

@@ -0,0 +1,114 @@
+# Component: kpi-iconBox
+
+A boxed icon widget. Useful as a visual accent in KPI cards or to show category/status with a large icon. Color driven by thresholds.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Optional. Data key for threshold-based color changes. The icon itself stays fixed; only bg/color changes. E.g. `"errorCount"` → threshold `"> 0"` turns icon red. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `icon` | expression | MUI icon name to display, e.g. `"StarOutlined"`, `"TrendingUpOutlined"`, `"PeopleOutlined"`. |
+| `size` | expression | Box container size in px, e.g. `"48"`, `"64"`. |
+| `iconSize` | expression | Icon size in px (smaller than box size), e.g. `"28"`. |
+| `borderRadius` | expression | Box corner radius, e.g. `"8px"`, `"50%"` for circle. |
+| `iconColor` | expression | Icon color override. Overrides threshold color. E.g. `"#ffffff"`. |
+| `bgColor` | expression | Background color override. Overrides threshold bg. |
+| `shadow` | boolean | Adds a colored glow shadow matching the icon color. |
+| `align` | select | `left` · `center` · `right` |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Rules mapping `valueKey` to icon color + background. E.g. `"> 0"` → error color. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Visual accent in metric cards (large icon above/beside the metric value).
+- Category icons in navigation or summary panels.
+- Status visualization: a large warning icon when an alert is active.
+- Decorative icons in empty states or onboarding screens.
+
+**When NOT to use:**
+- Small inline icons → use prefix/suffix on `label` or `header`.
+- Interactive icon buttons → use `button` with `iconButton: true`.
+- Charts → use chart KPI components.
+
+---
+
+## Schema Examples
+
+### Static icon box (revenue card accent)
+```json
+{
+  "type": "kpi-iconBox",
+  "props": {
+    "icon": "AttachMoneyOutlined",
+    "size": "52",
+    "iconSize": "30",
+    "borderRadius": "12px",
+    "bgColor": "#e3f2fd",
+    "iconColor": "#1976d2",
+    "shadow": false,
+    "align": "center"
+  }
+}
+```
+
+### Threshold-driven alert icon
+```json
+{
+  "type": "kpi-iconBox",
+  "props": {
+    "valueKey": "data.errorCount",
+    "icon": "ErrorOutlineOutlined",
+    "size": "48",
+    "iconSize": "28",
+    "borderRadius": "50%",
+    "shadow": true,
+    "align": "center",
+    "thresholds": [
+      { "operator": "==", "value": 0, "color": "success.main", "bg": "#e8f5e9" },
+      { "operator": ">", "value": 0, "color": "error.main", "bg": "#ffebee" }
+    ]
+  }
+}
+```
+
+### Circle icon box
+```json
+{
+  "type": "kpi-iconBox",
+  "props": {
+    "icon": "PeopleOutlined",
+    "size": "60",
+    "iconSize": "32",
+    "borderRadius": "50%",
+    "bgColor": "#f3e5f5",
+    "iconColor": "#7b1fa2",
+    "shadow": true,
+    "align": "left"
+  }
+}
+```

package/training/43-kpi-gauge.md

@@ -0,0 +1,143 @@
+# Component: kpi-gauge
+
+A semicircular SVG gauge chart for displaying a value between a min and max. Supports needle mode, value label, threshold coloring, and sub-label.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression for the numeric value. E.g. `"cpuUsage"` → `data.cpuUsage`. |
+| `min` | expression | Minimum value of the gauge scale. E.g. `0`. |
+| `max` | expression | Maximum value of the gauge scale. E.g. `100`. |
+| `label` | expression | Label shown inside or below the gauge. |
+| `sublabel` | expression | Secondary label shown below the main label. |
+
+### Format
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `format` | select | `number` · `currency` · `percent` · `compact` · `bytes` · `duration` |
+| `decimals` | expression | Decimal places for displayed value. |
+| `prefix` | expression | Text before the value. |
+| `suffix` | expression | Text after the value, e.g. `"°C"`, `"%"`. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `size` | expression | Gauge SVG width in px, e.g. `"180"`. Height auto-scales. |
+| `strokeWidth` | expression | Arc stroke width in px, e.g. `"12"`. |
+| `color` | expression | Arc color when no threshold applies. E.g. `"primary.main"`. |
+| `trackColor` | expression | Background arc color, e.g. `"#e0e0e0"`. |
+| `showValue` | boolean | Shows the numeric value inside the gauge. |
+| `showMinMax` | boolean | Shows min/max labels at the arc ends. |
+| `needleMode` | boolean | Renders a needle pointer instead of a filled arc. |
+
+### Label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelFontSize` | expression | Font size of the center label. |
+| `labelFontWeight` | select | `normal` · `300` · `400` · `500` · `600` · `700` · `800` |
+| `labelColor` | expression | Label text color. |
+
+### 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 text color. |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Maps value ranges to arc colors. E.g. `< 50` → `success.main`, `< 75` → `warning.main`, `>= 75` → `error.main`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- CPU/memory usage visualization (0–100%).
+- Temperature, pressure, speed gauges.
+- Score or health indicator.
+- Any value between a known min and max that benefits from a visual dial.
+
+**When NOT to use:**
+- Simple numeric value → use `kpi-metric`.
+- Progress toward a goal with a target line → use `kpi-bullet`.
+- Horizontal progress → use `progress-line` or `kpi-bullet`.
+
+---
+
+## Schema Examples
+
+### CPU usage gauge
+```json
+{
+  "type": "kpi-gauge",
+  "props": {
+    "valueKey": "data.cpuUsage",
+    "min": 0,
+    "max": 100,
+    "label": "CPU Usage",
+    "format": "number",
+    "suffix": "%",
+    "size": "180",
+    "strokeWidth": "14",
+    "showValue": true,
+    "showMinMax": true,
+    "trackColor": "#e0e0e0",
+    "thresholds": [
+      { "operator": "<", "value": 60, "color": "#4caf50" },
+      { "operator": "<", "value": 80, "color": "#ff9800" },
+      { "operator": ">=", "value": 80, "color": "#f44336" }
+    ]
+  }
+}
+```
+
+### Temperature gauge with needle
+```json
+{
+  "type": "kpi-gauge",
+  "props": {
+    "valueKey": "data.temperature",
+    "min": 0,
+    "max": 50,
+    "label": "Temperature",
+    "sublabel": "°Celsius",
+    "format": "number",
+    "decimals": 1,
+    "size": "200",
+    "strokeWidth": "10",
+    "needleMode": true,
+    "showValue": true,
+    "color": "primary.main",
+    "trackColor": "#f5f5f5"
+  }
+}
+```
+
+### Satisfaction score
+```json
+{
+  "type": "kpi-gauge",
+  "props": {
+    "valueKey": "data.npsScore",
+    "min": 0,
+    "max": 10,
+    "label": "NPS Score",
+    "format": "number",
+    "decimals": 1,
+    "size": "160",
+    "strokeWidth": "12",
+    "showValue": true,
+    "thresholds": [
+      { "operator": "<", "value": 7, "color": "error.main" },
+      { "operator": "<", "value": 9, "color": "warning.main" },
+      { "operator": ">=", "value": 9, "color": "success.main" }
+    ]
+  }
+}
+```

package/training/44-kpi-bulletChart.md

@@ -0,0 +1,126 @@
+# Component: kpi-bulletChart
+
+A horizontal bullet chart showing an actual value vs a target, with an optional "good range" band. Based on Stephen Few's bullet graph design.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key for the actual (performance) value. E.g. `"revenue"`. |
+| `targetKey` | expression | Data key for the target/benchmark value. E.g. `"revenueTarget"`. |
+| `min` | expression | Scale minimum, e.g. `0`. |
+| `max` | expression | Scale maximum, e.g. `150000`. |
+| `label` | expression | Label shown to the left of the bar. |
+| `sublabel` | expression | Secondary label below the main label. |
+
+### Format
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `format` | select | `number` · `currency` · `percent` · `compact` |
+| `prefix` | expression | Text/symbol before values. |
+| `suffix` | expression | Text/symbol after values. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `height` | expression | Bar height in px, e.g. `"20"`, `"28"`. |
+| `colorSchema` | color-schema | Color palette for the actual bar. Overridden by threshold colors when they match. |
+| `actualColor` | expression | Explicit color for the actual value bar. Overrides color schema base color. |
+| `targetColor` | expression | Color of the target marker line, e.g. `"#333333"`. |
+| `trackColor` | expression | Background track color. Default: MUI `action.hover`. |
+| `goodColor` | expression | Color of the "good range" band. |
+| `goodFrom` | expression | Start of the good range (value or data expression). |
+| `goodTo` | expression | End of the good range. |
+| `showTarget` | boolean | Shows the vertical target marker line. Default: `true`. |
+| `showLabels` | boolean | Shows min/max value labels at the scale ends. |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Conditional bar colors based on actual value. |
+
+### Label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelFontSize` | expression | Font size of the label. |
+| `labelFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` |
+| `labelColor` | expression | Label text color. |
+
+### 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 text color. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Sales performance vs quota.
+- Budget actual vs budget target.
+- Any metric with an actual value compared to a reference target.
+- When you need to show "acceptable range" (goodFrom/goodTo) alongside the actual.
+
+**When NOT to use:**
+- Simple gauge without a target → use `kpi-gauge`.
+- Color-only visualization → use `kpi-color-scale`.
+- Just progress without a target → use `progress-line`.
+
+---
+
+## Schema Examples
+
+### Sales vs quota
+```json
+{
+  "type": "kpi-bulletChart",
+  "props": {
+    "valueKey": "data.salesActual",
+    "targetKey": "data.salesTarget",
+    "min": 0,
+    "max": 200000,
+    "label": "Sales",
+    "sublabel": "vs Target",
+    "format": "currency",
+    "prefix": "$",
+    "height": "24",
+    "showTarget": true,
+    "showLabels": true,
+    "targetColor": "#333333",
+    "goodFrom": 140000,
+    "goodTo": 180000,
+    "goodColor": "rgba(76,175,80,0.2)",
+    "thresholds": [
+      { "operator": ">=", "value": "data.salesTarget", "color": "success.main" },
+      { "operator": "<", "value": "data.salesTarget", "color": "warning.main" }
+    ]
+  }
+}
+```
+
+### Budget tracker (compact)
+```json
+{
+  "type": "kpi-bulletChart",
+  "props": {
+    "valueKey": "data.spent",
+    "targetKey": "data.budget",
+    "min": 0,
+    "max": "data.budget * 1.2",
+    "label": "Budget",
+    "format": "compact",
+    "height": "16",
+    "showTarget": true,
+    "thresholds": [
+      { "operator": "<=", "value": "data.budget * 0.8", "color": "success.main" },
+      { "operator": "<=", "value": "data.budget", "color": "warning.main" },
+      { "operator": ">", "value": "data.budget", "color": "error.main" }
+    ]
+  }
+}
+```

package/training/45-kpi-colorScale.md

@@ -0,0 +1,143 @@
+# Component: kpi-colorScale
+
+A horizontal color-scale bar that positions one or more value markers on a gradient or stepped color ramp. Visualizes where a value falls within a range.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key or expression for the primary marker value. E.g. `"riskScore"`. |
+| `min` | expression | Minimum of the scale range. |
+| `max` | expression | Maximum of the scale range. |
+| `label` | expression | Label shown below or beside the scale. |
+
+### Format
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `format` | select | `number` · `currency` · `percent` · `compact` |
+| `prefix` | expression | Prefix for marker label. |
+| `suffix` | expression | Suffix for marker label. |
+
+### Track Coloring
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `scaleMode` | select | `gradient` — smooth color ramp between color schema stops. `steps` — discrete colored zones based on thresholds. |
+| `colorSchema` | color-schema | Color palette defining the gradient stops or zone colors. |
+| `segments` | expression | Number of gradient stops in gradient mode. Default: `5`. |
+
+### Thresholds (Steps Mode)
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Define zone breakpoints. Each threshold value becomes a zone boundary. Threshold colors take priority over color schema in steps mode. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `height` | expression | Track bar height in px, e.g. `"20"`. |
+| `borderRadius` | expression | Track corner radius, e.g. `"4px"`. |
+| `showLabels` | boolean | Shows min/max value labels at the track ends. |
+
+### Label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelFontSize` | expression | Label font size. |
+| `labelFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` |
+| `labelColor` | expression | Label text color. |
+
+### Primary Marker
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `showMarker` | boolean | Shows the primary value marker (triangle/dot) on the scale. |
+| `markerColor` | expression | Marker color. Default: `"#333"`. |
+
+### Additional Markers
+| Prop | Type | Notes |
+|------|------|-------|
+| `markers` | markers-editor | Extra markers with their own `valueKey`, color, shape, and label. E.g. a "target" marker alongside the primary. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Risk scores, quality scores, health indices that fall on a color spectrum.
+- Temperature zones: cold/normal/hot.
+- Sentiment scores: negative/neutral/positive.
+- Visualizing where a value sits within color-coded ranges.
+- Comparing multiple values on the same scale (primary + additional markers).
+
+**When NOT to use:**
+- Progress toward a single target → use `kpi-bullet`.
+- Simple percentage → use `kpi-gauge` or `progress-line`.
+- Categorical status → use `kpi-badge`.
+
+---
+
+## Schema Examples
+
+### Gradient risk score
+```json
+{
+  "type": "kpi-colorScale",
+  "props": {
+    "valueKey": "data.riskScore",
+    "min": 0,
+    "max": 100,
+    "label": "Risk Score",
+    "format": "number",
+    "scaleMode": "gradient",
+    "colorSchema": "RdYlGn",
+    "height": "24",
+    "borderRadius": "4px",
+    "showLabels": true,
+    "showMarker": true,
+    "markerColor": "#333333"
+  }
+}
+```
+
+### Stepped zones with thresholds
+```json
+{
+  "type": "kpi-colorScale",
+  "props": {
+    "valueKey": "data.qualityScore",
+    "min": 0,
+    "max": 100,
+    "label": "Quality",
+    "format": "number",
+    "scaleMode": "steps",
+    "height": "20",
+    "showMarker": true,
+    "showLabels": true,
+    "thresholds": [
+      { "operator": "<", "value": 40, "color": "#f44336" },
+      { "operator": "<", "value": 70, "color": "#ff9800" },
+      { "operator": ">=", "value": 70, "color": "#4caf50" }
+    ]
+  }
+}
+```
+
+### With primary + target marker
+```json
+{
+  "type": "kpi-colorScale",
+  "props": {
+    "valueKey": "data.actual",
+    "min": 0,
+    "max": 200,
+    "label": "Performance",
+    "scaleMode": "gradient",
+    "height": "16",
+    "showMarker": true,
+    "markerColor": "#1976d2",
+    "markers": [
+      { "valueKey": "data.target", "color": "#d32f2f", "label": "Target" }
+    ]
+  }
+}
+```