robobyte-front-builder 1.0.26 → 1.0.27

package/training/46-kpi-rating.md

@@ -0,0 +1,125 @@
+# Component: kpi-rating
+
+An interactive or read-only star/heart/circle rating component. Writes the selected value back to `data[valueKey]`.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `valueKey` | expression | Data key for the current rating value. Clicking a star writes the new rating to `data[valueKey]`. |
+
+### Appearance
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `max` | expression | Maximum rating (number of icons shown). E.g. `5`, `10`. |
+| `icon` | select | `star` · `heart` · `circle` · `square` — Icon shape. |
+| `color` | expression | Color of filled/active icons, e.g. `"#f5a623"`, `"primary.main"`. |
+| `emptyColor` | expression | Color of unfilled icons, e.g. `"#e0e0e0"`. |
+| `size` | expression | Icon size in px, e.g. `"28"`. |
+| `gap` | expression | Gap between icons in px, e.g. `"4"`. |
+| `align` | select | `left` · `center` · `right` |
+| `readonly` | boolean | `true` prevents user interaction — display only. |
+
+### Actions
+| Prop | Type | Notes |
+|------|------|-------|
+| `onChange` | kpi-action | Fires when the user selects a rating. Available: `newValue` (new rating number), `clickedValue` (alias). The new value is automatically written to `data[valueKey]` before the action runs. |
+
+---
+
+## Props — Style Tab
+
+No dedicated style tab.
+
+---
+
+## Use Cases
+
+**When to use:**
+- Product reviews: user rates a product 1–5 stars.
+- Feedback forms: rate your experience.
+- Priority indicators with visual icons.
+- Read-only display of an average rating score.
+
+**When NOT to use:**
+- Sliders with continuous values → use a number input with slider.
+- Pure numeric display → use `kpi-metric`.
+- Status with fixed categories → use `kpi-badge`.
+
+---
+
+## Schema Examples
+
+### Interactive 5-star rating
+```json
+{
+  "type": "kpi-rating",
+  "props": {
+    "valueKey": "data.userRating",
+    "max": 5,
+    "icon": "star",
+    "color": "#f5a623",
+    "emptyColor": "#e0e0e0",
+    "size": "32",
+    "gap": "4",
+    "align": "center",
+    "readonly": false
+  }
+}
+```
+
+### Read-only product rating display
+```json
+{
+  "type": "kpi-rating",
+  "props": {
+    "valueKey": "data.product.avgRating",
+    "max": 5,
+    "icon": "star",
+    "color": "#fbc02d",
+    "emptyColor": "#e0e0e0",
+    "size": "20",
+    "readonly": true,
+    "align": "left"
+  }
+}
+```
+
+### Heart rating with action
+```json
+{
+  "type": "kpi-rating",
+  "props": {
+    "valueKey": "data.satisfaction",
+    "max": 5,
+    "icon": "heart",
+    "color": "#e91e63",
+    "size": "28",
+    "align": "center",
+    "onChange": {
+      "type": "custom",
+      "code": "submitSatisfactionScore({ score: newValue, sessionId: data.sessionId })"
+    }
+  }
+}
+```
+
+### 10-point circle rating
+```json
+{
+  "type": "kpi-rating",
+  "props": {
+    "valueKey": "data.npsScore",
+    "max": 10,
+    "icon": "circle",
+    "color": "primary.main",
+    "emptyColor": "#e0e0e0",
+    "size": "20",
+    "gap": "2",
+    "align": "left"
+  }
+}
+```

package/training/47-kpi-countdown.md

