robobyte-front-builder 1.0.25 → 1.0.27

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

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