robobyte-front-builder 1.0.26 → 1.0.28

package/training/19-link.md

@@ -0,0 +1,108 @@
+# Component: link
+
+A styled clickable hyperlink using MUI's Link component. Can navigate externally or trigger in-app navigation.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `text` | expression | Link display text, e.g. `"View Details"` or `data.label`. |
+| `href` | expression | Target URL, e.g. `"/users/data.id"` or `"https://example.com"`. |
+| `target` | select | `_self` — current tab. `_blank` — new tab. `_parent` · `_top` — frame contexts. |
+| `rel` | text | `rel` attribute for security, e.g. `"noopener noreferrer"` when using `_blank`. |
+| `variant` | select | Typography variant: `body1` · `body2` · `button` · `caption` · `h1` · `h2` · `h3` · `h4` · `h5` · `h6` |
+| `color` | select | `primary` · `secondary` · `error` · `warning` · `info` · `success` · `inherit` · `textPrimary` · `textSecondary` |
+| `underline` | select | `none` — never underlined. `hover` — underline on hover. `always` — always underlined. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Use parent layout-cell style for spacing.
+
+---
+
+## Props — Actions Tab
+
+No action events. Use `href` for navigation. For click-handler behavior use `button` instead.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Navigating to an external URL.
+- In-app navigation using a URL path.
+- Inline hyperlinks within text content.
+- "View more", "See details", "Download" type text links.
+
+**When NOT to use:**
+- Click triggers without navigation (open dialog, call API) → use `button`.
+- Navigation that requires passing state → use `button` with custom action.
+- Tab navigation → use `menu`.
+
+---
+
+## Schema Examples
+
+### External link opening in new tab
+```json
+{
+  "type": "link",
+  "props": {
+    "text": "Visit Website",
+    "href": "data.company.website",
+    "target": "_blank",
+    "rel": "noopener noreferrer",
+    "color": "primary",
+    "underline": "hover"
+  }
+}
+```
+
+### In-app navigation link
+```json
+{
+  "type": "link",
+  "props": {
+    "text": "View Profile",
+    "href": "'/users/' + data.user.id",
+    "target": "_self",
+    "color": "primary",
+    "variant": "body2",
+    "underline": "none"
+  }
+}
+```
+
+### Download link
+```json
+{
+  "type": "link",
+  "props": {
+    "text": "Download Report",
+    "href": "data.report.downloadUrl",
+    "target": "_blank",
+    "color": "secondary",
+    "variant": "button",
+    "underline": "hover"
+  }
+}
+```
+
+### Inline caption link
+```json
+{
+  "type": "link",
+  "props": {
+    "text": "Terms & Conditions",
+    "href": "/terms",
+    "target": "_blank",
+    "variant": "caption",
+    "color": "textSecondary",
+    "underline": "always"
+  }
+}
+```

package/training/20-banner.md

