robobyte-front-builder 1.0.26 → 1.0.27

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

package/training/08-richtext.md

@@ -0,0 +1,112 @@
+# Component: richtext
+
+A WYSIWYG rich text editor (SunEditor). Supports bold, italic, lists, tables, and custom toolbars. Value is stored as HTML string.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as HTML string in `data[key]` and `form[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled HTML value, e.g. `data.article.body`. |
+| `placeholder` | text | Hint shown when editor is empty. |
+| `disabled` | boolean | Disables the editor. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `height` | text | Editor height including toolbar, e.g. `"300px"`, `"500px"`. |
+| `mode` | select | `classic` — full toolbar above. `inline` — toolbar appears on text selection. `balloon` — compact balloon toolbar on selection. `balloon-always` — balloon always visible. |
+| `toolbar` | expression | Array of toolbar button names to include. If blank, shows default full toolbar. E.g. `['bold', 'italic', 'list', 'table']`. |
+| `resizingBar` | boolean | Shows a draggable bar at the bottom to resize the editor height. |
+| `showPathLabel` | boolean | Shows the HTML path breadcrumb at the bottom. |
+| `charCounter` | boolean | Displays a character count indicator. |
+| `maxCharCount` | expression | Maximum allowed characters. Enforces a hard limit when set. |
+
+---
+
+## Props — Style Tab
+
+Uses common input style fields:
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` |
+| `display` | expression | CSS display. |
+| `width` | expression | Field width. |
+| `height` | expression | Wrapper height. |
+| `margin` | expression | Outer spacing. |
+| `padding` | expression | Inner padding. |
+
+---
+
+## Props — Actions Tab
+
+No actions defined for richtext by default. Use the `onChange` pattern via a wrapping form or custom logic.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Article body, blog post content, email templates.
+- Product descriptions needing formatting.
+- Policy/documentation editors.
+- Any case where HTML output is needed.
+
+**When NOT to use:**
+- Plain text notes → use `textarea`.
+- Code entry → use a code editor field.
+- Short single-line text → use `input`.
+
+---
+
+## Schema Examples
+
+### Full classic editor
+```json
+{
+  "type": "richtext",
+  "props": {
+    "key": "articleBody",
+    "label": "Article Body",
+    "required": true,
+    "height": "400px",
+    "mode": "classic",
+    "resizingBar": true,
+    "charCounter": true,
+    "maxCharCount": 5000
+  },
+  "style": { "width": "100%" }
+}
+```
+
+### Inline mode with minimal toolbar
+```json
+{
+  "type": "richtext",
+  "props": {
+    "key": "emailTemplate",
+    "label": "Email Body",
+    "height": "250px",
+    "mode": "inline",
+    "toolbar": "['bold', 'italic', 'underline', 'list', 'link']",
+    "showPathLabel": false
+  }
+}
+```
+
+### Read-only display (disabled)
+```json
+{
+  "type": "richtext",
+  "props": {
+    "key": "policyContent",
+    "label": "Policy",
+    "value": "data.policy.content",
+    "disabled": true,
+    "height": "300px"
+  }
+}
+```

package/training/09-tag.md

@@ -0,0 +1,110 @@
+# Component: tag
+
+A multi-value chip/tag input. Users can select from a predefined list and/or type custom tags (freeSolo mode). Value is an array.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as an array in `data[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled array value, e.g. `data.selectedTags`. |
+| `placeholder` | text | Hint shown when no tags selected. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the tag input. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `options` | options-editor | Predefined `{ label, value }` pairs to suggest. Can also be bound to `data.tagList`. |
+| `freeSolo` | boolean | `true` allows users to type and add arbitrary tags not in the options list. |
+
+---
+
+## 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 | Wrapper height. |
+| `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 tags are added or removed. New array in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Multi-value selection where values render as chips: skills, categories, labels, interests.
+- Keyword/tag fields where users define custom values (`freeSolo: true`).
+- Filtering systems with multiple concurrent tags.
+
+**When NOT to use:**
+- Single selection → use `dropdown`.
+- Mutually exclusive options → use `radio`.
+- Large structured lists → use `autocomplete` or `dropdown multiple`.
+
+---
+
+## Schema Examples
+
+### Tag field with predefined options
+```json
+{
+  "type": "tag",
+  "props": {
+    "key": "skills",
+    "label": "Skills",
+    "options": [
+      { "label": "JavaScript", "value": "js" },
+      { "label": "Python", "value": "py" },
+      { "label": "React", "value": "react" },
+      { "label": "SQL", "value": "sql" }
+    ],
+    "placeholder": "Select skills..."
+  },
+  "style": { "width": "100%" }
+}
+```
+
+### Free-text tags (no predefined list)
+```json
+{
+  "type": "tag",
+  "props": {
+    "key": "keywords",
+    "label": "Keywords",
+    "freeSolo": true,
+    "placeholder": "Type and press Enter to add"
+  }
+}
+```
+
+### Pre-filled with data
+```json
+{
+  "type": "tag",
+  "props": {
+    "key": "categories",
+    "label": "Categories",
+    "value": "data.item.categories",
+    "options": "data.allCategories",
+    "size": "small"
+  }
+}
+```