@@ -0,0 +1,151 @@
+# Component: kpi-countdown
+
+A live countdown timer displaying days, hours, minutes, and seconds remaining until a target date/time. Fires an `onDone` action when it reaches zero.
+
+---
+
+## Props — Main Tab
+
+### Data
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `targetDateKey` | expression | Data key or expression returning the target date. Accepts: ISO datetime string, ISO date string, epoch ms (number), epoch seconds (number < 1e11), or JS Date object. E.g. `"dealDeadline"` → `data.dealDeadline`. |
+| `targetDate` | expression | Static target date when not using `targetDateKey`. E.g. `"2025-12-31T23:59:59"`. |
+| `doneLabel` | expression | Text shown when the countdown reaches zero, e.g. `"Expired"`, `"Time's up!"`. |
+| `label` | expression | Optional heading shown above the countdown digits. |
+
+### Segments
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `showDays` | boolean | Show days counter. |
+| `showHours` | boolean | Show hours counter. |
+| `showMinutes` | boolean | Show minutes counter. |
+| `showSeconds` | boolean | Show seconds counter. |
+
+### Unit Label Overrides
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelDays` | expression | Override "days" label, e.g. `"d"`. |
+| `labelHours` | expression | Override "hrs" label, e.g. `"h"`. |
+| `labelMinutes` | expression | Override "min" label. |
+| `labelSeconds` | expression | Override "sec" label. |
+
+### Layout
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `size` | select | `small` · `medium` · `large` — Controls digit font scale. |
+| `align` | select | `left` · `center` · `right` |
+| `separator` | expression | Character between digit groups, e.g. `":"`. Default: `":"`. |
+
+### Colors
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `color` | expression | Digit color. Overridden by thresholds. E.g. `"#1976d2"`. |
+| `unitColor` | expression | Color of the unit labels (days/hrs/min/sec). Default: `text.disabled`. |
+| `separatorColor` | expression | Color of the separator character. Default: `text.disabled`. |
+| `doneLabelColor` | expression | Color of the done label. Default: `success.main`. |
+
+### Digit Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `numberFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` · `900` |
+
+### Label Style
+| Prop | Type | Options / Notes |
+|------|------|-----------------|
+| `labelFontSize` | expression | Heading label font size. |
+| `labelFontWeight` | select | `300` · `400` · `500` · `600` · `700` · `800` |
+| `labelColor` | expression | Heading label color. Default: `text.secondary`. |
+
+### Thresholds
+| Prop | Type | Notes |
+|------|------|-------|
+| `thresholds` | thresholds-editor | Applied on remaining seconds. E.g. `< 3600` → `error.main` (last hour turns red). |
+
+### On Done
+| Prop | Type | Notes |
+|------|------|-------|
+| `onDoneCode` | code | Code run when countdown reaches zero. |
+
+---
+
+## Use Cases
+
+**When to use:**
+- Deal/offer expiry countdowns (e.g. flash sale).
+- Appointment/meeting countdown.
+- Deadline trackers for tasks or bids.
+- Event date countdowns (conference, launch).
+
+**When NOT to use:**
+- Elapsed time (uptime) → display a label with calculated duration.
+- Non-time-based progress → use `kpi-gauge` or `progress-line`.
+- Static date display → use `label`.
+
+---
+
+## Schema Examples
+
+### Deal expiry countdown
+```json
+{
+  "type": "kpi-countdown",
+  "props": {
+    "targetDateKey": "data.offerExpiry",
+    "label": "Offer Expires In",
+    "doneLabel": "Offer Expired",
+    "showDays": true,
+    "showHours": true,
+    "showMinutes": true,
+    "showSeconds": true,
+    "size": "large",
+    "align": "center",
+    "numberFontWeight": "700",
+    "color": "#1976d2",
+    "thresholds": [
+      { "operator": "<", "value": 3600, "color": "error.main" },
+      { "operator": "<", "value": 86400, "color": "warning.main" }
+    ],
+    "onDoneCode": "setData({ offerExpired: true }); showBanner('offerExpiredBanner')"
+  }
+}
+```
+
+### Days-only event countdown
+```json
+{
+  "type": "kpi-countdown",
+  "props": {
+    "targetDate": "2025-12-31",
+    "label": "Days Until Year End",
+    "showDays": true,
+    "showHours": false,
+    "showMinutes": false,
+    "showSeconds": false,
+    "size": "medium",
+    "align": "center",
+    "color": "#1976d2"
+  }
+}
+```
+
+### Compact with custom separator
+```json
+{
+  "type": "kpi-countdown",
+  "props": {
+    "targetDateKey": "data.meetingTime",
+    "showDays": false,
+    "showHours": true,
+    "showMinutes": true,
+    "showSeconds": true,
+    "separator": ":",
+    "size": "small",
+    "align": "left",
+    "labelDays": "d",
+    "labelHours": "h",
+    "labelMinutes": "m",
+    "labelSeconds": "s"
+  }
+}
+```

package/training/48-fetchReportData.md

@@ -0,0 +1,276 @@
+# Helper: `fetchReportData` — Calculation-scope Reference Manual
+
+> **Audience.** AI sessions emitting builder Calculation code (`actionsConfig.code`, `viewerActions.code`, `onClick`, `onLoad`, column functions, etc.). `fetchReportData` is **auto-injected** into every Calculation scope — you never `import` it in a builder schema.
+
+Fetches report data by `pageId` **without any AG Grid dependency**. Resolves the report's builder model on first call (cached for the session), applies the supplied filter on top of the report's own filter, optionally evaluates `customFilterCode`, then issues `GenericGet` and returns a normalized result.
+
+Use this whenever a Calculation needs **rows from a server-defined report** but the rows aren't rendered by a `reportViewer` on the page (e.g. dialog seed data, exports, conditional logic, dashboard counters, hidden lookups).
+
+> ⚠️ Different from `<reportViewer>`. `<reportViewer>` renders + paginates + filters + ag-grids the data. `fetchReportData` is a **pure data fetch** — you get an array back and decide what to do with it.
+
+---
+
+## 1. Quick start
+
+```js
+const result = await fetchReportData({ pageId: 'OPEN_INVOICES' })
+if (result.success) {
+  console.log(`Got ${result.rows.length} of ${result.total} rows`)
+}
+```
+
+Minimum: `pageId`. Everything else has sane defaults.
+
+---
+
+## 2. Signature
+
+`fetchReportData` is the alias bound into Calculation scope. The function it points to is the package's `fetchReportDataByPageId` (one and the same).
+
+```ts
+await fetchReportData({
+  pageId,                // string | number — REQUIRED
+  filter = {},           // see section 3
+  isDataOnly = false,    // true → return rows array directly, no wrapper
+  dataAsObject = false,  // true → expand underscore-paths into nested objects
+  isPagination = true,   // false → fetch all matching rows
+  isSingle = false,      // true → return only the first row (row, not array)
+  globalParams = null,   // { 0: value, 1: value, ... } overrides selectionParams by index
+  page = 1,              // 1-based page number
+  pageSize = 50,         // rows per page
+  authContext = null,    // host auth, used by customFilterCode
+  context = null,        // host system context, used by customFilterCode
+})
+```
+
+> **`authContext` / `context`** — pass them along when calling from inside a Calculation if your filter uses `customFilterCode` that reads `authContext.user`. The builder runtime doesn't auto-thread them through (yet) — explicitly forward what you have. Most calls don't need either.
+
+---
+
+## 3. The `filter` parameter
+
+Plain JS object. Three slots:
+
+| Slot | Type | Purpose |
+|---|---|---|
+| `Tfilter` | `FilterItem[]` | Filters merged with the report's own filters. |
+| `TFilter` | `FilterItem[]` | Alias accepted for legacy callers. Concatenated with `Tfilter`. |
+| `customFilterCode` | `string` | JS source evaluated at fetch time; pushes filters into a local `customFilter` array. |
+
+Anything **else** at the top level of `filter` is forwarded as-is to the backend request body. Useful for backend-specific knobs.
+
+### `FilterItem` shape
+
+```ts
+{
+  path:          string,    // dotted field path, e.g. "Customer.RegionId"
+  friendlyName?: string,
+  value:         any,       // scalar | array (for In/NotIn/Between)
+  method:        'Equal' | 'NotEqual' | 'Greater' | 'GreaterOrEqual' |
+                 'Less'  | 'LessOrEqual'  | 'Contains' | 'StartsWith' |
+                 'EndsWith' | 'In' | 'NotIn' | 'IsNull' | 'IsNotNull' | 'Between',
+  orGroupName?:  string,    // group multiple items into an OR-block
+}
+```
+
+### Null filtering
+
+Items where `value === null || value === undefined || value === ''` are stripped **before** the request is sent. So you can build a filter from optional state without conditional guards:
+
+```js
+const filter = {
+  Tfilter: [
+    { path: 'Status',  value: data.status,    method: 'Equal' },   // dropped if data.status is null
+    { path: 'OwnerId', value: data.ownerId,   method: 'Equal' },   // same
+    { path: 'Year',    value: 2026,           method: 'Equal' },   // kept
+  ]
+}
+```
+
+### `customFilterCode`
+
+A JS string evaluated in a sandbox at request time. Push `FilterItem`s into `customFilter`. Scope:
+
+| Var | Source |
+|---|---|
+| `authContext` | The `authContext` arg passed to `fetchReportData`. |
+| `context` | The `context` arg passed to `fetchReportData`. |
+| `filters` | The merged `Tfilter` array right before custom filters are added. Read-only. |
+| `customFilter` | Empty `[]` to push items into. |
+
+```js
+const filter = {
+  customFilterCode: `
+    if (authContext?.user?.shopId) {
+      customFilter.push({
+        path:   'ShopId',
+        value:  authContext.user.shopId,
+        method: 'Equal',
+      })
+    }
+  `
+}
+```
+
+---
+
+## 4. Return shape
+
+```ts
+// Default — full wrapper:
+{
+  success: true,
+  rows:    RowType[] | RowType,   // array OR single row (if isSingle)
+  total:   number,                // total rows on the server (paginated mode)
+  rawResponse: any,               // exact backend response (use sparingly)
+  finalRequest: {                 // useful for debugging — what was actually sent
+    endpoint:    string,
+    getType:     'Pagination' | 'NoPagination' | 'SqlPagination' | 'SqlNoPagination',
+    filter:      object,          // final filter payload
+    sourceModel: string,
+    params:      { page, pageSize },
+  }
+}
+
+// On error:
+{ success: false, error: 'Report detailsOld not found' /* or Error */ }
+
+// With isDataOnly: true:
+RowType[] | RowType    // bare rows; no wrapper
+```
+
+### Common shape variants
+
+| Options | Returns |
+|---|---|
+| Defaults | `{ success, rows: Row[], total, ... }` |
+| `isSingle: true` | `{ success, rows: Row, ... }` — first row, not an array |
+| `isDataOnly: true` | `Row[]` (or `Row` if `isSingle`) — no wrapper |
+| `isPagination: false` | All matching rows (use with care on large datasets) |
+| `dataAsObject: true` | Rows have underscore-paths expanded to nested objects (`{ "Customer_Name": "..." }` → `{ Customer: { Name: "..." } }`) |
+
+---
+
+## 5. Recipes
+
+### 5.1 Count rows for a KPI
+
+```js
+async function Calculation(form, data, setData) {
+  const r = await fetchReportData({
+    pageId:  'OPEN_TICKETS',
+    isPagination: true,
+    pageSize: 1,            // we only care about `total`, not the rows
+  })
+  if (r.success) setData(prev => ({ ...prev, openTicketCount: r.total }))
+}
+```
+
+### 5.2 Seed a dialog with one record
+
+```js
+async function Calculation(form, data, setData, dataRef, reportRefs, openDialog) {
+  const r = await fetchReportData({
+    pageId:  'CUSTOMER_BY_ID',
+    isSingle: true,
+    filter: { Tfilter: [{ path: 'Id', value: rowData.Id, method: 'Equal' }] },
+  })
+  if (!r.success) { showToast('Lookup failed', 'error'); return }
+  openDialog('editCustomer', r.rows)   // r.rows is a single object, not an array
+}
+```
+
+### 5.3 Filtered list inside an onLoad action
+
+```js
+async function Calculation(form, data, setData) {
+  const r = await fetchReportData({
+    pageId:  'ACTIVE_USERS',
+    filter:  { Tfilter: [{ path: 'TenantId', value: data.tenantId, method: 'Equal' }] },
+    isPagination: false,
+  })
+  if (r.success) setData(prev => ({ ...prev, users: r.rows }))
+}
+```
+
+### 5.4 Pivot-style "raw rows for chart"
+
+```js
+async function Calculation(form, data, setData) {
+  const rows = await fetchReportData({
+    pageId:  'SALES_BY_MONTH',
+    isPagination: false,
+    isDataOnly: true,                    // skip the wrapper — we just want rows
+    dataAsObject: true,                  // expand `Region_Name` → `Region.Name`
+  })
+  setData(prev => ({ ...prev, chartData: rows }))
+}
+```
+
+### 5.5 Forward auth context for tenant-scoped reports
+
+```js
+async function Calculation(form, data, setData, dataRef, reportRefs, openDialog, closeDialog, urlParams, page) {
+  const r = await fetchReportData({
+    pageId: 'MY_SHOP_ORDERS',
+    filter: {
+      customFilterCode: `
+        if (authContext?.user?.shopId) {
+          customFilter.push({ path: 'ShopId', value: authContext.user.shopId, method: 'Equal' })
+        }
+      `,
+    },
+    authContext: page?.authContext,    // forward whatever the parent page has
+  })
+  // ...
+}
+```
+
+### 5.6 Override report selection params by index
+
+```js
+const r = await fetchReportData({
+  pageId: 'SALES_BY_REGION',
+  globalParams: { 0: data.year, 1: data.region },   // 0-based positional, NOT keyed by name
+})
+```
+
+### 5.7 Refresh a hidden lookup table on demand
+
+```js
+async function refreshLookups(form, data, setData) {
+  const r = await fetchReportData({
+    pageId:       'CATEGORIES_LOOKUP',
+    isPagination: false,
+    isDataOnly:   true,
+    dataAsObject: true,
+  })
+  setData(prev => ({ ...prev, categories: r }))
+}
+```
+
+---
+
+## 6. Pitfalls
+
+- **Forgetting `await`.** `fetchReportData` returns a `Promise`. Without `await`, `r.success` is `undefined` and the next line runs before the request completes. Always `await`.
+- **`isSingle: true` returns the row, not an array.** `r.rows[0]` will crash; use `r.rows` directly.
+- **`isPagination: false` on huge reports.** All rows are fetched in one request. Use it for lookups (≤ a few thousand rows). For large datasets, paginate.
+- **Builder-model cache is per-session.** First call hits the metadata endpoint; subsequent calls with the same `pageId` reuse it. If the report definition changes mid-session, the user sees stale columns until refresh.
+- **`globalParams` is index-keyed, not name-keyed.** Keys are 0-based positional indices into `selectionParams`. Wrong index → wrong override.
+- **`filter.LocalTfilter` is stripped.** Only `Tfilter` / `TFilter` are honored at this level. (LocalTfilter is a UI-side concept that doesn't make sense for a direct fetch.)
+- **`null` / `''` / `undefined` values are dropped.** This is usually convenient (no need to gate on optional state), but if you literally need to filter for `null`, use `method: 'IsNull'`, not `value: null`.
+- **`customFilterCode` is a string, not a function.** Pushed `FilterItem`s must be plain objects. You can't reference page `data` directly inside — only `authContext`, `context`, `filters` are in scope. To filter by page state, build the filter array in JS **before** calling `fetchReportData` instead.
+
+---
+
+## 7. Cheat sheet
+
+1. `await fetchReportData({ pageId: '...' })` — that's the minimum.
+2. Build the filter as a plain JS object: `{ Tfilter: [{ path, value, method }] }`. Null values are auto-stripped.
+3. `isDataOnly: true` returns the bare rows array — skip the `r.success` ceremony when you trust the call.
+4. `isSingle: true` returns one row, not an array. `r.rows` is that row.
+5. `isPagination: false` to load everything; cap with `pageSize` if needed.
+6. `dataAsObject: true` to expand `Foo_Bar` flat keys into `Foo.Bar` nested objects.
+7. `globalParams: { 0: ..., 1: ... }` overrides specific `selectionParams` by index.
+8. `customFilterCode` runs server-side at request time — useful for auth-derived filters; otherwise build the filter object in JS.