@@ -0,0 +1,122 @@
+# Component: banner
+
+An alert/notification banner (MUI Alert). Displays informational, success, warning, or error messages. Can be dismissed.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier, used to reference the banner's open state. |
+| `message` | expression | Primary message text shown in the banner. |
+| `title` | expression | Optional bold title above the message. |
+| `severity` | select | `info` · `success` · `warning` · `error` — Sets color scheme and default icon. |
+| `variant` | select | `standard` — colored text on light tinted background. `filled` — solid color background with white text. `outlined` — bordered with colored text. |
+| `open` | expression | Controlled visibility. Bind to `data.showBanner` to show/hide programmatically. Leave blank for the component to manage its own state. |
+| `dismissible` | boolean | Shows an × close button so the user can dismiss the banner. |
+| `icon` | boolean | `true` shows the default severity icon (info/check/warning/error). `false` hides it. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control wrapper through parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onClose` | action | Fires when the user clicks the dismiss (×) button. Use to reset `data.showBanner` or clear error state. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- System notifications: success after saving, errors from APIs.
+- Form-level validation errors (e.g. "Please fix the errors below").
+- Contextual information banners: "This record is in read-only mode".
+- Dismissible alerts that the user can close.
+
+**When NOT to use:**
+- Toast/snackbar messages (ephemeral, auto-dismiss) → handle via action code.
+- Single-field validation → use field-level error states.
+- Status indicators → use `kpi-badge` or `kpi-status-dot`.
+
+---
+
+## Schema Examples
+
+### Always-visible info banner
+```json
+{
+  "type": "banner",
+  "props": {
+    "message": "This form is in draft mode. Changes are not saved automatically.",
+    "severity": "info",
+    "variant": "standard",
+    "icon": true
+  }
+}
+```
+
+### Dismissible error banner controlled by data
+```json
+{
+  "type": "banner",
+  "props": {
+    "key": "errorBanner",
+    "title": "Error",
+    "message": "data.apiError",
+    "severity": "error",
+    "variant": "filled",
+    "open": "!!data.apiError",
+    "dismissible": true
+  },
+  "actions": {
+    "onClose": {
+      "type": "custom",
+      "code": "setData({ apiError: null })"
+    }
+  }
+}
+```
+
+### Success confirmation
+```json
+{
+  "type": "banner",
+  "props": {
+    "key": "successBanner",
+    "title": "Saved",
+    "message": "Your changes have been saved successfully.",
+    "severity": "success",
+    "variant": "outlined",
+    "open": "data.saved",
+    "dismissible": true
+  },
+  "actions": {
+    "onClose": {
+      "type": "custom",
+      "code": "setData({ saved: false })"
+    }
+  }
+}
+```
+
+### Warning about missing data
+```json
+{
+  "type": "banner",
+  "props": {
+    "message": "Some required fields are incomplete.",
+    "severity": "warning",
+    "variant": "standard",
+    "open": "data.hasValidationErrors",
+    "icon": true
+  }
+}
+```

package/training/21-progress-circle.md

@@ -0,0 +1,101 @@
+# Component: progress-circle
+
+A circular progress indicator. Determinate (shows a specific % value) or indeterminate (spinning animation).
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `value` | expression | Progress value from `0` to `100`. Only used when `variant: determinate`. Can be bound to data: `data.uploadProgress`. |
+| `variant` | select | `determinate` — fills arc based on `value`. `indeterminate` — continuous spinning animation. |
+| `color` | select | `primary` · `secondary` · `error` · `info` · `success` · `warning` · `inherit` |
+| `size` | number | Diameter of the circle in pixels. Default: `40`. |
+| `thickness` | number | Stroke thickness of the arc. Default: `3.6`. |
+| `showValue` | boolean | `true` displays the numeric percentage in the center of the circle. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Position/spacing via parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+No actions. Progress circle is display-only.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Loading indicators while waiting for an API call.
+- File upload progress (bind `value` to `data.uploadPercent`).
+- Task completion percentage in a card.
+- Score or rating displayed as a filled arc (e.g. 75% completion).
+
+**When NOT to use:**
+- Horizontal progress bar → use `progress-line`.
+- Numeric-only value display → use `kpi-metric`.
+- Complex gauge with min/max → use `kpi-gauge`.
+
+---
+
+## Schema Examples
+
+### Indeterminate loading spinner
+```json
+{
+  "type": "progress-circle",
+  "props": {
+    "variant": "indeterminate",
+    "color": "primary",
+    "size": 48
+  }
+}
+```
+
+### Upload progress with percentage label
+```json
+{
+  "type": "progress-circle",
+  "props": {
+    "value": "data.uploadProgress",
+    "variant": "determinate",
+    "color": "success",
+    "size": 80,
+    "thickness": 5,
+    "showValue": true
+  }
+}
+```
+
+### Completion indicator in a card
+```json
+{
+  "type": "progress-circle",
+  "props": {
+    "value": "data.task.completionPercent",
+    "variant": "determinate",
+    "color": "primary",
+    "size": 60,
+    "showValue": true
+  }
+}
+```
+
+### Small inline loading
+```json
+{
+  "type": "progress-circle",
+  "props": {
+    "variant": "indeterminate",
+    "color": "inherit",
+    "size": 20,
+    "thickness": 4
+  }
+}
+```

package/training/22-progress-line.md

@@ -0,0 +1,93 @@
+# Component: progress-line
+
+A horizontal progress bar. Determinate (value-driven), indeterminate (animation), buffer, or query variants.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `value` | expression | Progress value from `0` to `100`. Used for `determinate` and `buffer` variants. |
+| `variant` | select | `determinate` — fills based on `value`. `indeterminate` — continuous moving animation. `buffer` — shows primary fill + secondary buffer fill. `query` — reverse animation (for query in progress). |
+| `color` | select | `primary` · `secondary` · `error` · `info` · `success` · `warning` · `inherit` |
+| `showValue` | boolean | `true` displays the percentage as text above/below the bar. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control wrapper through parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+No actions. Progress-line is display-only.
+
+---
+
+## Use Cases
+
+**When to use:**
+- File upload progress bar.
+- Form step completion indicator.
+- Loading state for a data fetch.
+- Skill/proficiency level bars in a profile.
+
+**When NOT to use:**
+- Circular loading → use `progress-circle`.
+- Complex gauge with min/max labels → use `kpi-gauge` or `kpi-bullet`.
+- Horizontal bar chart → use `kpi-bullet` or a chart component.
+
+---
+
+## Schema Examples
+
+### Simple upload progress bar
+```json
+{
+  "type": "progress-line",
+  "props": {
+    "value": "data.uploadPercent",
+    "variant": "determinate",
+    "color": "primary",
+    "showValue": true
+  }
+}
+```
+
+### Indeterminate loading
+```json
+{
+  "type": "progress-line",
+  "props": {
+    "variant": "indeterminate",
+    "color": "primary"
+  }
+}
+```
+
+### Skill level bar (static or data-driven)
+```json
+{
+  "type": "progress-line",
+  "props": {
+    "value": "data.skill.level",
+    "variant": "determinate",
+    "color": "success"
+  }
+}
+```
+
+### Buffer variant
+```json
+{
+  "type": "progress-line",
+  "props": {
+    "value": "data.downloaded",
+    "variant": "buffer",
+    "color": "secondary"
+  }
+}
+```

package/training/23-menu.md

@@ -0,0 +1,139 @@
+# Component: menu
+
+A tab/navigation bar component. Children (wizard-steps or panels) are shown based on the active tab. Supports horizontal tabs, vertical tabs, and nav-style menus.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Active tab key is stored in `data[key]`. |
+| `activeKey` | expression | Controlled active tab key. Bind to `data.activeTab` to drive active tab externally. |
+| `appearance` | select | `default` — standard MUI Tabs. `subtle` — minimal underline style. `tabs` — standard tab appearance. |
+| `items` | items-editor | Static list of `{ key, label, icon? }` tab definitions. |
+| `justified` | boolean | Tabs stretch to fill the full width equally. |
+| `reversed` | boolean | Reverses the order of tabs. |
+| `vertical` | boolean | Renders tabs in a vertical column on the left side. |
+| `itemsAs` | expression | Expression driving dynamic tab list from data. |
+| `tabs` | tabs-editor | Advanced tab configuration with panel content per tab. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `variant` | select | `standard` · `scrollable` · `fullWidth` — Controls how tabs distribute horizontally. |
+| `textColor` | select | `primary` · `secondary` · `inherit` — Color of tab label text. |
+| `indicatorColor` | select | `primary` · `secondary` — Color of the active tab underline indicator. |
+| `scrollButtons` | select | `auto` · `desktop` · `on` · `off` — When to show scroll arrows for overflowing tabs. |
+| `centered` | boolean | Centers the tabs in the tab bar (only for `standard` variant). |
+| `gap` | expression | Gap between tab panel content and next element. |
+| `display` | expression | CSS display. |
+| `width` | expression | Tab bar width. |
+| `height` | expression | Tab bar height. |
+| `margin` | expression | Outer margin. |
+| `padding` | expression | Inner padding. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onTabChange` | expression | Expression/code run when the active tab changes. Receives the new tab key. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Multi-section forms where each section is on a tab (Personal Info, Contact, Documents).
+- Dashboard views with multiple data areas accessible by tab.
+- Settings pages with categories (General, Security, Notifications).
+- Navigation within a page without URL change.
+
+**When NOT to use:**
+- Step-by-step forms with validation per step → use `wizard`.
+- Simple show/hide toggle → use conditional rendering via `enabled`/`disabled`.
+- Breadcrumb or wizard-style flow → use `breadcrumb` or `wizard`.
+
+---
+
+## Schema Examples
+
+### Basic tab menu
+```json
+{
+  "type": "menu",
+  "props": {
+    "key": "mainTabs",
+    "appearance": "default",
+    "items": [
+      { "key": "overview", "label": "Overview" },
+      { "key": "details", "label": "Details" },
+      { "key": "history", "label": "History" }
+    ]
+  },
+  "style": {
+    "variant": "standard",
+    "textColor": "primary",
+    "indicatorColor": "primary"
+  }
+}
+```
+
+### Full-width justified tabs
+```json
+{
+  "type": "menu",
+  "props": {
+    "key": "settingsTabs",
+    "appearance": "tabs",
+    "justified": true,
+    "items": [
+      { "key": "general", "label": "General" },
+      { "key": "security", "label": "Security" },
+      { "key": "notifications", "label": "Notifications" }
+    ]
+  },
+  "style": {
+    "variant": "fullWidth",
+    "textColor": "primary",
+    "indicatorColor": "secondary"
+  }
+}
+```
+
+### Vertical tabs
+```json
+{
+  "type": "menu",
+  "props": {
+    "key": "sideNav",
+    "vertical": true,
+    "appearance": "subtle",
+    "items": [
+      { "key": "profile", "label": "Profile" },
+      { "key": "billing", "label": "Billing" },
+      { "key": "api", "label": "API Keys" }
+    ]
+  }
+}
+```
+
+### Controlled by data with onTabChange
+```json
+{
+  "type": "menu",
+  "props": {
+    "key": "reportTabs",
+    "activeKey": "data.activeReport",
+    "items": "data.reportTabs"
+  },
+  "actions": {
+    "onTabChange": "setData({ activeReport: newKey }); loadReport(newKey)"
+  }
+}
+```

