@object-ui/plugin-report 17.5.0 → 17.7.0

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.
  *
@@ -84,6 +87,17 @@ interface DatasetReportLike {
     columns?: string[];
     values?: string[];
     runtimeFilter?: Record<string, unknown>;
+    /**
+     * ⛔ NOT an authorable key, and NEVER applied as a filter (objectui#5137).
+     *
+     * `ReportSchema` (`@objectstack/spec`) is `z.core.$strict` and rejects
+     * `filter` outright, naming the replacement itself
+     * (`Did you mean … → runtimeFilter?`) — so a document carrying it did not
+     * arrive through the validated path. It stays declared for exactly one reason:
+     * so {@link warnOnRejectedFilterAlias} can SEE it on a stored document and
+     * say out loud that no filter was applied. Reading it AS a scope filter is
+     * the consumer tolerance this card removed. Author `runtimeFilter`.
+     */
     filter?: Record<string, unknown>;
     /**
      * Result ordering, most significant key first (framework#3916). Each `by`
@@ -117,6 +131,8 @@ export interface DatasetReportRendererProps {
 }
 /** `true` when this report should render through the dataset path. */
 export declare function isDatasetReport(value: unknown): value is DatasetReportLike;
+/** Reset the warn-once memo. Exported for tests. */
+export declare function resetReportFilterAliasWarnings(): void;
 /**
  * Resolve a report's declared `type` — the spec's `ReportType`
  * (`ui/report.zod.ts`: `tabular | summary | matrix | joined`) — to the
@@ -142,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';
 }
@@ -163,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';