@object-ui/plugin-report 4.0.11 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @object-ui/plugin-report
 
+## 4.2.1
+
+### Patch Changes
+
+- @object-ui/types@4.2.1
+- @object-ui/core@4.2.1
+- @object-ui/i18n@4.2.1
+- @object-ui/react@4.2.1
+- @object-ui/components@4.2.1
+- @object-ui/fields@4.2.1
+- @object-ui/plugin-grid@4.2.1
+
+## 4.2.0
+
+### Minor Changes
+
+- 650392e: MatrixRenderer now displays i18n-translated labels for picklist (`select` / `status`) groupings instead of raw values (e.g. `Best Case` / `Commit` / `Pipeline` instead of `best_case` / `commit` / `pipeline`). Field labels in the corner cell, row/column total labels, and the `(Empty)` / `(All)` placeholders are also fully translated. Adds `report.*` keys to `en` and `zh` locale bundles.
+- 26f5fce: Simplify report identity: replace the dashboard-style KPI grid with a compact "Totals" strip so reports look like reports (table-first with a grand total), not like mini-dashboards.
+  - `SpecReportGrid` now renders one inline `Totals: Label1: value Label2: value …` strip above the chart and table, styled as a muted single-line band — clearly subordinate to the data grid below.
+  - The Totals strip is now also shown for `tabular` reports when they declare aggregating columns (matches Salesforce's "Grand Total" convention).
+  - Drop the duplicate chart title `<div>`: the chart component already renders its own title from `report.chart.title`.
+  - Test ids renamed: `spec-report-kpis` → `spec-report-totals`, `spec-report-kpi-${key}` → `spec-report-total-${key}`.
+
+  Visual distinction from dashboards is now intentional: dashboard widgets use prominent floating KPI cards to convey "headline numbers"; report Totals describe the single dataset on the page and are intentionally compact.
+
+- 84b4bf1: Summary reports now render i18n-translated labels in the chart axis, chart series legend, and totals strip. `buildChartData` accepts a new `labels` parameter so callers (currently `SpecReportGrid`) can supply field/column/aggregate/value resolvers. Replaces raw column keys (e.g. `Count of case_number`) and raw picklist values (e.g. `closed`, `in_progress`) with their translated display labels (e.g. `案例编号 · 计数`, `已关闭`, `处理中`). Adds `report.totals` locale key.
+
+### Patch Changes
+
+- Updated dependencies [eb738bd]
+- Updated dependencies [650392e]
+- Updated dependencies [84b4bf1]
+  - @object-ui/i18n@4.2.0
+  - @object-ui/components@4.2.0
+  - @object-ui/fields@4.2.0
+  - @object-ui/react@4.2.0
+  - @object-ui/plugin-grid@4.2.0
+  - @object-ui/types@4.2.0
+  - @object-ui/core@4.2.0
+
+## 4.1.0
+
+### Minor Changes
+
+- b4ce9e2: Fix summary reports: render chart + KPIs, correct empty-table on server-aggregated data.
+  - `plugin-report`: `SpecReportGrid` now renders a KPI strip (per aggregating column) and a chart section above the grid for `summary` reports. KPI section auto-hides when no aggregating columns. New `buildChartData()` adapter buckets aggregated `ReportRow[]` to chart-ready data, auto-sorts pie/funnel descending, and falls back to row count when the chart `yAxis` points at a non-numeric column. When the data is server-aggregated, the grid switches columns to `[groupings, ${field}__${agg}]` so cells aren't empty against a raw-row column schema.
+  - `plugin-charts`: register `'column'` as an alias of `'bar'` in `ChartRenderer` / `AdvancedChartImpl` (Recharts only has `BarChart`).
+  - `app-shell`: `ReportView` now routes any object-backed report (matrix/joined/summary/tabular/columns/groupingsAcross) through the spec `ReportRenderer`; fully-legacy `fields`+`data` schemas still use `ReportViewer`.
+
+- b42a0d0: Server-side `dateGranularity` pushdown.
+
+  `useReportData()` reports with `{ groupBy: [{ field, dateGranularity }] }`
+  are now aggregated directly in the database via native SQL (`strftime` /
+  `to_char` / `date_format`) instead of fetching raw rows and bucketing in
+  Node. The framework's `driver-sql` advertises per-granularity support via
+  `IDataDriver.supports.queryDateGranularity` and the engine transparently
+  falls back to in-memory bucketing only when the dialect can't express a
+  given granularity (notably SQLite `week`, which needs `strftime('%V')`
+  added in SQLite 3.46). Output bucket labels (`2026-Q2`, `2026-01-15`,
+  `2026-W23`, …) are byte-for-byte identical between paths so drill
+  `groupKey` filters compose correctly across SQL and in-memory routes.
+
+  Requires framework ≥ commit `b26d217c`.
+
+### Patch Changes
+
+- @object-ui/types@4.1.0
+- @object-ui/core@4.1.0
+- @object-ui/react@4.1.0
+- @object-ui/components@4.1.0
+- @object-ui/fields@4.1.0
+- @object-ui/plugin-grid@4.1.0
+
+## 4.0.12
+
+### Patch Changes
+
+- @object-ui/types@4.0.12
+- @object-ui/core@4.0.12
+- @object-ui/react@4.0.12
+- @object-ui/components@4.0.12
+- @object-ui/fields@4.0.12
+
 ## 4.0.11
 
 ### Patch Changes

package/README.md

@@ -4,15 +4,15 @@ Report components for Object UI — build, view, render, and export reports with
 
 ## Features
 
-- 📊 **Report Builder** - Visual drag-and-drop report construction
-- 👁️ **Report Viewer** - Interactive report viewing with toolbar controls
-- 🎨 **Type-aware cells** - select → Badge, lookup → link, boolean → ✓/✗, email/url/phone → mailto/external/tel links, image → thumbnail, etc. (auto-hydrated from object metadata)
-- 🖨️ **Report Renderer** - Render reports from JSON definitions with charts
-- 📤 **Multi-Format Export** - Export to CSV, JSON, HTML, PDF, and Excel
-- 🔄 **Live Data Export** - Export with real-time data via `exportWithLiveData`
-- 📈 **Excel Formulas** - Export Excel files with live formulas via `exportExcelWithFormulas`
-- ⏰ **Schedule Config** - Configure recurring report generation and delivery
-- 📦 **Auto-registered** - Components register with `ComponentRegistry` on import
+- 🧩 **Four spec report variants** — `tabular` / `summary` / `matrix` / `joined`, dispatched by a single `<ReportRenderer schema={...}>`
+- 🧮 **Server-side aggregation** — `useReportData()` posts spec `QueryAST` to `POST /api/v1/data/:object/query`; transparent in-memory fallback
+- 📅 **Date bucketing** — `dateGranularity: day|week|month|quarter|year` on `groupingsAcross` / `groupingsDown`
+- 🪜 **Multi-level grouping + totals** — row totals, column totals, grand totals for matrix; tabular/summary delegate to `ObjectGrid`
+- 🎯 **Cell drill-down** — every aggregated cell dispatches a `drill` action via `ActionRunner`; targets List view or a nested Report (M3)
+- 🧱 **Joined reports** — vertically stacked sub-reports; each block owns its own `objectName`, filter and data fetch
+- 🎨 **Type-aware cells** — `select` → Badge, `lookup` → link, `boolean` → ✓/✗, `email`/`url`/`phone` → links, `image` → thumbnail (auto-hydrated from object metadata)
+- 🖨️ **Multi-format export** — CSV, JSON, HTML, PDF, Excel; live-data and Excel-formula variants
+- 📦 **Auto-registered** — components register with `ComponentRegistry` on import; embed via `{ "type": "spec-report", "report": {...} }`
 
 ## Installation
 
@@ -49,33 +49,115 @@ function EmbeddedReport() {
 }
 ```
 
-## API
+## Spec Reports — the four variants
 
-### ReportBuilder
+The plugin renders any `Report` defined by `@objectstack/spec`:
 
-Visual report construction interface:
+```ts
+import type { ReportInput } from '@objectstack/spec/ui';
+import { ReportRenderer } from '@object-ui/plugin-report';
 
-```tsx
-<ReportBuilder report={initialReport} />
+const report: ReportInput = {
+  name: 'opp_by_stage',
+  objectName: 'opportunity',
+  type: 'summary',
+  columns: [
+    { field: 'stage' },
+    { field: 'amount', aggregate: 'sum' },
+    { field: 'id', label: 'Deals', aggregate: 'count' },
+  ],
+  groupingsDown: [{ field: 'stage', sortOrder: 'asc' }],
+};
+
+<ReportRenderer schema={report} dataSource={ds} />
 ```
 
-### ReportViewer
+| `type`    | Description                                          |
+| --------- | ---------------------------------------------------- |
+| `tabular` | Flat record list                                     |
+| `summary` | Single-axis grouped + aggregated                     |
+| `matrix`  | Row × column pivot with cell aggregates and totals   |
+| `joined`  | Vertically stacked sub-reports, each with own data   |
 
-Interactive report viewer with toolbar:
+### Matrix (row × column pivot)
 
-```tsx
-<ReportViewer report={reportDefinition} showToolbar />
+```ts
+{
+  name: 'pipeline_by_quarter',
+  objectName: 'opportunity',
+  type: 'matrix',
+  columns: [{ field: 'amount', label: 'Pipeline', aggregate: 'sum' }],
+  groupingsDown:   [{ field: 'forecast_category' }],
+  groupingsAcross: [{ field: 'close_date', dateGranularity: 'quarter' }],
+}
 ```
 
-### ReportRenderer
+`dateGranularity` accepts `day | week | month | quarter | year` and is
+pushed down to the server-side aggregator.
 
-Renders a report from a JSON chart configuration:
+### Joined (M3)
+
+```ts
+{
+  name: 'churn_signals',
+  objectName: 'account',          // container default
+  type: 'joined',
+  columns: [],
+  blocks: [
+    { name: 'at_risk', type: 'summary', columns: [...], filter: {...} },
+    { name: 'lost',    type: 'summary', objectName: 'opportunity', columns: [...], filter: {...} },
+  ],
+}
+```
+
+Block rules: `objectName` falls back to the container; `filter` is ANDed
+with the container's; each block runs an isolated `useReportData()` call;
+`block.type` must not be `joined` (no recursion).
+
+## Server-side aggregation + drill-down
+
+`useReportData()` translates a `Report` into spec `QueryAST` and posts it
+to `POST /api/v1/data/:object/query`. If the endpoint is unavailable it
+falls back transparently to `dataSource.find()` + client-side aggregation.
+
+Every aggregated cell dispatches a `drill` action through `ActionRunner`:
 
 ```tsx
-<ReportRenderer title="Revenue" description="Q4 Revenue" chart={chartConfig} />
+import { registerDrillHandler } from '@object-ui/plugin-report';
+registerDrillHandler(actionRunner, { navigate: router.push });
+```
+
+Drill targets:
+1. **List view** — default; navigates to the filtered records.
+2. **Report drawer** — if the host widget declares `drillDown.report`,
+   the click opens a side drawer that renders that report scoped to the
+   cell's group key (composes dashboard → report → record).
+
+## Filter-time date helpers — current limitation
+
+The server does **not** currently evaluate `` cel`...` `` expressions
+embedded in filter values. Use module-load ISO strings instead:
+
+```ts
+const daysAgo = (n: number): string => {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - n);
+  return d.toISOString().slice(0, 10);
+};
+
+filter: { close_date: { $gte: daysAgo(30) } }
 ```
 
-### Export Functions
+See the bundled CRM `customer_churn_signals` demo for the full pattern.
+Native filter-time CEL evaluation is tracked for a future major version.
+
+## Legacy components
+
+`ReportBuilder`, `ReportViewer` and the export functions below remain
+available for legacy presentation-layer reports and are not affected by
+the spec-driven pipeline above.
+
+
 
 Export reports in multiple formats: