robobyte-front-builder 1.0.26 → 1.0.27

package/training/17-divider.md

@@ -0,0 +1,96 @@
+# Component: divider
+
+A thin horizontal or vertical line used to visually separate sections. Can include optional center text.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `text` | expression | Optional label text displayed in the middle of the divider line. Leave blank for a plain line. |
+| `orientation` | select | `horizontal` · `vertical` — Direction of the divider line. |
+| `variant` | select | `fullWidth` — spans full width. `inset` — indented on the left. `middle` — indented on both sides. |
+| `textAlign` | select | `center` · `left` · `right` — Position of the text label on the line. |
+| `flexItem` | boolean | `true` when the divider is inside a flex container and acts as a flex child (needed for vertical dividers in flex rows). |
+| `light` | boolean | Renders with lighter opacity (faded). |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control wrapper spacing with parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+No actions. Divider is purely decorative.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Visually separating form sections (e.g. "Personal Info" vs "Contact Info").
+- Dividing cards or panels into distinct areas.
+- Labelled sections: a horizontal line with text "OR" between login options.
+- Vertical separator between two side-by-side elements (set `orientation: vertical`, `flexItem: true`).
+
+**When NOT to use:**
+- Complex multi-column separation → use layout with borders on cells.
+- Spacing alone → use layout cell padding/gap instead.
+
+---
+
+## Schema Examples
+
+### Plain horizontal divider
+```json
+{
+  "type": "divider",
+  "props": {
+    "orientation": "horizontal",
+    "variant": "fullWidth"
+  }
+}
+```
+
+### Labelled section divider
+```json
+{
+  "type": "divider",
+  "props": {
+    "text": "Personal Information",
+    "orientation": "horizontal",
+    "variant": "fullWidth",
+    "textAlign": "left"
+  }
+}
+```
+
+### "OR" divider between login options
+```json
+{
+  "type": "divider",
+  "props": {
+    "text": "OR",
+    "orientation": "horizontal",
+    "variant": "middle",
+    "textAlign": "center",
+    "light": true
+  }
+}
+```
+
+### Vertical separator in flex row
+```json
+{
+  "type": "divider",
+  "props": {
+    "orientation": "vertical",
+    "flexItem": true,
+    "variant": "fullWidth"
+  }
+}
+```

package/training/18-image.md

@@ -0,0 +1,105 @@
+# Component: image
+
+Renders an image from a URL. Supports sizing, object-fit, and border-radius for various display contexts.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `src` | expression | Image URL. Can be a static URL string or a data-bound expression: `data.user.avatar`. |
+| `alt` | expression | Alternative text for accessibility. |
+| `width` | expression | Image display width, e.g. `"100%"`, `"200px"`, `"auto"`. |
+| `height` | expression | Image display height, e.g. `"150px"`, `"auto"`. |
+| `objectFit` | select | `cover` — scales to fill box, crops edges. `contain` — scales to fit within box, adds letterbox. `fill` — stretches to fill (may distort). `none` — original size. `scale-down` — smallest of `contain` or `none`. |
+| `borderRadius` | expression | Rounds the corners, e.g. `"8px"`, `"50%"` for a circle/avatar. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Control wrapper through parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+No dedicated action events for image.
+
+---
+
+## Use Cases
+
+**When to use:**
+- User avatars (circular with `borderRadius: "50%"`).
+- Product images in cards.
+- Logo display in headers.
+- Background-style decorative images within a card.
+- Thumbnails in a repeater list.
+
+**When NOT to use:**
+- SVG icons → use the `icon` type in prefix/suffix or `kpi-icon-box`.
+- Background color/pattern → use layout-cell `backgroundImage` style prop.
+- Charts/visualizations → use KPI components.
+
+---
+
+## Schema Examples
+
+### Basic image
+```json
+{
+  "type": "image",
+  "props": {
+    "src": "data.product.imageUrl",
+    "alt": "Product image",
+    "width": "100%",
+    "height": "200px",
+    "objectFit": "cover"
+  }
+}
+```
+
+### Circular avatar
+```json
+{
+  "type": "image",
+  "props": {
+    "src": "data.user.avatarUrl",
+    "alt": "data.user.name",
+    "width": "80px",
+    "height": "80px",
+    "objectFit": "cover",
+    "borderRadius": "50%"
+  }
+}
+```
+
+### Logo in header
+```json
+{
+  "type": "image",
+  "props": {
+    "src": "/images/logo.png",
+    "alt": "Company Logo",
+    "height": "40px",
+    "objectFit": "contain"
+  }
+}
+```
+
+### Thumbnail with rounded corners
+```json
+{
+  "type": "image",
+  "props": {
+    "src": "data.item.thumbnail",
+    "alt": "data.item.title",
+    "width": "120px",
+    "height": "90px",
+    "objectFit": "cover",
+    "borderRadius": "8px"
+  }
+}
+```

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