package/training/10-time.md

@@ -0,0 +1,107 @@
+# Component: time
+
+A time picker field with clock popup. Supports 12-hour AM/PM and 24-hour formats, and configurable minute steps.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as time string in `data[key]`. |
+| `label` | expression | Label text. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled value, e.g. `data.appointmentTime`. |
+| `placeholder` | text | Hint shown when empty, e.g. `"HH:MM"`. |
+| `size` | select | `small` · `medium` · `large` |
+| `disabled` | boolean | Disables the field. |
+| `enabled` | boolean | Enable/disable from an expression. |
+| `ampm` | boolean | `true` shows 12-hour clock with AM/PM. `false` (default) uses 24-hour. |
+| `minutesStep` | expression | Step size for minute selection, e.g. `5`, `15`, `30`. Default: `1`. |
+| `readOnly` | boolean | Displays 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 time changes. New value in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Appointment time, shift start/end, schedule entry fields.
+- Time-only selection when date is handled separately.
+- Meeting booking with quarter-hour steps (`minutesStep: 15`).
+
+**When NOT to use:**
+- Date-only → use `datepicker`.
+- Duration entry (hours + minutes as a number) → use `number`.
+
+---
+
+## Schema Examples
+
+### 24-hour time field
+```json
+{
+  "type": "time",
+  "props": {
+    "key": "startTime",
+    "label": "Start Time",
+    "required": true,
+    "ampm": false,
+    "minutesStep": 15,
+    "placeholder": "HH:MM"
+  }
+}
+```
+
+### 12-hour AM/PM
+```json
+{
+  "type": "time",
+  "props": {
+    "key": "appointmentTime",
+    "label": "Appointment Time",
+    "ampm": true,
+    "minutesStep": 30
+  },
+  "style": { "width": "200px" }
+}
+```
+
+### Read-only
+```json
+{
+  "type": "time",
+  "props": {
+    "key": "closingTime",
+    "label": "Closing Time",
+    "value": "data.store.closingTime",
+    "readOnly": true,
+    "ampm": false
+  }
+}
+```

package/training/11-toggle.md

@@ -0,0 +1,108 @@
+# Component: toggle
+
+A Material UI Switch rendered as a sliding toggle. Boolean on/off, with color variants.
+
+---
+
+## Props — Main Tab
+
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `key` | expression | Unique identifier. Value stored as boolean in `data[key]`. |
+| `label` | expression | Label text shown next to the toggle. |
+| `labelPosition` | select | `top` · `left` · `right` · `none` |
+| `required` | boolean | Marks field required. |
+| `value` | expression | Controlled boolean value, e.g. `data.settings.darkMode`. |
+| `size` | select | `small` · `medium` · `large` |
+| `color` | select | `default` · `primary` · `secondary` · `error` · `warning` · `info` · `success` — Color of the toggle when ON. |
+| `disabled` | boolean | Prevents toggling. |
+| `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 | Wrapper width. |
+| `height` | expression | Wrapper height. |
+| `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 toggle state changes. New boolean value in `form[key]`. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- On/Off feature flags: dark mode, notifications, maintenance mode.
+- Settings panels with instant effect toggles.
+- Any boolean that benefits from the visual "switch" metaphor over a checkbox.
+
+**When NOT to use:**
+- Needs confirmation before applying → use `checkbox` + a save button.
+- Multiple mutually exclusive options → use `radio`.
+- Multi-select → use `tag` or `dropdown multiple`.
+
+---
+
+## Schema Examples
+
+### Feature toggle
+```json
+{
+  "type": "toggle",
+  "props": {
+    "key": "notifications",
+    "label": "Enable Notifications",
+    "color": "primary",
+    "size": "medium",
+    "value": "data.settings.notifications"
+  }
+}
+```
+
+### With onChange (immediate effect)
+```json
+{
+  "type": "toggle",
+  "props": {
+    "key": "darkMode",
+    "label": "Dark Mode",
+    "color": "secondary"
+  },
+  "actions": {
+    "onChange": {
+      "type": "custom",
+      "code": "setTheme(form.darkMode ? 'dark' : 'light')"
+    }
+  }
+}
+```
+
+### Disabled read-only status
+```json
+{
+  "type": "toggle",
+  "props": {
+    "key": "isVerified",
+    "label": "Verified",
+    "value": "data.user.isVerified",
+    "color": "success",
+    "disabled": true
+  }
+}
+```