package/training/24-popover.md

@@ -0,0 +1,114 @@
+# Component: popover
+
+A floating panel triggered by a button, icon-button, or text. Contains arbitrary child components dropped into it. Useful for contextual actions, filters, or detail panels.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier for referencing with `openPopover(key)` / `closePopover(key)`. |
+| `triggerType` | select | `button` · `icon-button` · `text` — The type of trigger element. |
+| `triggerLabel` | expression | Label shown on the trigger button/text. |
+| `triggerVariant` | select | `text` · `outlined` · `contained` — Button variant (applies to `button` trigger). |
+| `triggerColor` | select | `primary` · `secondary` · `success` · `error` · `warning` · `info` · `inherit` |
+| `triggerSize` | select | `small` · `medium` · `large` |
+| `triggerIcon` | select | One of: `MoreVertOutlined` · `SettingsOutlined` · `TuneOutlined` · `FilterListOutlined` · `SearchOutlined` · `InfoOutlined` · `AddOutlined` · `EditOutlined` · `DeleteOutlined` · `DownloadOutlined` · `ExpandMoreOutlined` · `CheckOutlined` · `CloseOutlined` · `RefreshOutlined` · `StarOutlined` · `LockOutlined` · `LockOpenOutlined` · _(empty)_ |
+| `triggerFullWidth` | boolean | Makes the trigger stretch to full width. |
+| `title` | expression | Optional title shown at the top of the popover panel. |
+| `placement` | select | `bottom-start` · `bottom` · `bottom-end` · `top-start` · `top` · `top-end` · `left` · `right` |
+| `triggerOn` | select | `click` · `hover` — How the popover opens. |
+| `open` | expression | Controlled open state. Bind to `data.popoverOpen` for programmatic control. |
+| `maxWidth` | expression | Max width of the popover panel, e.g. `"320px"`. |
+| `maxHeight` | expression | Max height, e.g. `"400px"` (panel scrolls if content is taller). |
+| `contentPadding` | expression | Padding inside the popover panel, e.g. `"16px"`. |
+| `closeOnContentClick` | boolean | Closes the popover when a child inside it is clicked. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Props — Actions Tab
+
+No dedicated action events. Child components inside the popover handle their own actions.
+
+---
+
+## Use Cases
+
+**When to use:**
+- "More options" menus triggered by a `MoreVertOutlined` icon-button.
+- Filter panels triggered by a `FilterListOutlined` button.
+- Quick-edit forms that pop up alongside a row/item.
+- Info tooltips with rich content (not just text).
+- Color pickers, date range filters, column selectors.
+
+**When NOT to use:**
+- Full-screen or large content → use `dialog`.
+- Simple text tooltip → use button's `tooltip` prop.
+- Permanent side panel → use a layout with a sidebar cell.
+
+---
+
+## Schema Examples
+
+### "More options" icon popover
+```json
+{
+  "type": "popover",
+  "props": {
+    "key": "rowActions",
+    "triggerType": "icon-button",
+    "triggerIcon": "MoreVertOutlined",
+    "triggerColor": "inherit",
+    "placement": "bottom-end",
+    "triggerOn": "click",
+    "maxWidth": "200px",
+    "contentPadding": "8px",
+    "closeOnContentClick": true
+  }
+}
+```
+
+### Filter panel button
+```json
+{
+  "type": "popover",
+  "props": {
+    "key": "filterPanel",
+    "triggerType": "button",
+    "triggerLabel": "Filters",
+    "triggerIcon": "FilterListOutlined",
+    "triggerVariant": "outlined",
+    "triggerColor": "primary",
+    "placement": "bottom-start",
+    "triggerOn": "click",
+    "title": "Filter Options",
+    "maxWidth": "320px",
+    "contentPadding": "16px"
+  }
+}
+```
+
+### Hover info popover
+```json
+{
+  "type": "popover",
+  "props": {
+    "key": "helpInfo",
+    "triggerType": "icon-button",
+    "triggerIcon": "InfoOutlined",
+    "triggerColor": "info",
+    "triggerSize": "small",
+    "triggerOn": "hover",
+    "placement": "top",
+    "maxWidth": "280px",
+    "contentPadding": "12px"
+  }
+}
+```