@object-ui/plugin-report 4.0.12 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,244 @@
 # @object-ui/plugin-report
 
+## 4.3.0
+
+### Minor Changes
+
+- f196cf4: feat(plugin-report): popup picker for groupings + section-aware test ids
+
+  The matrix/summary "Group by" (rows) and "Columns axis" (cols) sections now
+  share the same searchable popup picker as the columns section, with a
+  commit-on-select single-pick mode wired through `FieldPickerDialog`.
+  - Per-row field buttons display the human-readable field label and open a
+    dialog scoped to swap that single field (already-used fields filtered out)
+  - "Add grouping" trigger uses the same dialog
+  - `GroupingsBuilder` accepts a `testIdPrefix` prop; ReportConfigPanel passes
+    `rows-grouping` and `cols-grouping` so both instances no longer share the
+    ambiguous `grouping-field-0` testid
+  - Bigger row spacing (h-7 / text-xs) — the old `text-[10px]` was unreadable
+
+  `FieldPickerDialog` gains:
+  - `commitOnSelect`: hides the Confirm/Cancel footer; clicking a row commits
+    - closes immediately (intended for `singleSelect` flows)
+  - `trigger`: custom trigger element override (used by the per-row field button)
+
+- 079c3b2: feat(plugin-report): per-block field resolution for joined reports
+
+  Joined report blocks can override `objectName` to query a different
+  object than the container, but the editor was always offering the
+  container's fields — wrong field names, wrong types, broken granularity
+  and chart-axis filtering.
+
+  `ReportConfigPanel` now accepts an optional `getFieldsForObject`
+  resolver. `JoinedBlocksEditor` uses it to source fields for each
+  block based on `block.objectName ?? containerObjectName`, falling
+  back to the static `availableFields` when the resolver returns
+  `undefined` (unknown object).
+
+  `ReportView` wires the resolver against the app's loaded `objects`
+  list and reuses the same parsing path internally to derive its
+  top-level `availableFields`, removing the duplicated schema lookup.
+
+  5 new RTL tests verify the resolver wiring, fallback behaviour,
+  add-block flow, and inline duplicate-name validation (111 plugin-report
+  tests green).
+
+- ee1cc96: feat(plugin-report): joined-report block editor
+
+  `type: 'joined'` reports were a black hole in the editor — the type
+  selector exposed them but no UI knew how to edit the `blocks` array,
+  so users could neither create nor modify joined reports without
+  hand-editing JSON.
+
+  This change adds a `Blocks` section to the report editor, visible only
+  when `type === 'joined'`. Each block renders as a collapsible card with
+  its own name (required + unique-validated), label, description, block
+  type, object override, and reuses the existing `ColumnsEditor`,
+  `GroupingsBuilder`, `SpecFilterAdapter`, and `ChartConfig` builders so
+  every block behaves like a mini standalone report — matching the
+  runtime contract of `JoinedReportRenderer`.
+
+  Block-level validation is surfaced in the main `ValidationBanner`:
+  empty blocks array, missing or duplicate block names, and blocks
+  without columns all become editor-time errors so saves stay safe.
+
+  The non-joined sections (Columns / Rows / Columns axis / Filters /
+  Chart) are hidden when `type === 'joined'` since they live per-block
+  in the spec.
+
+  New exports from `@object-ui/plugin-report`:
+  - `JoinedBlocksEditor` — standalone component for embedding the
+    block editor anywhere.
+  - `validateJoinedBlocks` — pure helper returning translated
+    problem strings, suitable for custom validation banners.
+  - `ColumnsEditor`, `GroupingsBuilder`, `ChartConfig`,
+    `SpecFilterAdapter`, `normalizeColumns` are now exported so
+    downstream consumers can build their own report-editor surfaces.
+
+  i18n: added `report.editor.blocks*` / `report.editor.addBlock` /
+  `report.editor.removeBlock` / `report.editor.blockName*` /
+  `report.editor.blockLabel*` / `report.editor.blockDescription*` /
+  `report.editor.validationJoinedNeedsBlocks` /
+  `report.editor.validationBlockNameRequired` /
+  `report.editor.validationBlockNameDuplicate` /
+  `report.editor.validationBlockNeedsColumns` to en + zh.
+
+- 0b032be: feat(plugin-report): replace inline column picker with a popup field picker
+
+  The columns section now opens a Dialog-based multi-select picker (`FieldPickerDialog`)
+  instead of rendering the unselected field list inline. The popup supports search,
+  batched multi-selection (commit several fields in one click), per-field type badges,
+  cancel-discards-pending semantics, and is fully i18n'd. Also fixes a latent
+  `ReferenceError: normalizeColumns is not defined` that crashed the editor whenever
+  the chart section was expanded.
+
+- 4e7bc1b: **Report editor panel overhaul**
+
+  The report configuration panel is now safe to open on any spec-shape `Report` and only exposes fields that are actually persisted by `@objectstack/spec`.
+
+  `@object-ui/plugin-report`:
+  - Add a bidirectional `SpecFilterAdapter` so `ReportConfigPanel` can edit
+    spec `FilterCondition` filters (`{field: value}`, `{field: {$op: value}}`,
+    top-level `$and`/`$or`). Complex / nested filters fall back to a
+    read-only banner and are preserved verbatim on save.
+  - Drop sections that never round-tripped through the spec
+    (`conditionalFormatting`, `sections`, `export`, `schedule`, `appearance`)
+    and their helper components.
+  - Add type-driven section visibility: `tabular` shows Columns/Filters,
+    `summary` adds Rows + Chart, `matrix` adds Rows + Columns axis + Chart.
+  - New `GroupingsBuilder` covers `groupingsDown`/`groupingsAcross` with
+    `sortOrder` and date-aware `dateGranularity` controls.
+  - New `ColumnsEditor` lets users reorder picked columns, override labels,
+    set aggregates and choose a display format.
+  - Chart subset now mirrors the spec: chart `title`, `showLegend`,
+    `showDataLabels`, plus `funnel` (scatter removed).
+  - Validation banner highlights missing `objectName` and missing
+    rows/columns for `matrix`/`summary` reports.
+  - All editor labels and hints are i18n-driven (`report.editor.*`).
+  - 18 new unit tests cover the filter adapter round-trip.
+
+  `@object-ui/components`:
+  - `FilterBuilder` now guards against malformed external `value` props.
+    Previously a spec-shape filter (`{is_active: true}`) would crash the
+    component on first render; the builder now falls back to an empty
+    AND group whenever `value` is not a valid `FilterGroup`.
+
+  `@object-ui/i18n`:
+  - Add `report.editor.*` strings to `en` and `zh`.
+
+- 8442c05: Improve report editor panel usability based on real-user browser testing:
+  - **Wider config panel** — the report editor now defaults to a `--config-panel-width`
+    of 440px (up from 280px), driven by a new optional `style` prop on
+    `ConfigPanelRenderer`. Long field labels, report titles, type labels, and filter
+    rows no longer truncate to "Account Na" / "kup" / "ct" / 1-character widths.
+  - **Disambiguated "Columns" sections** — for `summary` and `matrix` reports the
+    measure list is now labelled **"Values / 度量"** (pivot-style vocabulary) instead
+    of "Columns", which previously clashed with the matrix's pivot column axis
+    (also called "Columns / 列"). The two sections used to be indistinguishable.
+    New i18n key `report.editor.values` / `valuesHint` is shipped for all 10
+    locales (en, zh, ar, de, es, fr, ja, ko, pt, ru).
+  - **Reordered sections for matrix/summary** — the editor now surfaces _Rows_
+    and _Columns_ (the pivot axes) **before** _Values_, mirroring how a business
+    user thinks about a pivot table.
+  - **Per-row aggregate/format headers** — each column row in `ColumnsEditor` now
+    shows small "Aggregate" / "Format" labels above the respective selects, and
+    the row uses a 2-line layout so the label input has its own line. The cramped
+    3-dropdowns-side-by-side layout at 10px font is gone.
+  - **Searchable field picker** — the "Add columns" list now has a search box,
+    a `filtered / total` counter, an empty-state message, and a scrollable bordered
+    container. New i18n keys: `report.editor.searchFields`,
+    `report.editor.noMatchingFields`.
+
+### Patch Changes
+
+- 12c3b7c: refactor(plugin-report): split ReportConfigPanel.tsx (~1200 lines) into per-builder modules. The orchestrator file now only hosts `buildReportSchema`, `ValidationBanner`, and the public `ReportConfigPanel` component; each sub-editor (`SpecFilterAdapter`, `ColumnsEditor`, `GroupingsBuilder`, `ChartConfig`) lives in its own file alongside `editorTypes.ts` for shared types/constants. All existing exports are re-exported from `ReportConfigPanel` so test files and downstream consumers (`JoinedBlocksEditor`, `app-shell`) keep their current import paths. Pure refactor — no behavior change, 111 tests green.
+- Updated dependencies [f196cf4]
+- Updated dependencies [ee1cc96]
+- Updated dependencies [0b032be]
+- Updated dependencies [115d36a]
+- Updated dependencies [4e7bc1b]
+- Updated dependencies [8442c05]
+  - @object-ui/i18n@4.3.0
+  - @object-ui/components@4.3.0
+  - @object-ui/fields@4.3.0
+  - @object-ui/react@4.3.0
+  - @object-ui/plugin-grid@4.3.0
+  - @object-ui/types@4.3.0
+  - @object-ui/core@4.3.0
+
+## 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

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: