robobyte-front-builder 1.0.26 → 1.0.27

package/training/01-input.md

@@ -0,0 +1,144 @@
+# Component: input
+
+A single-line text input field. Supports labels, placeholders, icons, and real-time validation feedback.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. The user's typed value is stored in `data[key]` and `form[key]`. |
+| `label` | expression | Label text shown above/beside the field. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field as required; shows asterisk on label. |
+| `value` | expression | Initial/controlled value. Bind to `data.someKey` to pre-fill. |
+| `placeholder` | text | Greyed hint text shown when empty. |
+| `size` | select | `small` · `medium` · `large` |
+| `prefix` | icon | MUI icon displayed at the start of the input. |
+| `suffix` | icon | MUI icon displayed at the end of the input. |
+| `labelPrefix` | icon | Icon displayed before the label text. |
+| `labelSuffix` | icon | Icon displayed after the label text. |
+| `labelIconSize` | expression | Size of label icons, e.g. `"18px"`. |
+| `labelIconColor` | expression | Color of label icons, e.g. `"primary.main"`. |
+| `labelFontSize` | expression | Label text size, e.g. `"14px"`. |
+| `labelFontWeight` | expression | Label font weight, e.g. `"600"`. |
+| `labelColor` | expression | Label text color, e.g. `"#333"` or `"text.secondary"`. |
+| `labelFontStyle` | select | `normal` · `italic` · `oblique` |
+| `labelLetterSpacing` | expression | Letter spacing for label, e.g. `"0.05em"`. |
+| `disabled` | boolean | Disables the field entirely. |
+| `enabled` | boolean | Enables/disables the field from an expression, e.g. `data.isEditable`. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `elementStyle` | expression | CSS object applied directly to the component wrapper as a style override. Highest priority. E.g. `{ outline: '2px solid red' }`. |
+| `elementCss` | expression | CSS string applied to the component wrapper. Alternative to `elementStyle` for shorthand CSS. E.g. `"outline: 2px solid red; transition: all 0.2s"`. |
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` — MUI color variant for the field border/focus ring. |
+| `display` | expression | CSS display, e.g. `"flex"`. |
+| `width` | expression | Field width, e.g. `"100%"` or `"320px"`. |
+| `height` | expression | Field height override. |
+| `margin` | expression | Outer spacing, e.g. `"0 8px"`. |
+| `padding` | expression | Inner padding override. |
+| `flexDirection` | select | `row` · `column` · `row-reverse` · `column-reverse` |
+| `justifyContent` | select | `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between label and input when stacked. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onChange` | action (custom) | Fires every time the user changes the input value. Use to trigger calculations, show/hide elements, or call APIs. |
+| `onBlur` | action (custom) | Fires when the field loses focus. Use for validation or save-on-leave patterns. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Collecting short free-text: names, emails, usernames, search queries, addresses.
+- Any single-line form field that needs validation or a label.
+- Fields requiring icons (e.g. a search icon prefix or password-eye suffix).
+
+**When NOT to use:**
+- Multi-line text → use `textarea` or `richtext`.
+- Number input with formatting → use `number`.
+- Date input → use `datepicker`.
+- Selection from a list → use `dropdown`, `radio`, or `autocomplete`.
+
+---
+
+## Schema Examples
+
+### Minimal text input
+```json
+{
+  "type": "input",
+  "props": {
+    "key": "firstName",
+    "label": "First Name",
+    "placeholder": "Enter your first name",
+    "required": true
+  }
+}
+```
+
+### Pre-filled, sized, with icons
+```json
+{
+  "type": "input",
+  "props": {
+    "key": "email",
+    "label": "Email Address",
+    "labelPosition": "top",
+    "value": "data.userEmail",
+    "placeholder": "user@example.com",
+    "prefix": "EmailOutlined",
+    "size": "medium",
+    "required": true
+  },
+  "style": {
+    "width": "100%",
+    "color": "primary"
+  }
+}
+```
+
+### Disabled read-only field
+```json
+{
+  "type": "input",
+  "props": {
+    "key": "userId",
+    "label": "User ID",
+    "value": "data.userId",
+    "labelPosition": "left",
+    "disabled": true
+  }
+}
+```
+
+### With onChange action
+```json
+{
+  "type": "input",
+  "props": {
+    "key": "searchQuery",
+    "label": "Search",
+    "prefix": "SearchOutlined",
+    "placeholder": "Type to filter..."
+  },
+  "actions": {
+    "onChange": {
+      "type": "custom",
+      "code": "setData({ filteredList: data.fullList.filter(i => i.name.includes(form.searchQuery)) })"
+    }
+  }
+}
+```

package/training/02-checkbox.md

@@ -0,0 +1,107 @@
+# Component: checkbox
+
+A boolean toggle rendered as a checkbox. Stores `true`/`false` in `data[key]`.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as boolean in `data[key]` and `form[key]`. |
+| `label` | expression | Label text shown next to the checkbox. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled checked state, e.g. `data.isActive`. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Prevents toggling. |
+| `enabled` | boolean | Enable/disable from an expression. |
+
+---
+
+## Props — Style Tab
+
+Same as Input style tab:
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `display` | expression | CSS display override. |
+| `width` | expression | Wrapper width. |
+| `height` | expression | Wrapper height. |
+| `margin` | expression | Outer margin. |
+| `padding` | expression | Inner padding. |
+| `flexDirection` | select | `row` · `column` · `row-reverse` · `column-reverse` |
+| `justifyContent` | select | `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between elements. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onChange` | action (custom) | Fires when the checkbox is toggled. The new value is in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Accept terms & conditions.
+- Boolean flags on forms: `isActive`, `rememberMe`, `newsletter`.
+- Feature toggles in a settings panel.
+- Multi-select when combined with multiple checkboxes (or use `tag`/`dropdown multiple`).
+
+**When NOT to use:**
+- Mutually exclusive options → use `radio`.
+- On/Off toggle with a different appearance → use `toggle`.
+- Multiple-choice with a list → use `dropdown` with `multiple: true`.
+
+---
+
+## Schema Examples
+
+### Simple boolean checkbox
+```json
+{
+  "type": "checkbox",
+  "props": {
+    "key": "acceptTerms",
+    "label": "I accept the terms and conditions",
+    "required": true
+  }
+}
+```
+
+### Controlled with expression
+```json
+{
+  "type": "checkbox",
+  "props": {
+    "key": "isActive",
+    "label": "Active",
+    "value": "data.record.isActive",
+    "labelPosition": "right",
+    "color": "success"
+  }
+}
+```
+
+### With onChange
+```json
+{
+  "type": "checkbox",
+  "props": {
+    "key": "showDetails",
+    "label": "Show additional details"
+  },
+  "actions": {
+    "onChange": {
+      "type": "custom",
+      "code": "setData({ detailsVisible: form.showDetails })"
+    }
+  }
+}
+```

package/training/03-dropdown.md

@@ -0,0 +1,135 @@
+# Component: dropdown
+
+A select input letting users choose one or multiple options from a list. Options can be static or data-driven.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Selected value(s) stored in `data[key]` and `form[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled value. For multiple, pass an array. |
+| `placeholder` | text | Greyed hint text when nothing is selected. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the dropdown. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `fullWidth` | boolean | Stretches the dropdown to fill its container. |
+| `options` | options-editor | Static list of `{ label, value }` pairs. Can also be bound to `data.someArray`. |
+| `multiple` | boolean | Allows selecting multiple items (value becomes an array). |
+| `native` | boolean | Renders as a native HTML `<select>` element instead of MUI. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `display` | expression | CSS display. |
+| `width` | expression | e.g. `"100%"` or `"280px"`. |
+| `height` | expression | Height override. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding override. |
+| `flexDirection` | select | `row` · `column` · `row-reverse` · `column-reverse` |
+| `justifyContent` | select | `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between elements. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onChange` | action (custom) | Fires when selection changes. New value is in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Choosing from a fixed list (countries, categories, statuses).
+- Filtering data by a field when bound to data array.
+- Multi-select: `multiple: true` for tag-like selection with a list.
+
+**When NOT to use:**
+- Only 2–4 choices visible at once → use `radio`.
+- Freeform text with suggestions → use `autocomplete`.
+- Boolean on/off → use `checkbox` or `toggle`.
+
+---
+
+## Schema Examples
+
+### Static options
+```json
+{
+  "type": "dropdown",
+  "props": {
+    "key": "status",
+    "label": "Status",
+    "required": true,
+    "placeholder": "Select status",
+    "options": [
+      { "label": "Active", "value": "active" },
+      { "label": "Inactive", "value": "inactive" },
+      { "label": "Pending", "value": "pending" }
+    ]
+  },
+  "style": { "width": "100%", "color": "primary" }
+}
+```
+
+### Dynamic options from data
+```json
+{
+  "type": "dropdown",
+  "props": {
+    "key": "departmentId",
+    "label": "Department",
+    "value": "data.employee.departmentId",
+    "options": "data.departments",
+    "fullWidth": true
+  }
+}
+```
+
+### Multiple select
+```json
+{
+  "type": "dropdown",
+  "props": {
+    "key": "roles",
+    "label": "Roles",
+    "multiple": true,
+    "options": [
+      { "label": "Admin", "value": "admin" },
+      { "label": "Editor", "value": "editor" },
+      { "label": "Viewer", "value": "viewer" }
+    ],
+    "fullWidth": true
+  }
+}
+```
+
+### With onChange to cascade another field
+```json
+{
+  "type": "dropdown",
+  "props": {
+    "key": "countryId",
+    "label": "Country",
+    "options": "data.countries"
+  },
+  "actions": {
+    "onChange": {
+      "type": "custom",
+      "code": "setData({ cities: [], selectedCity: null }); fetchCities(form.countryId)"
+    }
+  }
+}
+```

package/training/04-datepicker.md

@@ -0,0 +1,139 @@
+# Component: datepicker
+
+A date selection field with a calendar popup. Supports date formats, range restrictions, and view modes.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Selected date string stored in `data[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled value. Pass a date string or `data.someDate`. |
+| `placeholder` | text | Hint text, e.g. `"YYYY-MM-DD"`. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the field. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `format` | text | Output format string, e.g. `"YYYY-MM-DD"`, `"DD/MM/YYYY"`, `"MM-DD-YYYY"`. |
+| `views` | select | Which calendar panel to show: `day` · `month` · `year` |
+| `openTo` | select | Which view opens first: `day` · `month` · `year` |
+| `minDate` | expression | Earliest selectable date, e.g. `"2020-01-01"` or `data.contractStart`. |
+| `maxDate` | expression | Latest selectable date, e.g. `new Date().toISOString()`. |
+| `disableFuture` | boolean | Prevents selecting dates after today. |
+| `disablePast` | boolean | Prevents selecting dates before today. |
+| `readOnly` | boolean | Shows value but prevents editing. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `display` | expression | CSS display. |
+| `width` | expression | Field width. |
+| `height` | expression | Height override. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+| `flexDirection` | select | `row` · `column` · `row-reverse` · `column-reverse` |
+| `justifyContent` | select | `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between elements. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onChange` | action (custom) | Fires when the user selects a date. New value in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Date-of-birth, start date, end date, due date fields.
+- Booking/scheduling forms.
+- Filtering data by date range (use two datepickers with `minDate`/`maxDate` cross-linked).
+- Year-only or month-only selection via `views: year` or `views: month`.
+
+**When NOT to use:**
+- Time-only input → use `time`.
+- Date + time → combine `datepicker` + `time` or use a datetime field.
+- Read-only date display → use `label`.
+
+---
+
+## Schema Examples
+
+### Simple date field
+```json
+{
+  "type": "datepicker",
+  "props": {
+    "key": "birthDate",
+    "label": "Date of Birth",
+    "format": "DD/MM/YYYY",
+    "disableFuture": true,
+    "required": true
+  },
+  "style": { "width": "100%" }
+}
+```
+
+### Date range (start / end)
+```json
+{
+  "type": "datepicker",
+  "props": {
+    "key": "startDate",
+    "label": "Start Date",
+    "format": "YYYY-MM-DD",
+    "maxDate": "data.endDate"
+  }
+}
+```
+```json
+{
+  "type": "datepicker",
+  "props": {
+    "key": "endDate",
+    "label": "End Date",
+    "format": "YYYY-MM-DD",
+    "minDate": "data.startDate",
+    "disablePast": true
+  }
+}
+```
+
+### Month/year picker only
+```json
+{
+  "type": "datepicker",
+  "props": {
+    "key": "reportMonth",
+    "label": "Report Month",
+    "views": "month",
+    "openTo": "month",
+    "format": "MM/YYYY"
+  }
+}
+```
+
+### Read-only display
+```json
+{
+  "type": "datepicker",
+  "props": {
+    "key": "createdAt",
+    "label": "Created",
+    "value": "data.record.createdAt",
+    "readOnly": true,
+    "format": "DD MMM YYYY"
+  }
+}
+```

package/training/05-radio.md

@@ -0,0 +1,123 @@
+# Component: radio
+
+A group of radio buttons for mutually exclusive selection. Ideal for 2–6 options visible at once.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Selected value stored in `data[key]` and `form[key]`. |
+| `label` | expression | Group label shown above/beside the buttons. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks the group required. |
+| `value` | expression | Controlled selected value, e.g. `data.gender`. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables all radio buttons. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `options` | options-editor | List of `{ label, value }` pairs defining the choices. |
+| `row` | boolean | `true` renders buttons horizontally (inline). Default is vertical stack. |
+
+---
+
+## Props — Style Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `display` | expression | CSS display. |
+| `width` | expression | Wrapper width. |
+| `height` | expression | Wrapper height. |
+| `margin` | expression | Outer margin. |
+| `padding` | expression | Inner padding. |
+| `flexDirection` | select | `row` · `column` · `row-reverse` · `column-reverse` |
+| `justifyContent` | select | `flex-start` · `center` · `flex-end` · `space-between` · `space-around` · `space-evenly` |
+| `alignItems` | select | `flex-start` · `center` · `flex-end` · `stretch` · `baseline` |
+| `gap` | expression | Gap between options. |
+
+---
+
+## Props — Actions Tab
+
+| Event | Type | Notes |
+|-------|------|-------|
+| `onChange` | action (custom) | Fires when the user selects a different option. New value in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Mutually exclusive options where all choices should be visible: gender, payment method, priority level.
+- Small option sets (2–5 items). Larger sets → use `dropdown`.
+- Survey-style questions.
+
+**When NOT to use:**
+- More than 5–6 options → use `dropdown`.
+- Boolean yes/no that looks like a switch → use `toggle`.
+- Multi-selection → use `checkbox` group or `dropdown multiple`.
+
+---
+
+## Schema Examples
+
+### Horizontal radio group
+```json
+{
+  "type": "radio",
+  "props": {
+    "key": "gender",
+    "label": "Gender",
+    "required": true,
+    "row": true,
+    "options": [
+      { "label": "Male", "value": "male" },
+      { "label": "Female", "value": "female" },
+      { "label": "Other", "value": "other" }
+    ]
+  }
+}
+```
+
+### Vertical with controlled value
+```json
+{
+  "type": "radio",
+  "props": {
+    "key": "priority",
+    "label": "Priority",
+    "value": "data.task.priority",
+    "color": "primary",
+    "options": [
+      { "label": "Low", "value": "low" },
+      { "label": "Medium", "value": "medium" },
+      { "label": "High", "value": "high" },
+      { "label": "Critical", "value": "critical" }
+    ]
+  }
+}
+```
+
+### With onChange
+```json
+{
+  "type": "radio",
+  "props": {
+    "key": "paymentMethod",
+    "label": "Payment Method",
+    "row": true,
+    "options": [
+      { "label": "Credit Card", "value": "card" },
+      { "label": "Bank Transfer", "value": "bank" },
+      { "label": "Cash", "value": "cash" }
+    ]
+  },
+  "actions": {
+    "onChange": {
+      "type": "custom",
+      "code": "setData({ showCardForm: form.paymentMethod === 'card' })"
+    }
+  }
+}
+```