robobyte-front-builder 1.0.26 → 1.0.28

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

package/training/06-number.md

@@ -0,0 +1,133 @@
+# Component: number
+
+A numeric input field with built-in formatting: currency, percentage, decimal, or custom mask patterns.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as a number 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, e.g. `data.price`. |
+| `placeholder` | text | Hint text shown when empty. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the field. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `formatType` | select | `decimal` · `currency` · `percentage` · `custom` — Controls how the number is formatted/displayed. |
+| `decimalScale` | expression | Number of decimal places, e.g. `2`. |
+| `fixedDecimalScale` | boolean | Always shows the decimal places (e.g. `10.00` instead of `10`). |
+| `thousandSeparator` | boolean | Adds comma separators every 3 digits (e.g. `1,000,000`). |
+| `currencySymbol` | text | Symbol shown when `formatType: currency`, e.g. `"$"`, `"€"`, `"AED"`. |
+| `prefix` | text | Text prefix before the number, e.g. `"$"` or `"+"`. |
+| `suffix` | text | Text suffix after the number, e.g. `"%"` or `" kg"`. |
+| `allowNegative` | boolean | Permits entering negative values. Default: `true`. |
+| `format` | text | Custom mask pattern, e.g. `"#### #### #### ####"` for credit card numbers. |
+
+---
+
+## 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 numeric value changes. New value in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Price, salary, quantity, or any numeric form field.
+- Currency amounts needing `$` prefix and thousands separator.
+- Percentage inputs with `%` suffix.
+- Masked formats like phone numbers, credit card numbers.
+
+**When NOT to use:**
+- Plain unformatted integer → a regular `input` may suffice.
+- Date/time values → use `datepicker` / `time`.
+
+---
+
+## Schema Examples
+
+### Currency field
+```json
+{
+  "type": "number",
+  "props": {
+    "key": "price",
+    "label": "Price",
+    "formatType": "currency",
+    "currencySymbol": "$",
+    "decimalScale": 2,
+    "fixedDecimalScale": true,
+    "thousandSeparator": true,
+    "required": true
+  },
+  "style": { "width": "100%" }
+}
+```
+
+### Percentage
+```json
+{
+  "type": "number",
+  "props": {
+    "key": "taxRate",
+    "label": "Tax Rate",
+    "formatType": "percentage",
+    "suffix": "%",
+    "decimalScale": 2,
+    "allowNegative": false
+  }
+}
+```
+
+### Credit card mask
+```json
+{
+  "type": "number",
+  "props": {
+    "key": "cardNumber",
+    "label": "Card Number",
+    "formatType": "custom",
+    "format": "#### #### #### ####",
+    "placeholder": "0000 0000 0000 0000"
+  }
+}
+```
+
+### Plain integer with separator
+```json
+{
+  "type": "number",
+  "props": {
+    "key": "quantity",
+    "label": "Quantity",
+    "formatType": "decimal",
+    "decimalScale": 0,
+    "thousandSeparator": true,
+    "allowNegative": false
+  }
+}
+```

package/training/07-textarea.md

@@ -0,0 +1,114 @@
+# Component: textarea
+
+A multi-line text input field. Auto-grows from a minimum row count up to `maxRows`.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value 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, e.g. `data.notes`. |
+| `placeholder` | text | Greyed hint text when empty. |
+| `rows` | number | Minimum visible rows (default: `4`). |
+| `maxRows` | number | Maximum rows before scrolling begins. Leave blank for unlimited growth. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the field. |
+| `enabled` | boolean | Enable/disable from an expression. |
+
+---
+
+## 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 content changes. |
+| `onBlur` | action (custom) | Fires when the field loses focus (useful for save-on-leave). |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Comments, notes, descriptions, addresses, bio fields.
+- Any multi-line plain text that does NOT need formatting.
+- Large text entries in forms.
+
+**When NOT to use:**
+- Rich text with bold/italic/lists → use `richtext`.
+- Single-line input → use `input`.
+- Code/JSON entry → use `input` or a code field.
+
+---
+
+## Schema Examples
+
+### Notes field
+```json
+{
+  "type": "textarea",
+  "props": {
+    "key": "notes",
+    "label": "Notes",
+    "placeholder": "Enter any additional notes...",
+    "rows": 4,
+    "maxRows": 10
+  },
+  "style": { "width": "100%" }
+}
+```
+
+### Description with limits
+```json
+{
+  "type": "textarea",
+  "props": {
+    "key": "description",
+    "label": "Description",
+    "required": true,
+    "rows": 3,
+    "maxRows": 6,
+    "placeholder": "Describe the issue in detail"
+  }
+}
+```
+
+### With onBlur auto-save
+```json
+{
+  "type": "textarea",
+  "props": {
+    "key": "memo",
+    "label": "Memo",
+    "rows": 5,
+    "value": "data.record.memo"
+  },
+  "actions": {
+    "onBlur": {
+      "type": "custom",
+      "code": "saveMemo({ id: data.record.id, memo: form.memo })"
+    }
+  }
+}
+```