robobyte-front-builder 1.0.26 → 1.0.28

package/training/49-printLayout.md

@@ -0,0 +1,215 @@
+# Helper: `openPrintLayout` / `closePrintLayout` — Calculation-scope Reference Manual
+
+> **Audience.** AI sessions emitting builder Calculation code (`actionsConfig.code`, `viewerActions.code`, button `onClick`, `onSubmit`, `onLoad`, column functions, etc.). The two helpers below are **auto-injected** into every Calculation scope — you never `import` them in a builder schema.
+
+Triggers a saved print layout from inside any Calculation. The layout itself is designed in the **Print Layout Builder** at `/printBuilder` and persisted on the backend; this helper fetches it by id, renders the multi-zone preview, and lets the user fire `window.print()` with the data you pass.
+
+> ⚠️ **Different from `<reportViewer>` PDF export.** The toolbar's PDF icon prints the current grid view as-is. `openPrintLayout` renders a **designed template** (multi-page, header/footer, page numbers, mixed components) populated by the data you pass.
+
+---
+
+## 1. Quick start
+
+```js
+openPrintLayout('invoice-layout-id', {
+  invoiceNumber: data.invoiceNumber,
+  customerName:  data.customer.name,
+  lines:         data.lines,
+})
+```
+
+That's it. The dialog opens, fetches the layout, renders preview, user clicks Print, OS print dialog appears. No `await` — fire-and-forget.
+
+---
+
+## 2. Signature
+
+Both helpers are auto-injected into the Calculation scope. No import.
+
+```ts
+openPrintLayout(layoutId: string, data?: object): void
+closePrintLayout(): void
+```
+
+- `layoutId` — string id from the saved layout (the value the designer copies from `/printBuilder/layouts`).
+- `data` — plain JS object made available inside the layout as `data` (see section 3).
+
+Returns nothing. Errors are logged to the console and surfaced via `react-hot-toast` if the layout id is unknown — no try/catch needed in your Calculation.
+
+---
+
+## 3. The `data` you pass
+
+The second argument becomes the layout's `data` scope. Inside the layout's expressions and Calculations, the values you pass read back as `data.x`.
+
+```js
+// Pass:
+openPrintLayout('invoice', {
+  invoiceNumber: 'INV-1042',
+  customer:      { name: 'Acme Corp', address: '1 Main St' },
+  lines:         [{ sku: 'A', qty: 2 }, { sku: 'B', qty: 5 }],
+})
+
+// Inside the layout's expressions / Calculations:
+data.invoiceNumber                                      // → 'INV-1042'
+data.customer.name                                      // → 'Acme Corp'
+data.lines.reduce((sum, l) => sum + l.qty, 0)          // → 7
+```
+
+The contract is whatever the layout's designer designed against. In the Print Layout Builder's *Settings* tab, the **Test Data** JSON field shows the shape the designer used for preview — your call site should pass the same shape.
+
+---
+
+## 4. When to call it
+
+| Trigger | Where it lives in the schema |
+|---|---|
+| Toolbar button on a `reportViewer` | `viewerActions[N].code` |
+| Row action button | `actionsConfig[N].code` |
+| Form submit (`onSubmit`) | `actions[N].code` with `event: 'onSubmit'` |
+| After a `*Service` call succeeds | inside any action `code` |
+| On load (rare — prints automatically on page open) | `actions[N].code` with `event: 'onLoad'` |
+| Page-level button click | `button` component's `onClick.code` |
+
+There's no rule preventing you from firing it from any Calculation, but the typical pattern is "user action → fetch / mutate → print".
+
+---
+
+## 5. Recipes
+
+### 5.1 Print a single record from a row action
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "invoices",
+    "pageId": "INVOICE_LIST",
+    "actionsConfig": [
+      {
+        "label": "Print Invoice",
+        "icon":  "PrintOutlined",
+        "color": "primary",
+        "variant": "text",
+        "code": "openPrintLayout('invoice-layout', { invoice: rowData })"
+      }
+    ]
+  }
+}
+```
+
+Inside `actionsConfig.code`, `rowData` is the current AG Grid row — pass it straight to the layout.
+
+### 5.2 Print after saving a form
+
+```js
+async function Calculation(form, data, setData) {
+  const r = await PostService(Endpoints.Orders.Post.Create, true, form)
+  if (!r) return
+  // r.data is the new order id
+  showToast('Order created', 'success')
+  openPrintLayout('order-layout', { ...form, id: r.data })
+}
+```
+
+### 5.3 Print all selected rows as one document
+
+If your layout uses a `repeater` over `data.rows`, you can hand the whole array in:
+
+```js
+async function Calculation(form, data, setData, dataRef, reportRefs) {
+  // Pull the selected rows from the report's grid API.
+  // The report's nodeName is its `key` ("invoices" below).
+  const api = reportRefs['invoices']?.current?.api
+  const selected = api?.getSelectedRows?.() ?? []
+  if (selected.length === 0) { showToast('Select at least one row', 'warning'); return }
+  openPrintLayout('invoices-batch-layout', { rows: selected })
+}
+```
+
+### 5.4 Print with filters applied
+
+When the layout includes a `reportViewer` zone (e.g. an itemized list inside a header), pass the filter object so the print render fetches only the right rows:
+
+```js
+function Calculation(form, data) {
+  openPrintLayout('sales-report', {
+    title:  `Sales — ${data.year}`,
+    filter: {
+      Tfilter: [
+        { path: 'Year', value: data.year, method: 'Equal' },
+      ],
+    },
+  })
+}
+```
+
+Inside the layout, the `reportViewer` zone's `filter` prop binds to `data.filter`.
+
+### 5.5 Conditional layout — pick one of several at runtime
+
+```js
+function Calculation(form, data) {
+  const layoutId = data.invoiceType === 'B2B'
+    ? 'invoice-b2b-layout'
+    : 'invoice-b2c-layout'
+  openPrintLayout(layoutId, { invoice: data.invoice })
+}
+```
+
+### 5.6 Close the dialog programmatically (rare)
+
+```js
+// e.g. when an external event invalidates the open print preview
+closePrintLayout()
+```
+
+Usually the user closes it themselves via the dialog's Close button or by completing the print.
+
+### 5.7 Open print from a viewer-action button
+
+```json
+{
+  "type": "reportViewer",
+  "props": {
+    "key": "orders",
+    "pageId": "ORDER_LIST",
+    "viewerActions": [
+      {
+        "label": "Print Today's Orders",
+        "icon":  "PrintOutlined",
+        "variant": "contained",
+        "code": "openPrintLayout('daily-orders', { date: new Date().toISOString().slice(0,10) })"
+      }
+    ]
+  }
+}
+```
+
+The action runs **without** a row context (`rowData` is not in scope for viewer actions).
+
+---
+
+## 6. Pitfalls
+
+- **Wrong `layoutId`.** The id must match a saved layout. A typo silently fails — the dialog opens, the fetch errors, the dialog stays in the loading state. Test in `/printBuilder/layouts` first; copy the id from there.
+- **Wrong `data` shape.** The layout reads `data.x` for whatever fields the designer used. If the designer wrote `data.invoiceNumber` and you pass `{ number: ... }`, you'll see blank cells. Mirror the **Test Data** JSON in the layout's Settings tab.
+- **No `await`.** `openPrintLayout` is fire-and-forget. Adding `await` is a no-op and may confuse a reader — the dialog handles its own lifecycle.
+- **Trying to gate on print completion.** There's no callback. The print outcome lives in the OS print dialog. If you need post-print behavior (e.g. mark as printed), handle it in your Save / Approve action right *before* calling `openPrintLayout`, not after.
+- **`reportViewer` zones inside a layout fetch ALL rows.** AG Grid virtualization breaks under `window.print()`, so the print path uses `isPagination: false` and renders a static HTML table. For huge datasets the preview may take seconds to populate — pass a filter that scopes the rows tightly.
+- **Calling it during `onLoad`.** Triggering print as soon as a view opens is jarring UX. Use it sparingly (e.g. a dedicated "/print/[id]" page that auto-prints and closes).
+- **Multiple opens at once.** Calling `openPrintLayout` again while the dialog is already open replaces the content. To print several layouts back-to-back, concat them into a single layout with a `repeater` instead.
+- **Calling outside Calculation scope.** `openPrintLayout` is only auto-injected into Calculation code. If you write a non-Calculation context (e.g. a raw `valueGetter` string on a colDef), it won't be defined — use a row-action `code` instead.
+
+---
+
+## 7. Cheat sheet
+
+1. `openPrintLayout(layoutId, data)` — fires the print dialog. No `await`. No try/catch.
+2. `closePrintLayout()` — closes it programmatically. Rarely needed.
+3. `data` becomes the layout's runtime `data` scope — match the shape from the layout's Test Data.
+4. From a **row action**, `rowData` is in scope — pass it as-is or shape it: `{ invoice: rowData }`.
+5. From a **viewer action**, `rowData` is **not** in scope — use `data`, `form`, `reportRefs`, or selected rows via `reportRefs[key]?.current?.api?.getSelectedRows()`.
+6. To pick a layout at runtime: build `layoutId` from a conditional and pass it.
+7. The dialog's render path fetches **all** rows of any embedded `reportViewer` zone — scope filters tightly for large datasets.
+8. Companion host-app docs (for non-Calculation callers): [`docs/printLayout.md`](../docs/printLayout.md).

package/training/examples/01-login-form.json

@@ -0,0 +1,176 @@
+{
+  "description": "Simple login form with email, password, remember me checkbox, and submit button",
+  "components_used": ["layout", "layout-cell", "header", "label", "input", "checkbox", "button", "link", "divider"],
+  "root": {
+    "type": "layout",
+    "props": { "cols": 1, "gap": 0, "rowGap": 0 },
+    "style": {},
+    "children": [
+      {
+        "type": "layout-cell",
+        "props": {},
+        "style": {
+          "backgroundColor": "#ffffff",
+          "borderRadius": "12px",
+          "boxShadow": "0 4px 24px rgba(0,0,0,0.12)",
+          "padding": "40px",
+          "maxWidth": "420px",
+          "width": "100%",
+          "alignItems": "center"
+        },
+        "children": [
+          {
+            "type": "layout",
+            "props": { "cols": 1, "rowGap": 20 },
+            "children": [
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "alignItems": "center", "padding": "0 0 8px 0" },
+                "children": [
+                  {
+                    "type": "header",
+                    "props": {
+                      "text": "Welcome Back",
+                      "variant": "h4",
+                      "component": "h1",
+                      "align": "center",
+                      "color": "textPrimary"
+                    }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "input",
+                    "props": {
+                      "key": "email",
+                      "label": "Email Address",
+                      "labelPosition": "top",
+                      "required": true,
+                      "placeholder": "you@example.com",
+                      "prefix": "EmailOutlined",
+                      "size": "medium"
+                    },
+                    "style": { "width": "100%", "color": "primary" }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "input",
+                    "props": {
+                      "key": "password",
+                      "label": "Password",
+                      "labelPosition": "top",
+                      "required": true,
+                      "placeholder": "Enter your password",
+                      "prefix": "LockOutlined",
+                      "suffix": "VisibilityOutlined",
+                      "size": "medium"
+                    },
+                    "style": { "width": "100%", "color": "primary" }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "justifyContent": "space-between", "alignItems": "center" },
+                "children": [
+                  {
+                    "type": "checkbox",
+                    "props": {
+                      "key": "rememberMe",
+                      "label": "Remember me",
+                      "labelPosition": "right",
+                      "size": "small"
+                    }
+                  },
+                  {
+                    "type": "link",
+                    "props": {
+                      "text": "Forgot password?",
+                      "href": "/forgot-password",
+                      "color": "primary",
+                      "variant": "body2",
+                      "underline": "hover"
+                    }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "button",
+                    "props": {
+                      "label": "Sign In",
+                      "variant": "contained",
+                      "color": "primary",
+                      "fullWidth": true,
+                      "size": "large"
+                    },
+                    "actions": {
+                      "onClick": { "type": "submit" }
+                    }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "divider",
+                    "props": { "text": "OR", "orientation": "horizontal", "variant": "middle", "textAlign": "center" }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "justifyContent": "center", "alignItems": "center" },
+                "children": [
+                  {
+                    "type": "label",
+                    "props": {
+                      "text": "Don't have an account?",
+                      "variant": "body2",
+                      "color": "textSecondary",
+                      "align": "center"
+                    }
+                  },
+                  {
+                    "type": "link",
+                    "props": {
+                      "text": "Sign up",
+                      "href": "/register",
+                      "color": "primary",
+                      "variant": "body2",
+                      "underline": "hover"
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "dialogs": [],
+  "actions": [],
+  "timers": []
+}

package/training/examples/02-contact-form.json

@@ -0,0 +1,141 @@
+{
+  "description": "Simple contact us form with name, email, subject dropdown, message textarea, and submit",
+  "components_used": ["layout", "layout-cell", "header", "label", "input", "dropdown", "textarea", "button", "banner"],
+  "root": {
+    "type": "layout",
+    "props": { "cols": 1, "rowGap": 0 },
+    "children": [
+      {
+        "type": "layout-cell",
+        "props": {},
+        "style": { "padding": "32px", "backgroundColor": "#ffffff", "borderRadius": "8px", "boxShadow": "0 2px 12px rgba(0,0,0,0.08)" },
+        "children": [
+          {
+            "type": "layout",
+            "props": { "cols": 1, "rowGap": 24 },
+            "children": [
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  { "type": "header", "props": { "text": "Contact Us", "variant": "h5", "component": "h1", "color": "textPrimary", "gutterBottom": false } }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "banner",
+                    "props": {
+                      "key": "successMsg",
+                      "message": "Your message was sent! We'll get back to you within 24 hours.",
+                      "severity": "success",
+                      "variant": "outlined",
+                      "open": "data.submitted",
+                      "dismissible": true,
+                      "icon": true
+                    },
+                    "actions": {
+                      "onClose": { "type": "custom", "code": "setData({ submitted: false })" }
+                    }
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": {},
+                "children": [
+                  {
+                    "type": "layout",
+                    "props": { "cols": 2, "gap": 16, "rowGap": 16 },
+                    "children": [
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "input", "props": { "key": "firstName", "label": "First Name", "required": true, "size": "medium" }, "style": { "width": "100%" } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "input", "props": { "key": "lastName", "label": "Last Name", "required": true, "size": "medium" }, "style": { "width": "100%" } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": { "colSpan": 2 },
+                        "style": {},
+                        "children": [
+                          { "type": "input", "props": { "key": "email", "label": "Email", "required": true, "prefix": "EmailOutlined", "size": "medium" }, "style": { "width": "100%" } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": { "colSpan": 2 },
+                        "style": {},
+                        "children": [
+                          {
+                            "type": "dropdown",
+                            "props": {
+                              "key": "subject",
+                              "label": "Subject",
+                              "required": true,
+                              "fullWidth": true,
+                              "placeholder": "Select a topic",
+                              "options": [
+                                { "label": "General Inquiry", "value": "general" },
+                                { "label": "Technical Support", "value": "support" },
+                                { "label": "Billing", "value": "billing" },
+                                { "label": "Partnership", "value": "partnership" }
+                              ]
+                            }
+                          }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": { "colSpan": 2 },
+                        "style": {},
+                        "children": [
+                          { "type": "textarea", "props": { "key": "message", "label": "Message", "required": true, "rows": 5, "placeholder": "Tell us how we can help you..." }, "style": { "width": "100%" } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": { "colSpan": 2 },
+                        "style": { "justifyContent": "flex-end" },
+                        "children": [
+                          {
+                            "type": "button",
+                            "props": { "label": "Send Message", "variant": "contained", "color": "primary", "prefix": "SendOutlined" },
+                            "actions": {
+                              "onClick": {
+                                "type": "custom",
+                                "code": "sendContactForm({ firstName: form.firstName, lastName: form.lastName, email: form.email, subject: form.subject, message: form.message }); setData({ submitted: true })"
+                              }
+                            }
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "dialogs": [],
+  "actions": [],
+  "timers": []
+}

package/training/examples/03-kpi-cards-row.json

@@ -0,0 +1,123 @@
+{
+  "description": "Three KPI metric cards in a row with trend indicators — typical dashboard top section",
+  "components_used": ["layout", "layout-cell", "kpi-metric", "kpi-trend", "kpi-badge", "kpi-statusDot", "divider"],
+  "root": {
+    "type": "layout",
+    "props": { "cols": 1, "rowGap": 24 },
+    "children": [
+      {
+        "type": "layout-cell",
+        "props": {},
+        "style": { "padding": "0 0 8px 0" },
+        "children": [
+          { "type": "header", "props": { "text": "Today's Overview", "variant": "h5", "color": "textPrimary" } }
+        ]
+      },
+      {
+        "type": "layout-cell",
+        "props": {},
+        "style": {},
+        "children": [
+          {
+            "type": "layout",
+            "props": { "cols": 3, "gap": 16 },
+            "children": [
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "backgroundColor": "#ffffff", "borderRadius": "12px", "boxShadow": "0 2px 8px rgba(0,0,0,0.08)", "padding": "24px" },
+                "children": [
+                  {
+                    "type": "layout",
+                    "props": { "cols": 1, "rowGap": 8 },
+                    "children": [
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": { "justifyContent": "space-between", "alignItems": "flex-start" },
+                        "children": [
+                          { "type": "kpi-metric", "props": { "valueKey": "data.totalRevenue", "label": "Total Revenue", "format": "currency", "currency": "USD", "decimals": 0, "fontSize": "28px", "fontWeight": "700", "align": "left", "labelPosition": "below", "labelColor": "text.secondary", "labelFontSize": "13px" } },
+                          { "type": "kpi-statusDot", "props": { "valueKey": "data.revenueStatus", "size": "10", "pulse": true, "showLabel": false, "thresholds": [{ "operator": "==", "value": "healthy", "color": "success.main" }] } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "kpi-trend", "props": { "valueKey": "data.revenueGrowth", "label": "vs last month", "isPercent": true, "decimals": 1, "variant": "chip", "size": "small", "showIcon": true, "align": "left" } }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "backgroundColor": "#ffffff", "borderRadius": "12px", "boxShadow": "0 2px 8px rgba(0,0,0,0.08)", "padding": "24px" },
+                "children": [
+                  {
+                    "type": "layout",
+                    "props": { "cols": 1, "rowGap": 8 },
+                    "children": [
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "kpi-metric", "props": { "valueKey": "data.totalOrders", "label": "Total Orders", "format": "number", "fontSize": "28px", "fontWeight": "700", "align": "left", "labelPosition": "below", "labelColor": "text.secondary", "labelFontSize": "13px" } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "kpi-trend", "props": { "valueKey": "data.ordersGrowth", "label": "vs last week", "isPercent": true, "decimals": 0, "variant": "chip", "size": "small", "showIcon": true, "align": "left" } }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              },
+              {
+                "type": "layout-cell",
+                "props": {},
+                "style": { "backgroundColor": "#ffffff", "borderRadius": "12px", "boxShadow": "0 2px 8px rgba(0,0,0,0.08)", "padding": "24px" },
+                "children": [
+                  {
+                    "type": "layout",
+                    "props": { "cols": 1, "rowGap": 8 },
+                    "children": [
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": { "justifyContent": "space-between", "alignItems": "flex-start" },
+                        "children": [
+                          { "type": "kpi-metric", "props": { "valueKey": "data.satisfactionScore", "label": "Satisfaction", "format": "number", "decimals": 1, "suffix": "/5", "fontSize": "28px", "fontWeight": "700", "align": "left", "labelPosition": "below", "labelColor": "text.secondary", "labelFontSize": "13px" } },
+                          { "type": "kpi-badge", "props": { "valueKey": "data.satisfactionLevel", "variant": "soft", "size": "small", "thresholds": [{ "operator": "==", "value": "excellent", "color": "success.main", "label": "Excellent" }, { "operator": "==", "value": "good", "color": "info.main", "label": "Good" }] } }
+                        ]
+                      },
+                      {
+                        "type": "layout-cell",
+                        "props": {},
+                        "style": {},
+                        "children": [
+                          { "type": "kpi-trend", "props": { "valueKey": "data.satisfactionDelta", "label": "vs last quarter", "isPercent": false, "decimals": 1, "variant": "chip", "size": "small", "showIcon": true, "align": "left" } }
+                        ]
+                      }
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  },
+  "dialogs": [],
+  "actions": [],
+  "timers": []
+}