robobyte-front-builder 1.0.26 → 1.0.27

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

package/training/25-layout.md

@@ -0,0 +1,116 @@
+# Component: layout
+
+A CSS Grid container that holds `layout-cell` children. The primary structural building block for page layouts.
+
+> ⚠️ CRITICAL RULES:
+> - NEVER use the `container` component — it is banned. Always use `layout` instead.
+> - Direct children of `layout` MUST be `layout-cell` nodes. Do not put other components directly inside layout.
+> - The root of every schema should be a `layout` with `cols: 1`.
+> - One component per layout-cell for cols ≥ 2 (unless the cell itself contains a nested layout).
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Optional identifier. |
+| `cols` | number | Number of grid columns. `1` = single column stack. `2` = two equal columns. `3`, `4`, etc. |
+| `gap` | number | Column gap in pixels between cells. Default: `0`. |
+| `rowGap` | number | Row gap in pixels between rows. Default: `0`. |
+| `cellMinHeight` | expression | Default minimum height for every cell, e.g. `"48px"`. Overridden per cell via layout-cell style. |
+| `cellPadding` | expression | Default padding applied to every cell, e.g. `"16px"`. Overridden per cell. |
+| `cellBackgroundColor` | expression | Default background color for all cells, e.g. `"#f5f5f5"`. |
+| `cellBorder` | expression | Default border for all cells, e.g. `"1px solid #e0e0e0"`. |
+| `cellBorderRadius` | expression | Default border-radius for all cells. |
+| `cellBoxShadow` | expression | Default box-shadow for all cells. |
+| `cellJustifyContent` | select | Default horizontal alignment of content within each cell: `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `cellAlignItems` | select | Default vertical alignment within each cell: `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `cellElementStyle` | expression | CSS object expression applied as overrides to all cells (highest priority among grid defaults). |
+| `cellElementCss` | expression | Additional CSS string applied to all cells. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab for the layout container itself. Control the layout wrapper through its parent layout-cell style.
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Cell Positioning (on layout-cell, not layout)
+
+When `cols > 1`, cells auto-flow into columns left-to-right. To manually position a cell:
+- Set `colStart` (1-indexed) and `colSpan` on the cell.
+- Set `rowStart` and `rowSpan` for cross-row spanning.
+- Leave these blank to use CSS auto-placement.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Every page/screen should start with `layout cols:1` as root.
+- Two-column form layout: `cols: 2`.
+- Three-column dashboard cards: `cols: 3`.
+- Mixed widths: use `colSpan` on individual cells (e.g. a cell spanning all 3 columns).
+- Nested sections: put a `layout cols:2` inside a cell of a `layout cols:1`.
+
+**When NOT to use:**
+- Do not nest layouts more than 2–3 deep for performance.
+- For a single-column stack, `cols: 1` is correct (don't nest unnecessarily).
+
+---
+
+## Schema Examples
+
+### Single column (page root)
+```json
+{
+  "type": "layout",
+  "props": { "cols": 1, "gap": 0, "rowGap": 16 },
+  "children": [
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "header", "props": { "text": "Page Title", "variant": "h4" } }] },
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "input", "props": { "key": "name", "label": "Name" } }] }
+  ]
+}
+```
+
+### Two-column form
+```json
+{
+  "type": "layout",
+  "props": { "cols": 2, "gap": 16, "rowGap": 16 },
+  "children": [
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "input", "props": { "key": "firstName", "label": "First Name" } }] },
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "input", "props": { "key": "lastName", "label": "Last Name" } }] },
+    { "type": "layout-cell", "props": { "colSpan": 2 }, "children": [{ "type": "textarea", "props": { "key": "bio", "label": "Bio" } }] }
+  ]
+}
+```
+
+### Three-column KPI cards
+```json
+{
+  "type": "layout",
+  "props": {
+    "cols": 3,
+    "gap": 16,
+    "rowGap": 16,
+    "cellPadding": "20px",
+    "cellBackgroundColor": "#ffffff",
+    "cellBorderRadius": "8px",
+    "cellBoxShadow": "0 2px 8px rgba(0,0,0,0.08)"
+  },
+  "children": [
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "kpi-metric", "props": { "valueKey": "data.revenue", "label": "Revenue", "format": "currency" } }] },
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "kpi-metric", "props": { "valueKey": "data.orders", "label": "Orders", "format": "number" } }] },
+    { "type": "layout-cell", "props": {}, "children": [{ "type": "kpi-metric", "props": { "valueKey": "data.growth", "label": "Growth", "format": "percent" } }] }
+  ]
+}
+```

package/training/26-layout-cell.md

@@ -0,0 +1,143 @@
+# Component: layout-cell
+
+A single cell inside a `layout` grid container. Controls grid positioning and individual cell styling. Must be a direct child of `layout`.
+
+---
+
+## Props — Main Tab (Grid Positioning)
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Optional identifier. |
+| `colStart` | number | Which grid column this cell starts at (1-indexed). Leave blank for auto-placement. |
+| `rowStart` | number | Which grid row this cell starts at (1-indexed). Leave blank for auto-placement. |
+| `colSpan` | number | How many columns this cell spans. Default: `1`. Set to total cols to span full width. |
+| `rowSpan` | number | How many rows this cell spans. Default: `1`. |
+
+> NOTE: Only set `colStart`/`rowStart` when you need explicit positioning. For most layouts, leave them blank and let CSS auto-placement distribute cells.
+
+---
+
+## Props — Style Tab (Cell Visual Styling)
+
+These control the visual appearance of the individual cell. They override the parent layout's `cell*` defaults.
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `elementStyle` | expression | CSS object expression merged last (highest priority), e.g. `{ background: 'linear-gradient(...)' }`. |
+| `elementCss` | expression | CSS string expression merged last, e.g. `"background: linear-gradient(...)"`. |
+| `padding` | expression | Cell inner padding, e.g. `"16px"` or `"8px 16px"`. |
+| `paddingTop` | expression | Top padding only. |
+| `paddingBottom` | expression | Bottom padding only. |
+| `paddingLeft` | expression | Left padding only. |
+| `paddingRight` | expression | Right padding only. |
+| `width` | expression | Cell width override. Usually auto from grid. |
+| `minHeight` | expression | Minimum height, e.g. `"200px"`. |
+| `maxHeight` | expression | Maximum height; content scrolls if taller. |
+| `backgroundColor` | expression | Background color, e.g. `"#ffffff"`, `"primary.light"`. |
+| `backgroundImage` | expression | CSS background-image, e.g. `"url('/img/bg.jpg')"`. |
+| `backgroundSize` | expression | CSS background-size, e.g. `"cover"`, `"contain"`. |
+| `border` | expression | Full border shorthand, e.g. `"1px solid #e0e0e0"`. |
+| `borderTop` | expression | Top border only. |
+| `borderBottom` | expression | Bottom border only. |
+| `borderLeft` | expression | Left border only. |
+| `borderRight` | expression | Right border only. |
+| `borderRadius` | expression | Rounded corners, e.g. `"8px"`, `"12px 12px 0 0"`. |
+| `borderColor` | expression | Border color (used with border shorthand). |
+| `justifyContent` | select | Horizontal alignment of content: `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | Vertical alignment of content: `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between children inside the cell, e.g. `"8px"`. |
+| `boxShadow` | expression | Box shadow, e.g. `"0 2px 8px rgba(0,0,0,0.1)"`. |
+| `opacity` | expression | Cell opacity, e.g. `"0.8"`. |
+| `overflow` | expression | CSS overflow: `"hidden"`, `"auto"`, `"visible"`. |
+
+---
+
+## Props — Actions Tab
+
+No actions.
+
+---
+
+## Use Cases
+
+**Always use layout-cell as the direct child of layout.**
+
+- A cell with only `justifyContent: center` and `alignItems: center` centers its content.
+- A card-style cell: `backgroundColor: "#fff"`, `borderRadius: "8px"`, `boxShadow: "0 2px 8px rgba(0,0,0,0.08)"`, `padding: "20px"`.
+- A highlighted header cell: `backgroundColor: "primary.main"`, `padding: "16px"`.
+- `colSpan: 2` in a `cols: 2` layout spans the full width.
+- `minHeight: "300px"` ensures a cell has a minimum size for visual balance.
+
+---
+
+## Schema Examples
+
+### Plain auto-placed cell
+```json
+{
+  "type": "layout-cell",
+  "props": {},
+  "style": { "padding": "16px" },
+  "children": [
+    { "type": "input", "props": { "key": "email", "label": "Email" } }
+  ]
+}
+```
+
+### Card-style cell
+```json
+{
+  "type": "layout-cell",
+  "props": {},
+  "style": {
+    "backgroundColor": "#ffffff",
+    "borderRadius": "8px",
+    "boxShadow": "0 2px 8px rgba(0,0,0,0.08)",
+    "padding": "20px"
+  },
+  "children": [
+    { "type": "kpi-metric", "props": { "valueKey": "data.revenue", "label": "Revenue", "format": "currency" } }
+  ]
+}
+```
+
+### Full-width cell (spans all 3 columns in a cols:3 layout)
+```json
+{
+  "type": "layout-cell",
+  "props": { "colSpan": 3 },
+  "style": { "padding": "0 0 16px 0" },
+  "children": [
+    { "type": "header", "props": { "text": "Section Title", "variant": "h5" } }
+  ]
+}
+```
+
+### Centered content cell
+```json
+{
+  "type": "layout-cell",
+  "props": {},
+  "style": {
+    "justifyContent": "center",
+    "alignItems": "center",
+    "minHeight": "200px",
+    "backgroundColor": "#f5f5f5",
+    "borderRadius": "8px"
+  },
+  "children": [
+    { "type": "progress-circle", "props": { "variant": "indeterminate", "color": "primary" } }
+  ]
+}
+```
+
+### Explicit grid positioning (spans rows)
+```json
+{
+  "type": "layout-cell",
+  "props": { "colStart": 2, "rowStart": 1, "rowSpan": 2 },
+  "style": { "padding": "20px", "backgroundColor": "#fff" },
+  "children": []
+}
+```

package/training/27-card.md

@@ -0,0 +1,87 @@
+# Component: card
+
+A MUI Card container with an optional title and subheader. Contains arbitrary child components.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Optional identifier. |
+| `title` | expression | Card header title text, e.g. `"User Details"` or `data.project.name`. Leave blank for no header. |
+| `subheader` | expression | Secondary text below the title, e.g. a date or role. |
+| `variant` | select | `elevation` — floating card with shadow. `outlined` — flat card with border, no shadow. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab. Use the parent layout-cell style for spacing/shadow. The card itself uses MUI's default elevation/border.
+
+---
+
+## Props — Actions Tab
+
+No actions. Card is a container component.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Grouping related content with a visual card boundary (user profile, product, post).
+- Dashboard panels with a labeled title area.
+- List items rendered via a `repeater` — each repeater item is a card.
+
+**When NOT to use:**
+- When you want full control of the outer styling → use a `layout-cell` with `backgroundColor`, `borderRadius`, `boxShadow`.
+- When the card border/shadow would conflict with a custom design → style via layout-cell instead.
+- Tabs with panel switching → use `menu`.
+
+---
+
+## Schema Examples
+
+### Basic card with title
+```json
+{
+  "type": "card",
+  "props": {
+    "title": "Personal Information",
+    "variant": "elevation"
+  },
+  "children": [
+    { "type": "input", "props": { "key": "name", "label": "Name" } },
+    { "type": "input", "props": { "key": "email", "label": "Email" } }
+  ]
+}
+```
+
+### Outlined card with subheader
+```json
+{
+  "type": "card",
+  "props": {
+    "title": "data.project.name",
+    "subheader": "data.project.createdAt",
+    "variant": "outlined"
+  },
+  "children": [
+    { "type": "label", "props": { "text": "data.project.description", "variant": "body2" } }
+  ]
+}
+```
+
+### Card without header (container only)
+```json
+{
+  "type": "card",
+  "props": {
+    "variant": "elevation"
+  },
+  "children": [
+    { "type": "kpi-metric", "props": { "valueKey": "data.total", "label": "Total Sales", "format": "currency" } }
+  ]
+}
+```