robobyte-front-builder 1.0.26 → 1.0.28

package/training/14-button.md

@@ -0,0 +1,168 @@
+# Component: button
+
+A clickable action button. Supports form submission, reset, custom code, icons, and tooltip.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Optional identifier for targeting or referencing. |
+| `label` | expression | Button text. Can be any expression returning a string. |
+| `variant` | select | `text` — no background. `outlined` — border only. `contained` — filled background. |
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` · `inherit` |
+| `size` | select | `small` · `medium` · `large` |
+| `prefix` | icon | Icon shown before the label (left icon). |
+| `suffix` | icon | Icon shown after the label (right icon). |
+| `tooltip` | expression | Tooltip text shown on hover. |
+| `iconButton` | boolean | `true` renders as a circular icon-only button (no label). Pair with `prefix`. |
+| `disabled` | boolean | Makes the button non-clickable. |
+| `fullWidth` | boolean | Stretches button to 100% of its container. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `background` | expression | CSS background shorthand, e.g. `"linear-gradient(45deg, #FE6B8B, #FF8E53)"`. |
+| `backgroundColor` | expression | Solid background color, e.g. `"#1976d2"`. |
+| `color` | expression | Text/icon color, e.g. `"#ffffff"`. |
+| `borderRadius` | expression | Border radius, e.g. `"8px"` or `"50%"`. |
+| `boxShadow` | expression | Box shadow, e.g. `"0 4px 12px rgba(0,0,0,0.2)"`. |
+| `border` | expression | Full border shorthand, e.g. `"2px solid #1976d2"`. |
+| `borderColor` | expression | Border color only. |
+| `textTransform` | select | `none` · `uppercase` · `lowercase` · `capitalize` |
+| `fontWeight` | expression | Font weight, e.g. `"600"`. |
+| `fontSize` | expression | Font size, e.g. `"14px"`. |
+| `letterSpacing` | expression | Letter spacing, e.g. `"0.05em"`. |
+| `width` | expression | Button width, e.g. `"160px"`. |
+| `height` | expression | Button height. |
+| `padding` | expression | Inner padding override. |
+| `margin` | expression | Outer margin. |
+| `display` | expression | CSS display. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onClick` | action | `submit` — submits the parent form. `reset` — resets all form fields. `custom` — runs custom code. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Form submit/save buttons (`onClick: submit`).
+- Form reset/clear buttons (`onClick: reset`).
+- Navigation triggers: go to next step, open dialog, navigate to another view.
+- API calls: save record, delete, approve.
+- Icon-only action buttons in toolbars (`iconButton: true`).
+
+**When NOT to use:**
+- Navigation links → use `link`.
+- Tab switching → use `menu`.
+- Toggle state → use `toggle`.
+
+---
+
+## Schema Examples
+
+### Primary submit button
+```json
+{
+  "type": "button",
+  "props": {
+    "key": "submitBtn",
+    "label": "Save",
+    "variant": "contained",
+    "color": "primary",
+    "fullWidth": true,
+    "prefix": "SaveOutlined"
+  },
+  "actions": {
+    "onClick": { "type": "submit" }
+  }
+}
+```
+
+### Custom action button
+```json
+{
+  "type": "button",
+  "props": {
+    "label": "Approve",
+    "variant": "contained",
+    "color": "success",
+    "prefix": "CheckCircleOutlined",
+    "tooltip": "Approve this request"
+  },
+  "actions": {
+    "onClick": {
+      "type": "custom",
+      "code": "approveRequest({ id: data.request.id }); setData({ approved: true })"
+    }
+  }
+}
+```
+
+### Icon-only button
+```json
+{
+  "type": "button",
+  "props": {
+    "key": "refreshBtn",
+    "iconButton": true,
+    "prefix": "RefreshOutlined",
+    "tooltip": "Refresh data",
+    "color": "primary",
+    "size": "small"
+  },
+  "actions": {
+    "onClick": {
+      "type": "custom",
+      "code": "refreshData()"
+    }
+  }
+}
+```
+
+### Danger / destructive button
+```json
+{
+  "type": "button",
+  "props": {
+    "label": "Delete",
+    "variant": "outlined",
+    "color": "error",
+    "prefix": "DeleteOutlined"
+  },
+  "style": {
+    "borderRadius": "4px"
+  },
+  "actions": {
+    "onClick": {
+      "type": "custom",
+      "code": "openDialog('confirmDelete')"
+    }
+  }
+}
+```
+
+### Reset form button
+```json
+{
+  "type": "button",
+  "props": {
+    "label": "Reset",
+    "variant": "text",
+    "color": "inherit"
+  },
+  "actions": {
+    "onClick": { "type": "reset" }
+  }
+}
+```

