robobyte-front-builder 1.0.26 → 1.0.27

package/docs/printLayout.md

@@ -0,0 +1,405 @@
+# Print Layouts — Calling Them From Host-App Code
+
+> **Scope.** This document covers triggering a print layout **from outside the UI Builder** — from a regular page, action handler, dialog, hook, or anywhere else in host-app code.
+>
+> The layout *itself* is designed in the **Print Layout Builder** at `/printBuilder` and persisted via the backend. This guide only covers how the host renders + prints a saved layout, not how to design one.
+>
+> If you're triggering print from inside the builder's Calculation runtime (`actionsConfig.code`, `viewerActions.code`, `onSubmit`, etc.), use the auto-injected `openPrintLayout(layoutId, data)` — see [`training/49-printLayout.md`](../training/49-printLayout.md) for the full Calculation-scope reference (data shape, when to fire, recipes for row / viewer / form-submit triggers, pitfalls). This doc is for everything else: regular host-app React, dialogs, hooks, pages outside any builder context.
+
+---
+
+## 1. Quick start
+
+```jsx
+import { useRef } from 'react'
+import PrintDialog from 'views/builder/viewer/PrintDialog'
+
+export default function InvoicesPage() {
+  // 1. Allocate a ref the dialog will register itself on.
+  const printDialogRef = useRef(null)
+
+  // 2. Build the minimum viewerContext the dialog needs.
+  const viewerContext = {
+    printDialogRef,
+    data: {},        // becomes printData inside the layout
+    setData: () => {},
+    form: {},
+    setForm: () => {},
+    mode: 'preview',
+    isEditMode: false,
+    isPreviewMode: true,
+    isPrintContext: true,
+  }
+
+  // 3. Mount the dialog once. It stays hidden until you open it.
+  // 4. Open it from anywhere with the saved layout id + the data the
+  //    layout should render against.
+  return (
+    <>
+      <Button
+        variant='contained'
+        onClick={() =>
+          printDialogRef.current?.open('invoice-layout-id', {
+            invoiceNumber: 'INV-1042',
+            customerName:  'Acme Corp',
+            lines: [{ sku: 'A', qty: 2 }, { sku: 'B', qty: 5 }],
+          })
+        }
+      >
+        Print Invoice
+      </Button>
+
+      <PrintDialog viewerContext={viewerContext} />
+    </>
+  )
+}
+```
+
+The dialog fetches the layout by `id`, renders the multi-zone preview, exposes a Print button, injects print CSS for `@page`, and on print fills in page numbers / clones fixed header & footer per page.
+
+---
+
+## 2. Prerequisites
+
+### 2.1 The layout exists on the backend
+
+You design the layout in the host app's `/printBuilder` (the page wrapper for `PrintBuilderPage`), give it a title, and save it. The backend persists it as `{ id, title, value: JSON-stringified-schema }` under `Endpoints.PrintLayout.*`. The dialog fetches it on `open(layoutId, data)`.
+
+### 2.2 `<RoboByteFrontBuilderProvider>` at app root
+
+`PrintDialog` uses `Services.GetService` to fetch the layout, which reads `apiURL` and `accessToken` from the provider. AG Grid (for `reportViewer` zones inside a layout) also reads its license from the provider. Without the provider, the fetch and any embedded grids fail silently.
+
+### 2.3 `next.config.js` bare-alias resolution
+
+The import path is bare-aliased — `views/builder/viewer/PrintDialog`. Your host's `next.config.js` `NormalModuleReplacementPlugin` resolves `views/*` to the package's source when the importing file is inside the package, and to the host's source otherwise. See [INTEGRATION.md](../INTEGRATION.md). When importing `PrintDialog` from **host** code, you need to point the alias at the package explicitly because the importing file is in the host tree.
+
+The simplest cross-tree import is to add this to your host's `package.json` `dependencies` and just import via package subpath:
+
+```js
+// works wherever next-transpile-modules is active
+import PrintDialog from 'robobyte-front-builder/src/views/builder/viewer/PrintDialog'
+```
+
+Or expose it from your host via `next.config.js`:
+
+```js
+// next.config.js — point bare 'views/builder/viewer/PrintDialog' at the package
+const packageOwned = [
+  'services/reportData/fetchReportData',
+  'views/builder/viewer/PrintDialog',     // ← add this
+]
+packageOwned.forEach(mod => {
+  config.plugins.push(
+    new NormalModuleReplacementPlugin(
+      new RegExp(`^${mod.replace(/\//g, '\\/')}(\\.jsx?)?$`),
+      resource => { resource.request = path.join(builderSrc, mod) }
+    )
+  )
+})
+```
+
+After that, `import PrintDialog from 'views/builder/viewer/PrintDialog'` works from any host file.
+
+---
+
+## 3. How it works
+
+The dialog is a **mounted-but-hidden** React component that exposes an imperative ref:
+
+```ts
+printDialogRef.current = {
+  open(layoutId: string, data?: object): void,        // fetch + open
+  openWithSchema(schema: object, data?: object): void, // open with a pre-loaded schema
+  close(): void,
+}
+```
+
+When `open(layoutId, data)` is called:
+
+1. The dialog calls `Endpoints.PrintLayout.Get.GetById?id=layoutId` and parses the schema.
+2. It stores `data` as the `printData` (read inside the layout as `data` in any Calculation / expression).
+3. It opens a full-screen `<Dialog>` showing a multi-page preview built by `PrintPreviewCanvas`, plus a "Print" button.
+4. Print CSS for `@page` (margins, paper size, header / footer height) is injected globally so `Ctrl+P` from inside the dialog respects the layout's settings.
+5. When the user clicks Print, the dialog closes, page numbers are filled in (`{page}` / `{pages}` tokens), fixed header / footer zones are cloned per body page, then `window.print()` is fired. An `afterprint` event listener cleans everything up.
+
+Because the print mechanism uses the browser's native `window.print()`, the user gets the OS print dialog — no PDF library, no server round-trip. Saving as PDF is just "Save to PDF" in the OS print dialog.
+
+---
+
+## 4. The `data` you pass to `open(...)`
+
+The second argument to `open` becomes the layout's `data` scope. Inside the layout (designed in the builder), expressions and Calculations read this object as `data`:
+
+```js
+// In the layout, a label component's text expression:
+data.invoiceNumber                                  // → 'INV-1042'
+data.lines.reduce((sum, l) => sum + l.qty, 0)      // → 7
+```
+
+There are no constraints on shape — pass whatever the layout's bindings expect. A typical pattern:
+
+```js
+printDialogRef.current.open('invoice-layout', {
+  // header
+  invoiceNumber: order.id,
+  invoiceDate:   formatDate(order.createdAt),
+  customerName:  order.customer.name,
+  customerAddr:  order.customer.address,
+
+  // body
+  lines:         order.lines,
+  subtotal:      order.subtotal,
+  tax:           order.tax,
+  total:         order.total,
+
+  // footer
+  notes:         order.notes,
+})
+```
+
+> **Tip.** Keep a clear contract between the layout designer and the caller. The layout's Settings tab has a "Test Data" JSON field — the designer uses that to preview against representative data; that same shape is what the caller should pass at runtime.
+
+---
+
+## 5. Three mounting patterns
+
+### 5.1 Mount per page (simplest)
+
+Allocate the ref + mount the dialog where you need it. Best when print is page-specific.
+
+```jsx
+function OrdersPage() {
+  const printDialogRef = useRef(null)
+  const ctx = {
+    printDialogRef,
+    data: {}, setData: () => {}, form: {}, setForm: () => {},
+    mode: 'preview', isEditMode: false, isPreviewMode: true, isPrintContext: true,
+  }
+
+  const printOrder = (order) =>
+    printDialogRef.current?.open('order-layout-id', { order })
+
+  return (
+    <>
+      <OrdersTable onPrint={printOrder} />
+      <PrintDialog viewerContext={ctx} />
+    </>
+  )
+}
+```
+
+### 5.2 Mount at app root (cleanest for multi-page apps)
+
+If you want `printLayout(id, data)` callable from anywhere, mount once at the `_app.js` level and put the ref + helper in a context.
+
+```jsx
+// host: contexts/PrintContext.jsx
+import { createContext, useContext, useRef, useCallback } from 'react'
+import PrintDialog from 'views/builder/viewer/PrintDialog'
+
+const PrintCtx = createContext({ openPrintLayout: () => {} })
+
+export function PrintProvider({ children }) {
+  const printDialogRef = useRef(null)
+
+  const openPrintLayout = useCallback((layoutId, data) => {
+    if (!printDialogRef.current) {
+      console.warn('[openPrintLayout] PrintDialog is not mounted yet')
+      return
+    }
+    printDialogRef.current.open(layoutId, data)
+  }, [])
+
+  const closePrintLayout = useCallback(() => {
+    printDialogRef.current?.close()
+  }, [])
+
+  const viewerContext = {
+    printDialogRef,
+    data: {}, setData: () => {}, form: {}, setForm: () => {},
+    mode: 'preview', isEditMode: false, isPreviewMode: true, isPrintContext: true,
+  }
+
+  return (
+    <PrintCtx.Provider value={{ openPrintLayout, closePrintLayout }}>
+      {children}
+      <PrintDialog viewerContext={viewerContext} />
+    </PrintCtx.Provider>
+  )
+}
+
+export const usePrintLayout = () => useContext(PrintCtx)
+```
+
+```jsx
+// host: pages/_app.js
+<RoboByteFrontBuilderProvider {...}>
+  <PrintProvider>
+    <Component {...pageProps} />
+  </PrintProvider>
+</RoboByteFrontBuilderProvider>
+```
+
+```jsx
+// any host page
+import { usePrintLayout } from '@/contexts/PrintContext'
+
+function InvoiceRow({ invoice }) {
+  const { openPrintLayout } = usePrintLayout()
+  return (
+    <Button onClick={() => openPrintLayout('invoice-layout', invoice)}>
+      Print
+    </Button>
+  )
+}
+```
+
+> This is the recommended pattern for any non-trivial host app — every page gets `usePrintLayout()` without re-mounting the dialog.
+
+### 5.3 With a preloaded schema (skip the fetch)
+
+If your host already has the layout's schema in memory — e.g. from a custom backend bundle, a fixture, or a recently-saved layout — bypass the API fetch and call `openWithSchema(schema, data)`:
+
+```jsx
+const someSchema = await fetch('/api/my-cached-layout').then(r => r.json())
+printDialogRef.current.openWithSchema(someSchema, { invoiceId: 42 })
+```
+
+This is what the Print Builder's "Test Print" button uses — the in-progress schema isn't on the server yet, so it gets pushed in directly.
+
+---
+
+## 6. Discovering and listing layouts
+
+If users should pick a layout at runtime, two paths:
+
+### 6.1 Embed the built-in `PrintLayoutsList` page
+
+```jsx
+import { PrintLayoutsList } from 'robobyte-front-builder'
+
+<PrintLayoutsList />
+```
+
+Renders the same list view as `/printBuilder/layouts` — browse, preview, delete.
+
+### 6.2 Roll your own with the endpoint
+
+```jsx
+import { Services, Endpoints } from 'services/Endpoints'
+
+async function loadLayouts() {
+  const r = await Services.GetService(Endpoints.PrintLayout.Get.GetAll, false, {})
+  return r?.data ?? []   // [{ id, title, value }, ...]
+}
+```
+
+`value` is the JSON-stringified schema. Pass `id` to `printDialogRef.current.open(id, data)` to render.
+
+---
+
+## 7. Recipes
+
+### 7.1 Print right after a save
+
+```js
+async function saveAndPrint(orderDraft) {
+  const r = await PostService(Endpoints.Orders.Post.Create, true, orderDraft)
+  if (r?.data) {
+    openPrintLayout('order-layout', { ...orderDraft, id: r.data.id })
+  }
+}
+```
+
+### 7.2 Print a filtered grid (no per-row template)
+
+For "print the report exactly as it is on screen", let the user click the **PDF export** icon in the report toolbar — it uses `jspdf-autotable` and respects current filters / columns. Use `openPrintLayout` only when you have a designed template the data should populate.
+
+### 7.3 Bulk print one layout per selected row
+
+```js
+function bulkPrint(rows) {
+  // Print one at a time — opening multiple PrintDialogs at once would race.
+  // Easiest pattern: concat into a single layout that accepts an array.
+  openPrintLayout('packing-slips', { slips: rows })
+}
+```
+
+The layout iterates `data.slips` via a `repeater` and the print engine paginates automatically.
+
+### 7.4 Programmatic close (e.g. cancel from a parent)
+
+```js
+printDialogRef.current?.close()
+// OR via the provider pattern:
+const { closePrintLayout } = usePrintLayout()
+closePrintLayout()
+```
+
+### 7.5 Print a layout from a `<reportViewer>` viewer action
+
+If you've wired the `PrintProvider` (section 5.2), pull `openPrintLayout` from the hook inside your `viewerActions` `onClick`:
+
+```jsx
+import { usePrintLayout } from '@/contexts/PrintContext'
+
+function OrdersReport() {
+  const { openPrintLayout } = usePrintLayout()
+  const [api, setApi] = useState(null)
+
+  const viewerActions = [
+    {
+      label: 'Print Selected',
+      icon:  'PrintOutlined',
+      variant: 'contained',
+      onClick: () => {
+        const selected = api?.getSelectedRows() ?? []
+        if (selected.length === 0) return
+        openPrintLayout('order-layout', { orders: selected })
+      },
+    },
+  ]
+
+  return (
+    <ReportViewer pageId='ORDERS' setOutGridApi={setApi} viewerActions={viewerActions} />
+  )
+}
+```
+
+---
+
+## 8. Pitfalls
+
+- **Ref not registered yet.** `PrintDialog` registers `printDialogRef.current` in a `useEffect` after mount. Calling `open()` before the first render completes throws "PrintDialog is not mounted". In practice this only matters for SSR — wrap calls in `useEffect` or `requestAnimationFrame` if you must trigger on first paint.
+- **Multiple mounted dialogs.** Each `<PrintDialog>` instance writes to its own ref. Mounting two with the same ref is undefined; mounting two with different refs is fine but you'll have stacking print CSS. Use the provider pattern (section 5.2) to enforce a single instance.
+- **Provider missing.** Without `<RoboByteFrontBuilderProvider>`, `Services.GetService` has no base URL or auth — the layout fetch fails silently and the dialog stays in its loading state.
+- **The `viewerContext` shape matters.** The dialog reads `printDialogRef` from it. The other fields (`data`, `setData`, `form`, …) are forwarded to every zone's render context. Pass at least the keys shown in section 1 — missing keys will show up as `undefined` inside the layout's expressions.
+- **`data` is the layout's runtime scope, not arbitrary metadata.** Inside the layout, every Calculation and expression reads `data.x`. If you pass `{ order: {...} }`, expressions need to write `data.order.x`. Match the shape the designer designed against.
+- **Saving as PDF is a browser print operation.** There's no programmatic "save to PDF" — it goes through the OS print dialog. Users on Chromium pick "Save as PDF"; users on Safari pick the print → PDF flow. If you need server-rendered PDFs, that's out of scope for this package.
+- **`@page` settings only kick in after the first `open` of a session.** The CSS is injected on schema load. If you change the layout's `settings.margins` and call `open` again, the new CSS replaces the old. Don't try to set `@page` from outside the layout.
+- **Print preview shows the AG Grid as a static HTML table.** When a layout includes a `reportViewer`, the print path fetches **all rows with `isPagination: false`** and renders a plain table (AG Grid virtualization breaks under `window.print()`). For very large reports, expect the print preview to take several seconds to populate.
+
+---
+
+## 9. Cheat sheet
+
+1. Import: `import PrintDialog from 'views/builder/viewer/PrintDialog'` (bare alias; add the package-owned plugin rule in `next.config.js` if you're importing from host code).
+2. Allocate `const printDialogRef = useRef(null)`.
+3. Mount `<PrintDialog viewerContext={{ printDialogRef, data: {}, setData: () => {}, form: {}, setForm: () => {}, mode: 'preview', isEditMode: false, isPreviewMode: true, isPrintContext: true }} />` once in your tree.
+4. Call `printDialogRef.current.open('layout-id', dataObject)` to fetch + show.
+5. Or `printDialogRef.current.openWithSchema(schema, dataObject)` if you already have the schema in memory.
+6. Call `printDialogRef.current.close()` to dismiss.
+7. For multi-page apps: wrap once in a `PrintProvider` and expose `usePrintLayout()` (section 5.2).
+8. The `dataObject` becomes `data` inside the layout — match the shape the designer designed against.
+
+---
+
+## Cross-references
+
+- **In-builder usage** (`openPrintLayout` auto-injected into Calculation scope): [`training/49-printLayout.md`](../training/49-printLayout.md). Also covered briefly in README's *Calculation Scope Reference* and *Print Layout Builder* sections.
+- **Designing layouts**: visit `/printBuilder` in the host app (the `PrintBuilderPage` re-export).
+- **Listing / managing saved layouts**: `<PrintLayoutsList />` (re-export), or roll your own via `Endpoints.PrintLayout.Get.GetAll`.
+- **Host-app integration**: [INTEGRATION.md](../INTEGRATION.md) for `next.config.js`, peer deps, provider setup.
+- **AG Grid theme customization** (relevant for `reportViewer` zones inside a print layout): README → *AG Grid theme*.
+- **`<ReportViewer>` host-app usage**: [docs/ReportViewer.md](./ReportViewer.md).
+- **`fetchReportDataByPageId` host-app usage**: [docs/fetchReportData.md](./fetchReportData.md).

package/package.json

@@ -1,7 +1,31 @@
 {
   "name": "robobyte-front-builder",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "RoboByte low-code UI builder, Report builder, and navigation extension system",
+  "keywords": [
+    "low-code",
+    "ui-builder",
+    "report-builder",
+    "print-layout",
+    "next.js",
+    "react",
+    "ag-grid",
+    "mui",
+    "drag-and-drop",
+    "schema-driven",
+    "form-builder",
+    "navigation"
+  ],
+  "homepage": "https://github.com/Hossny37/RoboByteFrontBuilder#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hossny37/RoboByteFrontBuilder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Hossny37/RoboByteFrontBuilder/issues"
+  },
+  "license": "MIT",
+  "author": "Hossny37",
   "main": "src/lib/index.js",
   "files": [
     "src",
@@ -9,7 +33,11 @@
     "styles",
     "next.config.js",
     "jsconfig.json",
+    "LICENSE",
     "INTEGRATION.md",
+    "docs",
+    "training/*.md",
+    "training/examples",
     "RoboByteBuilder_User_Manual.docx"
   ],
   "exports": {

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