@object-ui/plugin-report 17.6.0 → 17.7.0

package/README.md

@@ -12,7 +12,7 @@ Report components for Object UI — render, view and export reports, with schedu
 - 🧱 **Joined reports** — vertically stacked sub-reports; each block names its own `dataset`, filter and ordering
 - 🎨 **Type-aware cells** — the presentation-layer `ReportViewer` renders `select` → Badge, `lookup` → link, `boolean` → ✓/✗, `email`/`url`/`phone` → links, `image` → thumbnail
 - 🖨️ **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": {...} }`
+- 📦 **Auto-registered** — components register with `ComponentRegistry` on import; embed via `{ "type": "report", "report": {...} }`
 
 ## Installation
 
@@ -33,8 +33,12 @@ report-authoring component in this package (see
 
 ```tsx
 import { ReportRenderer } from '@object-ui/plugin-report';
+import type { DataSource } from '@object-ui/types';
 
 // `dataSource` and `router` are host-provided.
+declare const dataSource: DataSource;
+declare const router: { push: (href: string) => void };
+
 function ReportPage() {
   return (
     <ReportRenderer
@@ -57,9 +61,17 @@ already decided the shape — it takes the report as `report`, not `schema`:
 
 ```tsx
 import { DatasetReportRenderer, isDatasetReport } from '@object-ui/plugin-report';
+import type { DataSource } from '@object-ui/types';
+
+// `stored` is whatever the host loaded; `dataSource` is host-provided.
+declare const stored: unknown;
+declare const dataSource: DataSource;
 
-if (isDatasetReport(stored)) {
-  return <DatasetReportRenderer report={stored} dataSource={dataSource} />;
+function StoredReportPage() {
+  if (isDatasetReport(stored)) {
+    return <DatasetReportRenderer report={stored} dataSource={dataSource} />;
+  }
+  return null;
 }
 ```
 
@@ -69,6 +81,12 @@ that schema, not props of the component:
 
 ```tsx
 import { ReportViewer } from '@object-ui/plugin-report';
+import type { ReportComponentSchema } from '@object-ui/types';
+
+// All three are host-provided.
+declare const reportDefinition: ReportComponentSchema;
+declare const rows: Array<Record<string, unknown>>;
+declare const refetch: () => void;
 
 function LegacyReportPage() {
   return (
@@ -89,9 +107,13 @@ the report declares no object, no field, no aggregate and no date bucket of its
 own. `defineReport` validates at authoring time and returns the parsed shape
 `ReportRenderer` takes as `schema`:
 
-```ts
+```tsx
 import { defineReport } from '@objectstack/spec/ui';
 import { ReportRenderer } from '@object-ui/plugin-report';
+import type { DataSource } from '@object-ui/types';
+
+// `ds` is host-provided.
+declare const ds: DataSource;
 
 const report = defineReport({
   name: 'opp_by_stage',
@@ -234,6 +256,11 @@ defineReport({
 `series`, `colors`, `height`, `showDataLabels`, `annotations` and `interaction`
 are passed through to the chart as authored.
 
+The chart runs its own `xAxis` × `yAxis` dataset query, so it binds the same way
+on every non-`joined` type. It draws above a `tabular` or `summary` table, and
+below the cross-tab of a `matrix` that declares `columns`; there `xAxis` may name
+a `rows` or a `columns` dimension.
+
 ## Server-side aggregation + drill-down
 
 A dataset-bound report selects its dimensions (`rows`, and for `matrix` also
@@ -253,6 +280,12 @@ dimension names (ADR-0021 D2).
 
 ```tsx
 import { ReportRenderer, type DatasetDrillArgs } from '@object-ui/plugin-report';
+import type { DataSource, SpecReport } from '@object-ui/types';
+
+// `report`, `dataSource` and `router` are host-provided.
+declare const report: SpecReport;
+declare const dataSource: DataSource;
+declare const router: { push: (href: string) => void };
 
 <ReportRenderer
   schema={report}
@@ -284,13 +317,23 @@ The server does **not** currently evaluate `` cel`...` `` expressions
 embedded in filter values. Use module-load ISO strings instead:
 
 ```ts
+import { defineReport } from '@objectstack/spec/ui';
+
 const daysAgo = (n: number): string => {
   const d = new Date();
   d.setUTCDate(d.getUTCDate() - n);
   return d.toISOString().slice(0, 10);
 };
 
-runtimeFilter: { close_date: { $gte: daysAgo(30) } }
+defineReport({
+  name: 'recent_pipeline',
+  label: 'Recent Pipeline',
+  type: 'summary',
+  dataset: 'opportunity_pipeline',
+  rows: ['stage'],
+  values: ['amount_sum'],
+  runtimeFilter: { close_date: { $gte: daysAgo(30) } },
+});
 ```
 
 See the bundled CRM `customer_churn_signals` demo for the full pattern.
@@ -405,8 +448,12 @@ does not compile. It is the one `async` export function, resolving to a
 
 ```tsx
 import { exportWithLiveData } from '@object-ui/plugin-report';
+import type { DataSource, ReportComponentSchema } from '@object-ui/types';
 
 // `myAdapter` is a host-provided DataSource (see @object-ui/data-*).
+declare const myAdapter: DataSource;
+declare const report: ReportComponentSchema;
+
 const result = await exportWithLiveData(report, {
   dataSource: myAdapter,
   resource: 'orders',
@@ -427,6 +474,10 @@ spreadsheet line number:
 
 ```tsx
 import { exportExcelWithFormulas } from '@object-ui/plugin-report';
+import type { ReportComponentSchema } from '@object-ui/types';
+
+declare const report: ReportComponentSchema;
+declare const rows: Array<Record<string, unknown>>;
 
 exportExcelWithFormulas(report, rows, {
   columns: [
@@ -434,12 +485,22 @@ exportExcelWithFormulas(report, rows, {
     { name: 'total', header: 'Total', formula: '=B{ROW}*C{ROW}' },
   ],
   includeAggregationRow: true,
+  locale: 'de-DE',
 });
 ```
 
 Omitting `columns` derives them from `report.fields`. `includeAggregationRow`
 appends a totals row built from each field's `aggregation`.
 
+`locale` is the BCP-47 tag the numeric cells are formatted in — above, an
+`amount` of `1234.5` writes `1.234,50` rather than `1,234.50`. Pass the tag the
+session renders in: `useDisplayLocale()` from `@object-ui/i18n` in React, or
+whatever your non-React caller resolved. This function is not a component and a
+display locale is a property of the session rather than of the authored report
+schema, so its caller is the only place the tag can come from. Omitted, cells
+format in `'en'` — the display channel's own last resort, which is neither
+`'en-US'` nor the machine's locale (objectui#10020).
+
 ### Scheduled export
 
 A schedule is **data on the report schema**, not a component: it is
@@ -453,9 +514,11 @@ and a completion callback:
 
 ```ts
 import { createScheduleTrigger } from '@object-ui/plugin-report';
-import type { ReportComponentSchema, ReportScheduleConfig } from '@object-ui/types';
+import type { DataSource, ReportComponentSchema, ReportScheduleConfig } from '@object-ui/types';
 
 // `dataSource` and `notify` are host-provided.
+declare const dataSource: DataSource;
+declare const notify: (recipients: string[], subject: string | undefined) => void;
 
 const report: ReportComponentSchema = {
   type: 'report',
@@ -490,19 +553,23 @@ it ran.
 
 ### Schema-Driven Usage
 
-Importing the package registers three component types with `ComponentRegistry`:
+Importing the package registers two component types with `ComponentRegistry`:
+
+| `type`          | Component        | Notes                                                        |
+| --------------- | ---------------- | ------------------------------------------------------------ |
+| `report`        | `ReportRenderer` | The dispatcher. A spec report goes under its `report` key.   |
+| `report-viewer` | `ReportViewer`   | Presentation-layer viewer.                                   |
 
-| `type`          | Component        | Notes                                              |
-| --------------- | ---------------- | -------------------------------------------------- |
-| `report`        | `ReportRenderer` | The dispatcher.                                    |
-| `spec-report`   | `ReportRenderer` | Spec-native alias; the report goes under `report`.  |
-| `report-viewer` | `ReportViewer`   | Presentation-layer viewer.                         |
+To embed a report, wrap the `@objectstack/spec` report definition (`ReportSchema`)
+in a `report` node's `report` member. When `report` is present, the node renders
+that report and reads none of its own presentation keys.
 
 ```json
 {
-  "type": "spec-report",
+  "type": "report",
   "report": {
     "name": "opp_by_stage",
+    "label": "Opportunities by Stage",
     "type": "summary",
     "dataset": "opportunity_pipeline",
     "rows": ["stage"],
@@ -513,7 +580,9 @@ Importing the package registers three component types with `ComponentRegistry`:
 
 There is no `report-builder` component type — the authoring component that name
 addressed was removed in the 9.0 cutover, so a node declaring it resolves to
-nothing.
+nothing. `spec-report` is retired too (objectui#11440): it was an alias of `report`
+carrying the same wrapper, and a node declaring it now resolves to nothing. Write
+`"type": "report"` instead; the `report` member is unchanged.
 
 ### Type-aware cell rendering
 

package/dist/DatasetReportRenderer.d.ts

@@ -24,6 +24,9 @@
  *   so an older server that returns no `totals` renders the plain cross-tab
  *   with no totals row/column. A matrix without `columns` degrades to the
  *   flat grouped table.
+ * - `chart` (any non-joined type) → the embedded chart, its own
+ *   `chart.xAxis` × `chart.yAxis` dataset query: above the grouped / flat
+ *   table, below the matrix cross-tab (objectui#10964).
  * - `joined` → a vertical stack of blocks, each its own dataset-bound table,
  *   with the report-level `runtimeFilter` merged into every block.
  *
@@ -155,7 +158,7 @@ export type ReportChartPlan =
  | {
     kind: 'single_value';
 }
-/** Tabular family — the grouped table beneath IS the rendering; no duplicate chart. */
+/** Tabular family — the report's own table beside it IS the rendering; no duplicate chart. */
  | {
     kind: 'tabular';
 }
@@ -176,8 +179,8 @@ export type ReportChartPlan =
  * - the single-value families (`gauge` / `solid-gauge` / `metric` / `kpi` /
  *   `bullet`) render the measure as a number — the spec's own comment calls
  *   them "honest single-value variants pending a real dial/target renderer";
- * - `table` / `pivot` add no duplicate chart: the grouped table that always
- *   renders beneath the chart slot is exactly the tabular presentation;
+ * - `table` / `pivot` add no duplicate chart: the table that always renders
+ *   beside the chart slot is exactly the tabular presentation;
  * - anything else is out-of-spec and gets a visible notice.
  *
  * `combo` joined `ChartTypeSchema` in spec 17.0.0-rc.1 and routes as a series

package/dist/LiveReportExporter.d.ts

@@ -13,6 +13,13 @@ export interface LiveExportOptions {
     format?: ReportExportFormat;
     /** Export config override */
     exportConfig?: ReportExportConfig;
+    /**
+     * BCP-47 display tag for the HTML / PDF "Generated:" time — in React,
+     * whatever `useDisplayLocale()` (`@object-ui/i18n`) returned for the session.
+     * Omitted, `exportReport` falls back to the display channel's own last
+     * resort, never to the machine's locale (objectui#9909).
+     */
+    locale?: string;
 }
 /**
  * Excel column configuration for formatted export
@@ -83,6 +90,18 @@ export declare function exportExcelWithFormulas(report: ReportComponentSchema, d
     columns?: ExcelColumnConfig[];
     filename?: string;
     includeAggregationRow?: boolean;
+    /**
+     * BCP-47 tag the numeric cells are formatted in — in React, whatever
+     * `useDisplayLocale()` (`@object-ui/i18n`) returned for the session.
+     *
+     * It lives on the OPTIONS BAG because this module is not a component and
+     * has no hook to read: a locale can only reach it from its caller, and a
+     * report schema is the wrong carrier for it (a display locale is a property
+     * of the session, not of the authored report). Omitted, it falls back to
+     * the display channel's own last resort — never to `'en-US'`, and never to
+     * a dropped tag, which would mean the MACHINE's locale (objectui#10020).
+     */
+    locale?: string;
 }): void;
 /**
  * Create a schedule trigger that can be invoked by workflow engines.

package/dist/ReportExportEngine.d.ts

@@ -2,6 +2,21 @@ import { ReportComponentSchema, ReportExportConfig, ReportExportFormat } from '@
 /**
  * Report Export Engine
  * Handles exporting report data to various formats using browser-native APIs.
+ *
+ * ## The export's display locale (objectui#9909)
+ *
+ * The HTML and PDF exports stamp a "Generated:" time into a file the reader
+ * downloads and keeps. That time used to be `new Date().toLocaleString()` —
+ * no tag, i.e. the MACHINE's locale, which is neither of the repo's two
+ * locale channels. The functions below take the tag as a trailing, OPTIONAL
+ * `locale` parameter — the same additive shape `formatValue` took in
+ * objectui#10020, and for the same reason: they are published exports, so a
+ * required parameter would break every existing caller. Omitted, it falls back
+ * to {@link DISPLAY_LOCALE_LAST_RESORT}, the display channel's own last resort
+ * — never to a dropped tag. In React the caller passes `useDisplayLocale()`;
+ * `ReportViewer` does. ⚠️ A display locale is a property of the SESSION, not
+ * of the authored report, so it is deliberately NOT a `ReportExportConfig`
+ * member: that type is authored metadata (`exportConfigs` on the schema).
  */
 /**
  * Export report data as CSV
@@ -14,11 +29,11 @@ export declare function exportAsJSON(report: ReportComponentSchema, data: any[],
 /**
  * Export report as HTML (printable format)
  */
-export declare function exportAsHTML(report: ReportComponentSchema, data: any[], config?: ReportExportConfig): void;
+export declare function exportAsHTML(report: ReportComponentSchema, data: any[], config?: ReportExportConfig, locale?: string): void;
 /**
  * Export report as PDF using browser print
  */
-export declare function exportAsPDF(report: ReportComponentSchema, data: any[], config?: ReportExportConfig): void;
+export declare function exportAsPDF(report: ReportComponentSchema, data: any[], config?: ReportExportConfig, locale?: string): void;
 /**
  * Export report as Excel-compatible CSV (with BOM for proper UTF-8 in Excel)
  */
@@ -26,4 +41,4 @@ export declare function exportAsExcel(report: ReportComponentSchema, data: any[]
 /**
  * Main export function - routes to correct format handler
  */
-export declare function exportReport(format: ReportExportFormat, report: ReportComponentSchema, data: any[], config?: ReportExportConfig): void;
+export declare function exportReport(format: ReportExportFormat, report: ReportComponentSchema, data: any[], config?: ReportExportConfig, locale?: string): void;

package/dist/ReportRenderer.d.ts

@@ -1,6 +1,6 @@
 import { SpecReport, DataSource } from '@object-ui/types';
-import { LegacyReportRendererProps } from './LegacyReportRenderer';
-import { DatasetDrillArgs } from './DatasetReportRenderer';
+import { LegacyReportRendererProps } from './LegacyReportRenderer.js';
+import { DatasetDrillArgs } from './DatasetReportRenderer.js';
 /**
  * ReportRenderer
  *

package/dist/displayLocale.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * displayLocale — the one place this package spells the display locale's LAST
+ * RESORT, and the one place it formats a number with a THREADED tag.
+ *
+ * Two module-private copies of both used to be the alternative (`formatValue`
+ * and `LiveReportExporter` each hard-coded `'en-US'`), which is how the
+ * divergence objectui#10020 records happened in the first place: a package can
+ * only contradict a contract it states in more than one place.
+ */
+/**
+ * `'en'` — the tag `useDisplayLocale` (`@object-ui/i18n`) itself falls back to
+ * when neither the tenant's regional default nor the active UI language
+ * answers. Quoted from that hook's contract, which names BOTH alternatives as
+ * wrong answers:
+ *
+ *   > `'en'` — a concrete last resort rather than `undefined`. `undefined`
+ *   > would hand `Intl` the *machine's* locale, which is invisible in review
+ *   > and non-deterministic in CI; `'en'` at least fails the same way
+ *   > everywhere. Note this is `'en'`, not `'en-US'`: the point of
+ *   > objectui#4033 is that `en-US` is not the world's default.
+ *
+ * So this constant may become neither `'en-US'` (the tag objectui#10020 removed
+ * from five display sites in this package) nor `undefined` (objectui#9909's
+ * separate defect shape, which `ReportExportEngine.ts`'s "Generated:" time
+ * carried until that card threaded a locale there, defaulting to this same
+ * constant).
+ *
+ * ⚠️ It is a local re-spelling of that literal, not an import of it:
+ * `@object-ui/i18n` exports the HOOK but no constant for the tag inside it, and
+ * a plain formatter cannot call a hook. Anything that moves the contract's last
+ * resort has to move this line too — pinned from the behavioural side by
+ * `__tests__/reportDisplayLocale-10020.test.tsx`, which asserts the omitted
+ * argument agrees with an explicit `'en'`.
+ */
+export declare const DISPLAY_LOCALE_LAST_RESORT = "en";
+/**
+ * `Number.prototype.toLocaleString` with a tag that came from OUTSIDE this
+ * module.
+ *
+ * The retry is load-bearing rather than defensive, and it is the threading
+ * itself that makes it so: a hard-coded literal can never be malformed, while a
+ * threaded tag originates in tenant configuration (ADR-0053) and reaches here
+ * verbatim. `Intl` throws `RangeError` on a malformed tag — measured on
+ * `'en_US'`, underscore instead of hyphen, the likeliest such typo — and these
+ * call sites are inside a cell render, so an uncaught throw takes the whole
+ * report down rather than misformatting one number.
+ *
+ * ⚠️ The degradation is to {@link DISPLAY_LOCALE_LAST_RESORT}, NOT to a dropped
+ * tag, because this package's display tags follow `useDisplayLocale`'s
+ * contract: in React the tag IS that hook's value, and an omitted one defaults
+ * to the hook's own last resort. Under that contract, dropping the tag hands
+ * `Intl` the machine's locale — the other answer the contract quoted above
+ * rules out, non-deterministic in CI and invisible in review.
+ *
+ * `@object-ui/core`'s sibling retry (`formatNumberInLocale`, through
+ * `formatDisplayNumber`) drops the tag instead. That is a deliberate
+ * difference, not an oversight, and not a wrong answer: `core` is the
+ * React-free formatter, and where its retry lands is what its own declared
+ * contract (`DisplayNumberFormatOptions.locale`) gives a caller with no tag in
+ * hand — the runtime default, the viewer's own environment. Each retry follows
+ * its own package's declared contract (objectui#10098).
+ */
+export declare function formatNumberInDisplayLocale(value: number, locale: string, options?: Intl.NumberFormatOptions): string;

package/dist/formatValue.d.ts

@@ -2,5 +2,23 @@ import { ReportField } from '@object-ui/types';
 /**
  * Format a cell value based on the field definition.
  * Handles number (with thousand separators), currency, percent, and date formatting.
+ *
+ * `locale` is the BCP-47 DISPLAY tag the numeric branches below format in —
+ * in React, whatever `useDisplayLocale()` returned for the session. It is
+ * OPTIONAL, and that is a deliberate contract decision rather than convenience
+ * (objectui#10020): this function is a published export of
+ * `@object-ui/plugin-report`, so a REQUIRED third parameter would be a breaking
+ * change to a public signature. Optional is purely additive — everything that
+ * compiled before compiles after.
+ *
+ * ⚠️ The cost of that choice, named rather than hidden: an OPTIONAL locale
+ * leaves a leg that is still wrong when nobody passes one. Closing it is the
+ * caller's job, and inside this repo every caller does — `ReportViewer` is a
+ * component and resolves `useDisplayLocale()` itself at all three of its call
+ * sites, pinned in `__tests__/reportDisplayLocale-10020.test.tsx`. An OPTIONAL
+ * parameter nobody passes is the same defect with a longer signature.
+ *
+ * The default is {@link DISPLAY_LOCALE_LAST_RESORT} — the contract's own last
+ * resort, which is neither the `'en-US'` this card removed nor an absent tag.
  */
-export declare function formatValue(value: any, field?: ReportField): string;
+export declare function formatValue(value: any, field?: ReportField, locale?: string): string;

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { ReportRenderer } from './ReportRenderer';
-import { LegacyReportRenderer } from './LegacyReportRenderer';
-import { ReportViewer } from './ReportViewer';
-import { DatasetReportRenderer, isDatasetReport } from './DatasetReportRenderer';
+import { ReportRenderer } from './ReportRenderer.js';
+import { LegacyReportRenderer } from './LegacyReportRenderer.js';
+import { ReportViewer } from './ReportViewer.js';
+import { DatasetReportRenderer, isDatasetReport } from './DatasetReportRenderer.js';
 export { ReportRenderer, LegacyReportRenderer, ReportViewer, DatasetReportRenderer, isDatasetReport };
-export type { ReportRendererProps, ReportRendererSchema } from './ReportRenderer';
-export type { LegacyReportRendererProps } from './LegacyReportRenderer';
-export type { DatasetReportRendererProps, DatasetDrillArgs } from './DatasetReportRenderer';
-export { formatValue } from './formatValue';
-export { exportReport, exportAsCSV, exportAsJSON, exportAsHTML, exportAsPDF, exportAsExcel } from './ReportExportEngine';
-export { exportWithLiveData, exportExcelWithFormulas, createScheduleTrigger, } from './LiveReportExporter';
-export type { LiveExportOptions, LiveExportResult, ExcelColumnConfig, ScheduleTriggerCallback, } from './LiveReportExporter';
-export { mergeFilters } from './mergeFilters';
+export type { ReportRendererProps, ReportRendererSchema } from './ReportRenderer.js';
+export type { LegacyReportRendererProps } from './LegacyReportRenderer.js';
+export type { DatasetReportRendererProps, DatasetDrillArgs } from './DatasetReportRenderer.js';
+export { formatValue } from './formatValue.js';
+export { exportReport, exportAsCSV, exportAsJSON, exportAsHTML, exportAsPDF, exportAsExcel } from './ReportExportEngine.js';
+export { exportWithLiveData, exportExcelWithFormulas, createScheduleTrigger, } from './LiveReportExporter.js';
+export type { LiveExportOptions, LiveExportResult, ExcelColumnConfig, ScheduleTriggerCallback, } from './LiveReportExporter.js';
+export { mergeFilters } from './mergeFilters.js';