robobyte-front-builder 1.0.26 → 1.0.28

package/src/lib/providers/RoboByteFrontBuilderProvider.jsx

@@ -46,10 +46,12 @@
 import { useEffect, useMemo } from 'react'
 import { useRouter } from 'next/router'
 import { Toaster } from 'react-hot-toast'
+import { ThemeProvider as MuiThemeProvider } from '@mui/material/styles'
 import { ModuleRegistry } from 'ag-grid-community'
 import { AllEnterpriseModule, LicenseManager } from 'ag-grid-enterprise'
 import { NavigationExtensionProvider } from '../navigation/NavigationExtensionContext'
 import { AgGridThemeProvider } from '../agGridThemeContext'
+import { buildMuiTheme, isResolvedMuiTheme, DEFAULT_MUI_THEME } from '../muiTheme'
 import { configureRoboByte } from '../../services/config'
 import { AuthContext } from '../../context/AuthContext'
 import { setRouter } from '../../services/routerRef'
@@ -107,6 +109,26 @@ const RoboByteFrontBuilderProvider = ({
    * pass a plain params object.
    */
   agGridTheme = null,
+  /**
+   * Optional MUI theme overrides applied to every component the package
+   * renders. Three accepted shapes:
+   *
+   *   1. nothing (default)         — uses DEFAULT_MUI_THEME from lib/muiTheme.js
+   *   2. theme options object      — deep-merged on top of the defaults, e.g.
+   *      muiTheme={{ palette: { primary: { main: '#6366f1' } }, shape: { borderRadius: 12 } }}
+   *   3. a pre-built MUI Theme     — used as-is (escape hatch for full control)
+   *
+   * The package mounts a `<MuiThemeProvider>` wrapping children with the
+   * resolved theme. Host apps with their own outer `<ThemeProvider>` should
+   * pass their theme options here so the package's internal components share
+   * the host's visual identity.
+   *
+   * Pass `disableMuiTheme={true}` to skip the inner ThemeProvider entirely —
+   * use this when the host has already wrapped the app in its own
+   * ThemeProvider and wants it to win without merging.
+   */
+  muiTheme = null,
+  disableMuiTheme = false,
   toasterProps = {},
 }) => {
   // Apply URL + endpoint config synchronously before any child renders.
@@ -130,7 +152,29 @@ const RoboByteFrontBuilderProvider = ({
     [user, accessToken]
   )
 
-  return (
+  // ── Resolve the MUI theme ────────────────────────────────────────────────
+  // Three cases:
+  //   - disableMuiTheme: no wrapping ThemeProvider; host provides its own
+  //   - muiTheme is a pre-built Theme: use as-is
+  //   - muiTheme is null OR an options object: deep-merge with defaults
+  // JSON.stringify keys the memo so a fresh `{ palette: { ... } }` literal
+  // each render doesn't rebuild the theme. Resolved Themes (case 2) are
+  // expected to be stable from the caller's side.
+  const resolvedMuiTheme = useMemo(() => {
+    if (disableMuiTheme) return null
+    if (isResolvedMuiTheme(muiTheme)) return muiTheme
+    if (!muiTheme) return DEFAULT_MUI_THEME
+    return buildMuiTheme(muiTheme)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [disableMuiTheme, isResolvedMuiTheme(muiTheme) ? muiTheme : JSON.stringify(muiTheme ?? null)])
+
+  // Wrapper helper — applies MuiThemeProvider conditionally based on flag.
+  const withMuiTheme = (node) =>
+    disableMuiTheme
+      ? node
+      : <MuiThemeProvider theme={resolvedMuiTheme}>{node}</MuiThemeProvider>
+
+  return withMuiTheme(
     <AuthContext.Provider value={authValue}>
       <NavigationExtensionProvider items={navExtensions}>
         <AgGridThemeProvider params={agGridTheme}>

package/src/pages/_app.js

@@ -31,6 +31,7 @@ export default function App({ Component, pageProps }) {
       user={DEV_USER}
       accessToken={DEV_ACCESS_TOKEN}
       agGridLicenseKey={process.env.NEXT_PUBLIC_AG_GRID_LICENSE_KEY}
+      agGridTheme={{ accentColor: '#3b82f6', headerHeight: 32 }}
     >
       {getLayout(<Component {...pageProps} />)}
     </RoboByteFrontBuilderProvider>

package/src/pages/printBuilder/index.jsx

@@ -11,30 +11,37 @@ import { Endpoints, Services } from 'services/Endpoints'
 import { PRINT_COMPONENT_SECTIONS } from 'views/builder/sidebar/tabs/Components/printComponentCatalog'
 import ComponentsTab from 'views/builder/sidebar/tabs/Components/ComponentsTab'
 import TreeTab from 'views/builder/sidebar/tabs/TreeTab'
-import { createTheme } from '@mui/material/styles'
+import { buildMuiTheme } from 'src/lib/muiTheme'
 
-// ── Builder themes (inlined to avoid cross-package path resolution issues) ────
+// ── Builder themes ────────────────────────────────────────────────────────────
+// Deep-merge with the package's DEFAULT_MUI_THEME_OPTIONS so every component
+// override (button polish, input focus halo, transitions, Inter typography,
+// soft shadows) is inherited. The builder UI only overrides palette.
 const _STORAGE_KEY = 'rbb:builderThemeMode'
 const BUILDER_THEMES = {
-  dark: createTheme({
-    palette: {
-      mode: 'dark',
-      primary:    { main: '#9c27b0' },
-      secondary:  { main: '#f5a623' },
-      background: { default: '#141618', paper: '#1e2227' },
-      divider:    '#3a3f45',
-      text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+  dark: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#141618', paper: '#1e2227' },
+        divider:    '#3a3f45',
+        text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+      },
     },
-  }),
-  light: createTheme({
-    palette: {
-      mode: 'light',
-      primary:   { main: '#9c27b0' },
-      secondary: { main: '#f5a623' },
-      background: { default: '#f0f2f5', paper: '#ffffff' },
-      divider:   '#dde1e7',
+    { mode: 'dark' }
+  ),
+  light: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#f0f2f5', paper: '#ffffff' },
+        divider:    '#dde1e7',
+      },
     },
-  }),
+    { mode: 'light' }
+  ),
 }
 function getBuilderThemeMode() {
   try { return localStorage.getItem(_STORAGE_KEY) === 'light' ? 'light' : 'dark' } catch { return 'dark' }

package/src/pages/viewBuilder/index.jsx

@@ -9,30 +9,40 @@ import { useRouter } from 'next/router'
 import { useEffect, useState } from 'react'
 import { Endpoints, Services } from 'services/Endpoints'
 import { ChevronLeft, ChevronRight } from '@mui/icons-material'
-import { createTheme } from '@mui/material/styles'
+import { buildMuiTheme } from 'src/lib/muiTheme'
 
-// ── Builder themes (inlined to avoid cross-package path resolution issues) ────
+// ── Builder themes ────────────────────────────────────────────────────────────
+// These deep-merge ON TOP of the package's DEFAULT_MUI_THEME_OPTIONS so every
+// component override (button polish, input focus halo, transitions, soft
+// shadows, Inter typography, …) is inherited. The builder UI just contributes
+// its own palette (purple primary, gold secondary, builder-specific surface
+// colors). Without this merge the builder pages used a bare-palette theme
+// and looked completely different from the rest of the package.
 const _STORAGE_KEY = 'rbb:builderThemeMode'
 const BUILDER_THEMES = {
-  dark: createTheme({
-    palette: {
-      mode: 'dark',
-      primary:    { main: '#9c27b0' },
-      secondary:  { main: '#f5a623' },
-      background: { default: '#141618', paper: '#1e2227' },
-      divider:    '#3a3f45',
-      text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+  dark: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#141618', paper: '#1e2227' },
+        divider:    '#3a3f45',
+        text:       { primary: '#e8eaed', secondary: '#9aa0aa' },
+      },
     },
-  }),
-  light: createTheme({
-    palette: {
-      mode: 'light',
-      primary:   { main: '#9c27b0' },
-      secondary: { main: '#f5a623' },
-      background: { default: '#f0f2f5', paper: '#ffffff' },
-      divider:   '#dde1e7',
+    { mode: 'dark' }
+  ),
+  light: buildMuiTheme(
+    {
+      palette: {
+        primary:    { main: '#9c27b0' },
+        secondary:  { main: '#f5a623' },
+        background: { default: '#f0f2f5', paper: '#ffffff' },
+        divider:    '#dde1e7',
+      },
     },
-  }),
+    { mode: 'light' }
+  ),
 }
 function getBuilderThemeMode() {
   try { return localStorage.getItem(_STORAGE_KEY) === 'light' ? 'light' : 'dark' } catch { return 'dark' }

package/training/00-index.md

@@ -0,0 +1,168 @@
+# RoboByte Front Builder — Component Training Reference
+
+Complete reference for all components. Use these files to train a local AI model to generate valid builder schemas.
+
+---
+
+## Schema Structure
+
+Every schema follows this structure:
+```json
+{
+  "root": { "type": "layout", "props": { "cols": 1 }, "children": [ ... ] },
+  "dialogs": [],
+  "actions": [],
+  "timers": []
+}
+```
+
+- **Root is always a `layout`** — never use `container` (banned).
+- Direct children of `layout` must be `layout-cell` nodes.
+- Each `layout-cell` contains one component (or a nested `layout` for complex layouts).
+
+### Prop Wrapping (internal)
+In the actual builder schema, props are wrapped in `{ valueType: 'value', value: ... }` objects. The AI generates **simplified** schemas (flat props), and the `schemaTransformer` wraps them automatically:
+
+```json
+// AI generates:
+{ "type": "input", "props": { "key": "name", "label": "Name" }, "style": { "width": "100%" } }
+
+// Builder stores internally:
+{ "id": "cmp_xxx", "type": "input", "props": { "main": { "key": { "valueType": "value", "value": "name" }, "label": { "valueType": "value", "value": "Name" } }, "style": { "width": { "valueType": "value", "value": "100%" } }, "advanced": {} }, "children": [] }
+```
+
+---
+
+## Component Categories
+
+### Field Components (Form Inputs)
+| File | Component | Purpose |
+|------|-----------|---------|
+| 01-input.md | `input` | Single-line text input |
+| 02-checkbox.md | `checkbox` | Boolean checkbox |
+| 03-dropdown.md | `dropdown` | Select from list |
+| 04-datepicker.md | `datepicker` | Date selection |
+| 05-radio.md | `radio` | Mutually exclusive options |
+| 06-number.md | `number` | Numeric input with formatting |
+| 07-textarea.md | `textarea` | Multi-line text |
+| 08-richtext.md | `richtext` | WYSIWYG HTML editor |
+| 09-tag.md | `tag` | Multi-value chip input |
+| 10-time.md | `time` | Time picker |
+| 11-toggle.md | `toggle` | On/off switch |
+| 12-signature.md | `signature` | Canvas signature pad |
+| 13-autocomplete.md | `autocomplete` | Searchable select with async |
+
+### Display Components
+| File | Component | Purpose |
+|------|-----------|---------|
+| 14-button.md | `button` | Action button (submit/reset/custom) |
+| 15-label.md | `label` | Body text display (MUI Typography) |
+| 16-header.md | `header` | Heading text h1–h6 |
+| 17-divider.md | `divider` | Horizontal/vertical separator line |
+| 18-image.md | `image` | Image from URL |
+| 19-link.md | `link` | Clickable hyperlink |
+| 20-banner.md | `banner` | Alert/notification banner |
+| 21-progress-circle.md | `progress-circle` | Circular progress indicator |
+| 22-progress-line.md | `progress-line` | Horizontal progress bar |
+| 23-menu.md | `menu` | Tab navigation bar |
+| 24-popover.md | `popover` | Floating panel triggered by button |
+
+### Structure Components
+| File | Component | Purpose |
+|------|-----------|---------|
+| 25-layout.md | `layout` | CSS Grid container (PRIMARY STRUCTURE) |
+| 26-layout-cell.md | `layout-cell` | Grid cell (child of layout) |
+| 27-card.md | `card` | MUI card with title/subheader |
+| 28-wizard.md | `wizard` | Multi-step stepper form |
+| 29-wizard-step.md | `wizard-step` | Single step inside wizard |
+| 30-repeater.md | `repeater` | Repeat template per data array item |
+| 31-dialog.md | `dialog` | Modal overlay |
+| 32-breadcrumb.md | `breadcrumb` | Navigation trail or step indicator |
+
+### Data Components
+| File | Component | Purpose |
+|------|-----------|---------|
+| 33-dataGrid.md | `dataGrid` | AG Grid editable table |
+| 34-dataTableViewer.md | `dataTableViewer` | Simple read-only HTML table |
+| 35-reportViewer.md | `reportViewer` | Server-fetched AG Grid report |
+| 36-viewRenderer.md | `viewRenderer` | Embed another saved view |
+| 37-treeView.md | `treeView` | Hierarchical tree component |
+
+### KPI Components
+| File | Component | Purpose |
+|------|-----------|---------|
+| 38-kpi-metric.md | `kpi-metric` | Single numeric KPI value |
+| 39-kpi-trend.md | `kpi-trend` | Delta/change with direction icon |
+| 40-kpi-badge.md | `kpi-badge` | Colored status chip/badge |
+| 41-kpi-statusDot.md | `kpi-statusDot` | Small status indicator dot |
+| 42-kpi-iconBox.md | `kpi-iconBox` | Boxed icon with threshold coloring |
+| 43-kpi-gauge.md | `kpi-gauge` | Semicircular arc gauge |
+| 44-kpi-bulletChart.md | `kpi-bulletChart` | Bullet chart (actual vs target) |
+| 45-kpi-colorScale.md | `kpi-colorScale` | Color-scale bar with markers |
+| 46-kpi-rating.md | `kpi-rating` | Star/heart/circle rating |
+| 47-kpi-countdown.md | `kpi-countdown` | Countdown timer to a target date |
+
+---
+
+## Universal Style Props (available on every component's style tab)
+
+Every component style tab supports two escape-hatch props for arbitrary CSS:
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `elementStyle` | expression | CSS **object** merged at highest priority onto the component wrapper. E.g. `{ outline: '2px solid #f00', transition: 'all 0.2s' }`. |
+| `elementCss` | expression | CSS **string** merged at highest priority. Use when you need shorthand syntax that's hard to express as a JS object. E.g. `"outline: 2px solid red; background: linear-gradient(135deg, #667eea, #764ba2)"`. |
+
+> `elementCss` takes effect after `elementStyle`. Both are processed and merged last, so they override ALL other style tab settings.
+
+---
+
+## Critical Rules
+
+1. **Root must be `layout`** — never `container` (banned).
+2. **`layout` children must be `layout-cell`** — no other components directly.
+3. **One component per cell** for multi-column layouts (`cols ≥ 2`). For single-column (`cols: 1`), cells can contain nested layouts.
+4. **Use `style` key** (not inside `props`) for layout-cell visual styling: `backgroundColor`, `padding`, `borderRadius`, `boxShadow`.
+5. **Use `props` key** for component behavior props: `key`, `label`, `value`, etc.
+6. **Data is accessed via expressions**: `data.fieldName`, `form.fieldName`, `dataItem.field` (inside repeater).
+7. **Dialogs are siblings of root**, not nested inside it.
+8. **KPI components are leaf nodes** — they have no children.
+
+---
+
+## Quick Decision Guide
+
+| Need | Component |
+|------|-----------|
+| Text input | `input` |
+| Multi-line text | `textarea` |
+| Rich formatted text | `richtext` |
+| Number with formatting | `number` |
+| Date | `datepicker` |
+| Time | `time` |
+| Yes/No toggle | `toggle` or `checkbox` |
+| Select one from list | `dropdown` (small list) or `autocomplete` (large/async) |
+| Select multiple | `dropdown` + `multiple: true` or `tag` |
+| Select mutually exclusive (visible) | `radio` |
+| Signature capture | `signature` |
+| Display text | `label` |
+| Display heading | `header` |
+| Display number/metric | `kpi-metric` |
+| Display status | `kpi-badge` or `kpi-statusDot` |
+| Display trend | `kpi-trend` |
+| Display gauge | `kpi-gauge` |
+| Display progress | `progress-line` or `progress-circle` |
+| Display table (static) | `dataTableViewer` |
+| Display table (server) | `reportViewer` |
+| Editable table | `dataGrid` |
+| Tree hierarchy | `treeView` |
+| Embed another view | `viewRenderer` |
+| Repeat a template | `repeater` |
+| Multi-step form | `wizard` + `wizard-step` |
+| Tabs | `menu` |
+| Modal | `dialog` |
+| Floating panel | `popover` |
+| Navigation trail | `breadcrumb` |
+| Alert/notification | `banner` |
+| Action button | `button` |
+| Page structure | `layout` + `layout-cell` |

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