package/training/15-label.md

@@ -0,0 +1,138 @@
+# Component: label
+
+A text display element using MUI Typography. Use for body text, captions, subtitles, and data display. Not interactive.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `text` | expression | The text to display. Can be any expression: `data.userName`, `"Static text"`, `data.count + " items"`. |
+| `prefix` | icon | Icon shown before the text. |
+| `suffix` | icon | Icon shown after the text. |
+| `iconSize` | expression | Size of both prefix and suffix icons when `prefix`/`suffix` share a size, e.g. `"20px"`. |
+| `iconColor` | expression | Color of both icons, e.g. `"primary.main"`. |
+| `prefixSize` | expression | Size of prefix icon specifically. |
+| `prefixColor` | expression | Color of prefix icon specifically. |
+| `suffixSize` | expression | Size of suffix icon specifically. |
+| `suffixColor` | expression | Color of suffix icon specifically. |
+| `iconGap` | expression | Gap between icon and text, e.g. `"8px"`. |
+| `variant` | select | `body1` · `body2` · `caption` · `overline` · `subtitle1` · `subtitle2` — MUI Typography variant controlling font size/weight. |
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` · `textPrimary` · `textSecondary` |
+| `align` | select | `left` · `center` · `right` · `justify` |
+| `gutterBottom` | boolean | Adds bottom margin equal to one line-height. |
+| `noWrap` | boolean | Prevents text wrapping; shows ellipsis on overflow. |
+| `paragraph` | boolean | Renders as a `<p>` element with paragraph margins. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `elementStyle` | expression | CSS object override applied to the wrapper element. |
+| `elementCss` | expression | CSS string override applied to the wrapper element. |
+| `display` | expression | CSS display. |
+| `width` | expression | Wrapper width. |
+| `height` | expression | Wrapper height. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+| `fontSize` | expression | Font size override, e.g. `"16px"`. |
+| `fontWeight` | expression | Font weight, e.g. `"600"`. |
+| `lineHeight` | expression | Line height, e.g. `"1.5"`. |
+| `letterSpacing` | expression | Letter spacing, e.g. `"0.05em"`. |
+| `textTransform` | expression | CSS text-transform, e.g. `"uppercase"`. |
+
+---
+
+## Props — Actions Tab
+
+No actions. Label is display-only. Use `link` or `button` for clickable text.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Displaying field values in read-only detail views.
+- Body text, descriptions, helper text.
+- Captions below images or charts.
+- Metadata display: created at, updated by, status text.
+- Small labels with icons (e.g. status indicators).
+
+**When NOT to use:**
+- Page/section titles → use `header`.
+- Clickable text → use `link` or `button`.
+- Data that needs formatting (currency, dates) → display through KPI components.
+
+---
+
+## Schema Examples
+
+### Simple body text
+```json
+{
+  "type": "label",
+  "props": {
+    "text": "Welcome to the dashboard",
+    "variant": "body1",
+    "color": "textPrimary"
+  }
+}
+```
+
+### Dynamic value display
+```json
+{
+  "type": "label",
+  "props": {
+    "text": "data.user.fullName",
+    "variant": "subtitle1",
+    "color": "primary",
+    "align": "left"
+  }
+}
+```
+
+### With prefix icon
+```json
+{
+  "type": "label",
+  "props": {
+    "text": "data.record.status",
+    "prefix": "CircleOutlined",
+    "prefixColor": "success.main",
+    "prefixSize": "12px",
+    "iconGap": "6px",
+    "variant": "body2",
+    "color": "textSecondary"
+  }
+}
+```
+
+### Caption text
+```json
+{
+  "type": "label",
+  "props": {
+    "text": "Last updated: data.lastUpdated",
+    "variant": "caption",
+    "color": "textSecondary",
+    "align": "right"
+  }
+}
+```
+
+### Truncated single line
+```json
+{
+  "type": "label",
+  "props": {
+    "text": "data.item.description",
+    "variant": "body2",
+    "noWrap": true,
+    "color": "textSecondary"
+  }
+}
+```

package/training/16-header.md

@@ -0,0 +1,128 @@
+# Component: header
+
+A heading text element using MUI Typography h1–h6 variants. Use for page titles, section headings, and card titles.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `text` | expression | The heading text. Can be an expression or static string. |
+| `prefix` | icon | Icon shown before the heading text. |
+| `suffix` | icon | Icon shown after the heading text. |
+| `iconSize` | expression | Size of both icons, e.g. `"24px"`. |
+| `iconColor` | expression | Color of both icons, e.g. `"primary.main"`. |
+| `prefixSize` | expression | Size of prefix icon specifically. |
+| `prefixColor` | expression | Color of prefix icon. |
+| `suffixSize` | expression | Size of suffix icon specifically. |
+| `suffixColor` | expression | Color of suffix icon. |
+| `iconGap` | expression | Gap between icon and text, e.g. `"8px"`. |
+| `variant` | select | `h1` · `h2` · `h3` · `h4` · `h5` · `h6` — Controls visual size/weight. |
+| `component` | select | `h1` · `h2` · `h3` · `h4` · `h5` · `h6` · `div` · `span` — Actual HTML tag rendered. Set independently from `variant` for SEO control. |
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` · `textPrimary` · `textSecondary` |
+| `align` | select | `left` · `center` · `right` · `justify` |
+| `gutterBottom` | boolean | Adds bottom margin equal to one line-height. |
+| `noWrap` | boolean | Prevents wrapping; shows ellipsis on overflow. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `elementStyle` | expression | CSS object override applied to the wrapper element. |
+| `elementCss` | expression | CSS string override applied to the wrapper element. |
+| `display` | expression | CSS display. |
+| `width` | expression | Wrapper width. |
+| `height` | expression | Wrapper height. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+| `fontSize` | expression | Font size override, e.g. `"28px"`. |
+| `fontWeight` | expression | Font weight override, e.g. `"800"`. |
+| `lineHeight` | expression | Line height. |
+| `letterSpacing` | expression | Letter spacing, e.g. `"-0.02em"`. |
+| `textTransform` | expression | CSS text-transform, e.g. `"uppercase"`. |
+
+---
+
+## Props — Actions Tab
+
+No actions. Header is display-only.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Page title at the top of a view.
+- Section headings to divide content areas.
+- Card/panel titles.
+- Any prominent text that needs h1–h6 semantic weight.
+
+**When NOT to use:**
+- Body text or descriptions → use `label`.
+- Clickable heading → use `link` styled with a heading variant.
+- Metric values → use KPI components.
+
+---
+
+## Schema Examples
+
+### Page title
+```json
+{
+  "type": "header",
+  "props": {
+    "text": "Employee Profile",
+    "variant": "h4",
+    "component": "h1",
+    "color": "textPrimary",
+    "gutterBottom": true
+  }
+}
+```
+
+### Section heading with icon
+```json
+{
+  "type": "header",
+  "props": {
+    "text": "Contact Information",
+    "variant": "h6",
+    "component": "h2",
+    "prefix": "ContactMailOutlined",
+    "prefixColor": "primary.main",
+    "iconGap": "8px",
+    "color": "primary"
+  }
+}
+```
+
+### Dynamic heading from data
+```json
+{
+  "type": "header",
+  "props": {
+    "text": "data.project.name",
+    "variant": "h5",
+    "component": "h2",
+    "align": "center",
+    "color": "textPrimary"
+  }
+}
+```
+
+### Centered dashboard title
+```json
+{
+  "type": "header",
+  "props": {
+    "text": "Sales Dashboard",
+    "variant": "h3",
+    "component": "h1",
+    "align": "center",
+    "color": "primary"
+  }
+}
+```

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