robobyte-front-builder 1.0.26 → 1.0.27

package/training/12-signature.md

@@ -0,0 +1,107 @@
+# Component: signature
+
+A canvas-based signature pad. Users draw their signature with a mouse or stylus. Value is stored as a base64 PNG data URL.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as base64 PNG string in `data[key]`. |
+| `label` | expression | Label text shown above the signature canvas. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled value (base64 PNG). Pass to pre-fill with existing signature. |
+| `width` | number | Canvas width in pixels. Default: `500`. |
+| `height` | number | Canvas height in pixels. Default: `200`. |
+| `backgroundColor` | text | Canvas background color. Default: `"#ffffff"`. |
+| `penColor` | text | Ink color. Default: `"#000000"`. Accepts any CSS color. |
+| `minWidth` | number | Minimum pen stroke width for thin lines. Default: `0.5`. |
+| `maxWidth` | number | Maximum pen stroke width for thick lines. Default: `2.5`. |
+| `disabled` | boolean | Renders canvas as read-only (no drawing allowed). |
+| `enabled` | boolean | Enable/disable from an expression. |
+
+---
+
+## Props — Style Tab
+
+Uses common input style fields.
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `display` | expression | CSS display. |
+| `width` | expression | Wrapper width. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+
+---
+
+## Props — Actions Tab
+
+No dedicated action events. Use `onChange` pattern via form submission or a save button.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Legal forms, contracts, consent forms.
+- Delivery confirmation signatures.
+- HR onboarding forms.
+- Any scenario requiring a handwritten signature captured digitally.
+
+**When NOT to use:**
+- Text-based initials or typed signatures → use `input`.
+- Image upload from file → use an image-upload component.
+
+---
+
+## Schema Examples
+
+### Standard signature field
+```json
+{
+  "type": "signature",
+  "props": {
+    "key": "customerSignature",
+    "label": "Customer Signature",
+    "required": true,
+    "width": 500,
+    "height": 200,
+    "backgroundColor": "#f9f9f9",
+    "penColor": "#1a237e"
+  }
+}
+```
+
+### Compact signature pad
+```json
+{
+  "type": "signature",
+  "props": {
+    "key": "driverSignature",
+    "label": "Driver Signature",
+    "width": 360,
+    "height": 140,
+    "penColor": "#000000",
+    "minWidth": 1,
+    "maxWidth": 3
+  }
+}
+```
+
+### Read-only display of existing signature
+```json
+{
+  "type": "signature",
+  "props": {
+    "key": "approvalSignature",
+    "label": "Approved By",
+    "value": "data.document.approvalSignature",
+    "disabled": true,
+    "width": 400,
+    "height": 160
+  }
+}
+```

package/training/13-autocomplete.md

@@ -0,0 +1,134 @@
+# Component: autocomplete
+
+A searchable select input with async fetch support, grouping, multi-select, and free-text entry. More powerful than `dropdown` for large datasets.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored in `data[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `placeholder` | text | Hint shown in the search input. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the field. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `fullWidth` | boolean | Stretches to fill container. |
+| `options` | options-editor | Static options list `{ label, value }`. For async, leave empty and use `asyncFetchOptions`. |
+| `isSingle` | boolean | `true` for single-select. `false` (default) for multi-select (value is an array). |
+| `freeSolo` | boolean | Allows users to enter values not in the options list. |
+| `clearable` | boolean | Pressing Escape clears the selection. |
+| `disableCloseOnSelect` | boolean | Keeps the dropdown open after selecting an option (useful for multi-select). |
+| `fetchOnOpen` | boolean | Triggers `asyncFetchOptions` when the dropdown opens. |
+| `labelField` | expression | Field path within each option object to use as the display label, e.g. `"name"`. |
+| `groupByField` | expression | Field path to group options by, e.g. `"department"`. |
+| `targetValue` | expression | Path to extract the stored value from a selected option object, e.g. `"id"`. |
+| `targetValues` | expression | Map of field paths to extract multiple values from the selected option. |
+| `asyncFetchOptions` | expression | Expression/function to fetch options dynamically. Receives the typed search string. |
+
+---
+
+## Props — Style Tab
+
+Same as common input style fields.
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `width` | expression | Field width. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+
+---
+
+## Props — Actions Tab
+
+No dedicated actions. Results write to `data[key]` automatically. Use `onChange` wrapper if needed.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Large option sets where typing to filter is essential (hundreds of entries).
+- Server-side search/autocomplete: type to fetch matching records from an API.
+- Multi-select with search capability.
+- Grouped options (by category, department, etc.).
+- Fields where user may enter a custom value not in the list (`freeSolo`).
+
+**When NOT to use:**
+- Small static list (< 10 items) → use `dropdown` for simplicity.
+- Exact yes/no → use `toggle` or `checkbox`.
+
+---
+
+## Schema Examples
+
+### Single-select from static list
+```json
+{
+  "type": "autocomplete",
+  "props": {
+    "key": "country",
+    "label": "Country",
+    "isSingle": true,
+    "options": "data.countries",
+    "labelField": "name",
+    "targetValue": "code",
+    "placeholder": "Search countries...",
+    "fullWidth": true
+  }
+}
+```
+
+### Async server search
+```json
+{
+  "type": "autocomplete",
+  "props": {
+    "key": "userId",
+    "label": "Assign To",
+    "isSingle": true,
+    "fetchOnOpen": true,
+    "asyncFetchOptions": "searchUsers",
+    "labelField": "fullName",
+    "targetValue": "id",
+    "placeholder": "Type to search users..."
+  }
+}
+```
+
+### Multi-select with groups
+```json
+{
+  "type": "autocomplete",
+  "props": {
+    "key": "permissions",
+    "label": "Permissions",
+    "isSingle": false,
+    "options": "data.allPermissions",
+    "labelField": "name",
+    "groupByField": "module",
+    "disableCloseOnSelect": true,
+    "fullWidth": true
+  }
+}
+```
+
+### Free-text multi with suggestions
+```json
+{
+  "type": "autocomplete",
+  "props": {
+    "key": "tags",
+    "label": "Tags",
+    "isSingle": false,
+    "freeSolo": true,
+    "options": "data.suggestedTags",
+    "placeholder": "Type to add tags"
+  }
+}
+```

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