@object-ui/plugin-report 17.3.0 → 17.6.0

package/CHANGELOG.md

@@ -1,5 +1,695 @@
 # @object-ui/plugin-report
 
+## 17.6.0
+
+### Minor Changes
+
+- a945271: `DatasetReportRenderer` no longer reads `filter` as an alias for `runtimeFilter`.
+  
+  `filter` is not an authorable key. `ReportSchema` in `@objectstack/spec` (17.0.0)
+  is `z.core.$strict` and rejects it outright, going out of its way to name the
+  replacement: ``Unrecognized key(s) on this report: `filter`. Did you mean
+  `filter` → `runtimeFilter`?`` The renderer accepted the rejected spelling anyway,
+  at two sites — the report-level `report.runtimeFilter ?? report.filter` and the
+  per-joined-block `block.runtimeFilter ?? block.filter`. Metadata that could not
+  be authored through the validated path still rendered when it arrived by some
+  other route, so the strictness the spec promises was not the strictness the
+  runtime enforced. It matters most for AI-authored metadata: a generator emitting
+  `filter` got a working report from this renderer and a hard validation failure
+  from anything that parsed the document first, and which one the author met was a
+  function of which path the document travelled.
+  
+  **Behaviour change — read this if you store report documents.** A stored document
+  still carrying `filter` no longer has that filter applied: it renders
+  **unfiltered**, showing rows the report was scoped to exclude. Server-side
+  permissions are unaffected and still apply, so this is not an access-control
+  change — it is a report showing more rows than its author intended. Scored
+  `minor` per this repo's version policy (AGENTS.md §版本号策略), which reserves
+  `major` for the synchronized `@objectstack` major bump; the narrowing is
+  described here rather than encoded in the number.
+  
+  Because rendering unfiltered *in silence* would be worse than an error, the
+  dropped key is not silent. When a document carrying `filter` reaches the
+  renderer, a dev-mode warning fires once per offending report or block, naming the
+  key, quoting the spec's own rename hint verbatim (so an author meets one message
+  rather than two dialects of one message), and stating that no filter was applied.
+  It is a no-op under `NODE_ENV=production` and changes no types.
+  
+  Fix your documents by renaming `filter` to `runtimeFilter` — the key the schema
+  actually declares, and the one the suggestion has always pointed at. Reports that
+  already author `runtimeFilter`, and hosts that pass the `runtimeFilter` prop, are
+  entirely unaffected.
+
+### Patch Changes
+
+- cb5a7de: A report's embedded chart now paints its category dimension's own option colours and renders ordered-sequence charts (funnel/pyramid) in the field's declared picklist order — the same two derivations a dashboard chart has always gotten for the identical dimension (objectui#4906).
+  
+  `DatasetReportChart` (`DatasetReportRenderer.tsx`) resolved its dimension's option **labels** but called neither `buildOptionColorMap` nor `buildCategoryOrder` — the two `@object-ui/core` helpers `DatasetWidget` (plugin-dashboard) already runs off the same resolved field metadata. The chart forwarded only an author-supplied `colors` record (objectui#4877); with none authored it fell back to the positional palette, and a funnel's stages sorted by value instead of the declared pipeline.
+  
+  This is convergence onto an already-ruled behavior, not new capability: the report path now runs the identical `useDatasetDimensionMeta` → `localizeFieldOptions` → `buildOptionColorMap`/`buildCategoryOrder` chain the dashboard widget uses (framework#3588's declared-picklist-order ruling), reused rather than re-derived.
+  
+  **This visibly changes rendering for an existing report** that groups by a select/lookup dimension carrying option colours, or is declared on an ordered field:
+  
+  - a chart with no authored `colors` now paints each category in that dimension's own option colour (e.g. a `health` dimension now paints its own green/amber/red) instead of the renderer's positional palette;
+  - a `funnel`/`pyramid` chart now orders its stages by the field's declared picklist order instead of sorting by value.
+  
+  Precedence is unchanged and preserved: an authored `colors` record (objectui#4877) still wins over the derived per-category map, merged UNDER it exactly as the dashboard already does — an author's explicit colour for a category is never overridden by the field's own.
+- 0237208: docs(plugin-report): teach the dataset-bound report as the sole authoring shape
+  
+  `packages/plugin-report/README.md` and `content/docs/plugins/plugin-report.mdx`
+  still taught the pre-9.0 query form (`objectName` + column-definition `columns` +
+  `groupingsDown` / `groupingsAcross`) as the live way to write a report, and named
+  three renderers plus `applyInMemoryAggregation` that were removed at the ADR-0021
+  cutover. The current `ReportSchema` is strict and rejects that form outright, so
+  every copyable example on both pages now authors the dataset-bound shape
+  (`dataset` + `rows` / `columns` / `values`, `runtimeFilter`, `order`, `drilldown`,
+  `chart`) through `defineReport`. Stored pre-9.0 documents keep one clearly
+  labelled migration-only section describing the lossy bridge that renders them and
+  the key-by-key direction of migration.
+- 82a9417: docs(plugin-report): rewrite the README export snippets against the real export signatures
+  
+  The `### Export` and `### Live Export` snippets called every export function with
+  the wrong arity or argument order. Every name was real, so the name-set check
+  could not see it — only the calls were wrong:
+  
+  - The six format exporters are `(report: ReportComponentSchema, data: any[], config?: ReportExportConfig): void`.
+    The README called them `(data, filename)`, so a filename string landed in the
+    `data` slot the engine iterates as rows, and there is no filename parameter at
+    all — the download name comes from `config.filename`, else `report.title`. All
+    five are synchronous `void`, so the snippet's `await` was inert.
+    `exportReport` takes the format **first**, which no snippet showed.
+  - `exportWithLiveData(report, options)` requires `dataSource` and `resource` in
+    `LiveExportOptions`; the README passed only `{ format: 'pdf' }`.
+  - `exportExcelWithFormulas(report, data, options)` takes three parameters; the
+    README passed two, and spelled the column key `field` where `ExcelColumnConfig`
+    has the required `name` and `header`. Formula templates use the `{ROW}`
+    placeholder, which the old `SUM(B2:B100)` never exercised.
+  
+  The rewritten blocks are the exporters' own (correct) JSDoc examples, and each
+  one now compiles against the package's built `dist/index.d.ts`. Docs only — no
+  API, export surface or runtime behaviour changed.
+- f331f5a: Docs only: `packages/plugin-report/README.md` no longer teaches three exports the
+  package does not have (objectui#5016). Each was judged individually against the
+  entry module's export surface, and all three turned out to be **survivors of the
+  9.0 cutover** rather than renames — `CHANGELOG.md` records `ReportBuilder`,
+  `ScheduleConfig` and the drill helpers as removed with the pre-9.0 query-form
+  renderers, and the README kept teaching them afterwards:
+  
+  - **`ReportBuilder`** — taught as the main editor component. Removed; there is no
+    authoring component in this package. The Quick Start now teaches the real ones,
+    with their real signatures: `ReportRenderer` (the dispatcher, which takes the
+    report as `schema`), `DatasetReportRenderer` (which takes it as `report`), and
+    `ReportViewer` — whose props are `{ schema, onRefresh }`, so the old
+    `< ReportViewer report={…} showToolbar />` would not have compiled either.
+    `report` / `showToolbar` are keys inside a `ReportViewerSchema`.
+  - **`registerDrillHandler(actionRunner, …)`** — taught as the drill registration
+    call. Removed, and its mechanism no longer exists: drill-down is now a host
+    callback, `onDrill?: (args: DatasetDrillArgs) => void`, and the host owns
+    navigation because the renderer only knows dimension names (ADR-0021 D2). The
+    section is rewritten around what a click actually emits, including why
+    `objectFilter` (raw stored values) is what filters select/lookup dimensions
+    correctly where a display-label `groupKey` would not.
+  - **`ScheduleConfig`** — taught as a configuration component. Removed. A schedule
+    is *data* on the report schema: `ReportComponentSchema.schedule`, typed
+    `ReportScheduleConfig`. Both types live in `@object-ui/types` and are not
+    re-exported here, so the corrected snippet imports them from there —
+    `createScheduleTrigger` is the real export, and its real signature takes
+    `(report, dataSource, resource, onComplete)` and returns
+    `() => Promise< LiveExportResult[] >`, not the single callback the old snippet
+    passed.
+  
+  Two further leftovers of the same removal are corrected: the stale survivor
+  sentence that listed `ReportBuilder` as still available, and the schema-driven
+  example's `"type": "report-builder"`, which no component registers — the
+  registered types are `report`, `spec-report` and `report-viewer`, now listed
+  explicitly. The two feature bullets asserting the removed mechanisms (a
+  `useReportData()` query pipeline, an `ActionRunner`-dispatched `drill` action)
+  state the dataset-bound path instead.
+  
+  No code, types or runtime behaviour change — the diff is one README and this
+  changeset. The correction reaches npm with the package's next publish, which is
+  why it declares a patch: `README.md` is in the package's published `files`.
+- 5ffcc14: fix(plugin-report): forward the chart chrome and series presentation `ReportChartSchema` declares (objectui#4877)
+  
+  A report's embedded chart forwarded exactly six keys to the registered chart
+  component — `chartType`, `data`, `height`, `isAnimationActive`, `series`,
+  `xAxisKey`. Everything else `ReportChartSchema` declares as authorable never
+  left the report renderer, so it was inert metadata: the author writes it, the
+  schema accepts it, nothing reads it.
+  
+  `showLegend` was the sharpest case because dropping it does not merely ignore
+  the author, it INVERTS them: `AdvancedChartImpl` computes
+  `legendVisible = showLegend !== false`, so an absent value means the legend is
+  on and an explicit `showLegend: false` still drew one.
+  
+  Now lowered, under objectui#4229's ruled data/presentation split:
+  
+  - chrome — `showLegend`, `showDataLabels`, `colors` (both the positional-palette
+    array and the per-category record), `subtitle`, `description`, `annotations`,
+    `interaction`, `height`;
+  - per-series presentation — `color`, `stack`, `type`, `yAxis`, `dashArray`,
+    `opacity`, `variant`, matched by `series[].name` so series MEMBERSHIP stays
+    with the dataset.
+  
+  `title` is deliberately not forwarded: the report renderer paints it as its own
+  heading above the plot, and forwarding it would draw a second one inside the
+  chart's frame. `aria` is not lowered either — nothing on this path reads it
+  (`AdvancedChartImpl` has no `aria` prop, and this renderer hands the component a
+  schema directly rather than through `SchemaRenderer`'s flat ARIA injection), so
+  forwarding it would move declared-but-unread one layer down.
+  
+  The two helpers (`chartConfigPresentation`, `mergeAuthoredPresentation`) moved
+  from `plugin-dashboard`'s `DatasetWidget` to `@object-ui/core` beside
+  `buildChartSeries`, the derivation they merge onto, so both surfaces lower one
+  vocabulary once instead of keeping a second copy (the duplication objectui#4389
+  filed as a defect). `@object-ui/core` additionally exports `mergeAuthoredSeries`
+  — the series merge alone — for a surface whose axes are bare dimension/measure
+  NAME strings rather than spec `ChartAxis` objects, which is what a report chart
+  declares. `DatasetWidget` re-exports both names, so its public surface and its
+  rendering are unchanged.
+- 6bb39c4: 报表内嵌图表的度量显示名按三级回落解析，不再直接印原始 `name`
+  
+  数据集绑定的 report chart 此前把度量原样交给图表组件（`series: [{ dataKey }]`，无 label），
+  于是图例、标记 tooltip 与单值卡片的说明文字都落回 dataKey——在全中文控制台上打出
+  `potential_upside_tons`，而同一张报表下方的汇总表、以及绑定同一数据集的 dashboard 图表
+  都能正确解析出授权 `label`。`ReportChartSchema` 自 rc.1 起声明的 `series[].label` 也从未
+  被读取，作者因此没有任何可授权的手段控制这个字符串。
+  
+  现按三级回落解析，与汇总表和 dashboard 的既有口径对齐：
+  
+  1. `chart.series[]` 中 `name` 命中该度量的条目的 `label`（spec 的 `I18nLabel`，按控制台
+     语言解析；同名重复以第一条为准）；
+  2. 绑定数据集的度量 `label`（结果字段的 `label`，即汇总表表头一直在读的同一个值）；
+  3. 度量 `name` 兜底。
+  
+  图例与 tooltip 同源同修：`ChartRenderer` 把 series 的 `label` 写进 `config[dataKey].label`，
+  三处读的是同一个输入。单值族（`metric`/`kpi`/`gauge`）的说明文字与系列图共用这一次解析。
+- 5ffcc14: fix(plugin-report): route a report's embedded chart through `buildChartSeries` so a NULL category is bucketed (objectui#4878)
+  
+  `DatasetReportChart` built its rows as `relabelDimensions(state.rows, …)` and
+  handed them to the registered chart component verbatim. Nothing on that path
+  bucketed a null dimension value, so a report chart passed the renderer a null
+  category — the exact input objectui#4466 measured as drawing **no mark at all**.
+  The cost is not an empty chart but a quietly wrong one: the null group vanishes
+  while the y-axis scale still accommodates it, so the chart reads as valid data.
+  
+  The dashboard and chart-view surfaces never had the defect because they route
+  through `buildChartSeries` (`@object-ui/core`), where the whole null-category
+  family was fixed. The report chart now routes through it too, so those
+  properties are INHERITED rather than re-derived on a third surface:
+  
+  - the null bucket itself (objectui#4466);
+  - its label read from the locale bundle at the call site — `@object-ui/core` is
+    React-free, so a zh console would otherwise draw the bar and label it `(None)`
+    (objectui#4500);
+  - bucket IDENTITY separate from the bucket label, so a stored value that
+    literally spells `(None)` stays a different group (objectui#4508).
+  
+  objectui#4020's three-level measure display name still outranks the label the
+  derivation assigns, including for an `{ en, 'zh-CN' }` label record: core holds
+  no i18n provider and picks first-string-wins, which is exactly the defect class
+  #4020 closed.
+  
+  A report whose chart has no null group is unchanged, byte for byte.
+- Updated dependencies [88085e3]
+- Updated dependencies [69251bf]
+- Updated dependencies [57e668f]
+- Updated dependencies [516663d]
+- Updated dependencies [41ac1b7]
+- Updated dependencies [1eaf0a1]
+- Updated dependencies [a09bc33]
+- Updated dependencies [feb6b16]
+- Updated dependencies [460c4d0]
+- Updated dependencies [0ae27f7]
+- Updated dependencies [9aecabe]
+- Updated dependencies [2533ec5]
+- Updated dependencies [78c0f9a]
+- Updated dependencies [bbe8b86]
+- Updated dependencies [8477be5]
+- Updated dependencies [279fb13]
+- Updated dependencies [2e82ab2]
+- Updated dependencies [ad07b65]
+- Updated dependencies [41f498b]
+- Updated dependencies [ef0d150]
+- Updated dependencies [f34226e]
+- Updated dependencies [564b605]
+- Updated dependencies [e1d4251]
+- Updated dependencies [40d3a33]
+- Updated dependencies [8b9dc62]
+- Updated dependencies [1184192]
+- Updated dependencies [a2a9747]
+- Updated dependencies [65e88e6]
+- Updated dependencies [a1609a6]
+- Updated dependencies [53f23bc]
+- Updated dependencies [c4533dc]
+- Updated dependencies [be60815]
+- Updated dependencies [37f6844]
+- Updated dependencies [93de4f6]
+- Updated dependencies [2b50261]
+- Updated dependencies [384f30d]
+- Updated dependencies [ac600e5]
+- Updated dependencies [97fba31]
+- Updated dependencies [232f61a]
+- Updated dependencies [d374caf]
+- Updated dependencies [5673576]
+- Updated dependencies [c1ef923]
+- Updated dependencies [911ceaa]
+- Updated dependencies [98eab36]
+- Updated dependencies [375efb4]
+- Updated dependencies [af5e292]
+- Updated dependencies [3fbbea1]
+- Updated dependencies [0bffb18]
+- Updated dependencies [3e0214c]
+- Updated dependencies [800f455]
+- Updated dependencies [dbbd38a]
+- Updated dependencies [27c9cbd]
+- Updated dependencies [5458414]
+- Updated dependencies [3241559]
+- Updated dependencies [7f96b10]
+- Updated dependencies [167ec42]
+- Updated dependencies [616a2a5]
+- Updated dependencies [6c68b13]
+- Updated dependencies [0046d8f]
+- Updated dependencies [f1d4748]
+- Updated dependencies [bea374e]
+- Updated dependencies [b1119ec]
+- Updated dependencies [5607092]
+- Updated dependencies [9f23d2b]
+- Updated dependencies [b4089be]
+- Updated dependencies [578e025]
+- Updated dependencies [b4bccc7]
+- Updated dependencies [af025ee]
+- Updated dependencies [d109a4d]
+- Updated dependencies [598c89a]
+- Updated dependencies [4a0bd17]
+- Updated dependencies [b8b9af4]
+- Updated dependencies [31676be]
+- Updated dependencies [8c0d52e]
+- Updated dependencies [b29488f]
+- Updated dependencies [9fbb9b5]
+- Updated dependencies [90517e1]
+- Updated dependencies [aff10e2]
+- Updated dependencies [70a774b]
+- Updated dependencies [9ce096f]
+- Updated dependencies [e05db88]
+- Updated dependencies [7458a41]
+- Updated dependencies [ad13d63]
+- Updated dependencies [5ffcc14]
+- Updated dependencies [d971e51]
+- Updated dependencies [97abb24]
+- Updated dependencies [deb157a]
+- Updated dependencies [9c60144]
+- Updated dependencies [e7747f1]
+- Updated dependencies [d2ce342]
+- Updated dependencies [9695da7]
+- Updated dependencies [ac2f332]
+- Updated dependencies [a777058]
+- Updated dependencies [75444e3]
+- Updated dependencies [58b8346]
+- Updated dependencies [2d0bd16]
+- Updated dependencies [a9e17b4]
+- Updated dependencies [b8ce7dc]
+- Updated dependencies [dad51e5]
+- Updated dependencies [1c9c342]
+- Updated dependencies [787c738]
+- Updated dependencies [8396656]
+- Updated dependencies [dbbd38a]
+- Updated dependencies [2165d88]
+- Updated dependencies [8871c14]
+- Updated dependencies [93fe362]
+- Updated dependencies [dfc6975]
+- Updated dependencies [3cf4de0]
+- Updated dependencies [c9dc811]
+- Updated dependencies [144ef9b]
+- Updated dependencies [138ab04]
+- Updated dependencies [a0b9e91]
+- Updated dependencies [99bd015]
+- Updated dependencies [21e4585]
+  - @object-ui/types@17.6.0
+  - @object-ui/fields@17.6.0
+  - @object-ui/i18n@17.6.0
+  - @object-ui/react@17.6.0
+  - @object-ui/plugin-grid@17.6.0
+  - @object-ui/components@17.6.0
+  - @object-ui/core@17.6.0
+
+## 17.5.0
+
+### Patch Changes
+
+- ee26e65: Analytics: the dimension label net's fetch-and-memo glue is written once, not once per surface
+
+  PR #4388 (objectui#4330) put the same React glue on two surfaces — the dashboard's `DatasetWidget` and plugin-report's dataset block. The resolution RULES were never duplicated (both call the same `@object-ui/core` helpers), but the wiring around them was: read the object schema through the host's authenticated `apiFetch`, keep the fetched metadata locale-free in state, derive the label maps in a render memo. Two copies meant two statements of the same two bug fixes, which is a drift surface rather than a defect — nothing a user could hit today, filed as objectui#4389 so it was retired deliberately.
+
+  It is now split along the layer that can actually hold each half. `@object-ui/core` gains the React-free parts — `loadDimensionFieldMeta` (the base-object read composed with the dimension walk), `deriveDimensionLabelMaps` (the locale-applying derivation) and `dimensionOptionTranslator` (binding the bundle resolver to the object that OWNS a terminal field, which for a dotted path is the relationship target). `@object-ui/react` gains `useDatasetDimensionLabels` / `useDatasetDimensionMeta`, the React wiring that cannot live in core, beside the `useViewData` / `useElementDataSource` / `useDiscovery` hooks that already read `SchemaRendererContext` the same way. Both plugins consume it; the dashboard keeps its chart-only per-category colour and category-order derivation layered locally, since a table renders no palette.
+
+  The card originally proposed `@object-ui/core` as the whole glue's home. That home was disproven by measurement and retired in the card's PM RULING #2: `SchemaRendererContext` is defined in `@object-ui/react`, which depends on core, so core importing it back is a cycle — and core is React-free by declaration, by content, and by the topology in AGENTS.md. objectui#3367 had already ruled this direction for the same family (core-canonical logic, react re-exports).
+
+  Behaviour is unchanged by construction: same read count, same best-effort fallback, same memoization boundary. The two bug fixes are now stated once and pinned at the shared hook — the read rides the host's authenticated `apiFetch` (objectui#4121, pinned by asserting that a new channel re-issues the read, i.e. that it really is in the effect's deps), and the fetched metadata stays locale-free (objectui#4030 / PR #4324, pinned by switching language at runtime and asserting the labels flip with no second metadata read). All 39 assertions PR #4388 landed across both surfaces pass unchanged, and their files are byte-identical to before.
+
+- 326a70f: Analytics: a LOCAL select dimension on a table / pivot widget — and on a dataset-bound report — now renders its option label through the locale bundle
+
+  A dashboard table grouped by a select field showed `Domestic` on a zh-CN console while the related list on the same screen showed 国内. The value was never untranslated by accident: the server resolves that dimension's display label (ADR-0021) and hands the row over carrying the object's AUTHORED English label. The locale bundle is keyed by the option's stored VALUE (`{ns}.fieldOptions.<object>.<field>.<value>`), so translating one needs the option LIST — and the table path deliberately loaded no object metadata at all, which is why objectui#4030 / PR #4324 fixed charts and dotted dimensions and left this half open.
+
+  Table, pivot and the dataset report block now take the one metadata read that gives the bundle something to translate against, and feed it to the SAME seam #4324 landed (`resolveDimensionFieldMeta` → `localizeFieldOptions` / `buildDimensionLabelMap` → `relabelDimensions`). No second resolution dialect: the map carries both the stored value and the authored label as keys, and the relabel is value-wise and idempotent, so a value the server already resolved lands on the same display it would have from the raw value. Cells, pivot headers on both axes, the server's marginal totals, the CSV export and a report's embedded chart all read the one map, which is what keeps a subtotal's bucket lookup meeting the header it belongs to.
+
+  Untranslated apps are unchanged by construction: with no bundle entry the display equals the authored label, no key is emitted, and the rows come back by identity. Identity keys stay untranslated — a drilled row or cell still filters records by the values the server sent, and measures still export as bare numbers.
+
+  This deliberately amends the acceptance boundary objectui#4263 landed ("a local-only table issues no metadata read"), which was ruled for label RESOLUTION before the read had a second consumer. The pins that stated it are rewritten in place, in the same change, and say so.
+
+- 49ae9f4: Pivot buckets encode an empty dimension value as JSON `null`, so it no longer collides with a row whose value is literally the placeholder character
+
+  objectstack#5473 / objectstack#5665 replaced the pivot's delimiter-joined ids
+  with `JSON.stringify`, because every delimiter that had been tried — an empty
+  string, a plain space, a control character — assumed the data would not contain
+  it, and each assumption failed on ordinary data. This closes the last place the
+  same assumption survived: the ids were JSON, but the VALUES fed into them were
+  spelled `String(row[d] ?? '∅')`, so an absent dimension value became the
+  ordinary string `"∅"` and shared a bucket with a row whose value literally is
+  that character (U+2205). One bucket, later row overwriting the earlier one — the
+  cell showed a different row's measure, the overwritten row was unreachable, and
+  drill-through followed the same wrong index into the wrong records, all without
+  an error. The trigger requires that character to appear as a dimension value, so
+  this is the assumption being removed rather than a defect users hit today.
+
+  An empty value now encodes as JSON `null`, which `JSON.stringify` renders as a
+  bare `null` that no string can spell. The normalization lives in
+  `@object-ui/core` as `pivotDimensionValue` (absent ⇒ `null`, everything else ⇒
+  its string form) rather than at each call site, because a placeholder spelled by
+  a caller is a placeholder that can collide again — which is exactly how this one
+  survived the previous fix. `pivotBucketId` accepts `Array<string | null>`
+  accordingly; that is a widening, so existing callers passing `string[]` are
+  unaffected.
+
+  Both renderers' bucket keys move together, which the fix requires: a bucket id
+  and the subtotal map keyed by it are built from the same expression, so changing
+  one alone would split the headers while the subtotal map still merged, landing
+  every column subtotal under the wrong header. In `plugin-dashboard`'s
+  `DatasetWidget` that is the row bucket id, the column bucket id, the cell key,
+  and both the `rowTotalById` and `colTotalById` lookups; in `plugin-report`'s
+  `DatasetReportRenderer` the single `bucketId` helper already feeds all five.
+
+  The dashboard's column bucket id also stops being a bare string and becomes a
+  one-element tuple through the same shared encoder. It was the one id in the
+  family still built by hand, on the reasoning that a single value needs no
+  boundary — true of the boundary, false of everything else the encoder does, and
+  it is why the across axis kept carrying this collision after the row ids were
+  fixed.
+
+  No display change: these placeholders only ever entered ids, never labels. An
+  unset dimension still renders through `formatDimensionValue` exactly as before,
+  and data containing neither an absent value nor that character buckets
+  identically — the ids are opaque lookup keys, never parsed back into a value,
+  never shown, never persisted.
+
+- cb315f2: Report and dataset-preview measures follow the display locale (objectui#4575)
+
+  objectui#4566 gave `formatMeasure` / `formatDimensionValue` in `@object-ui/core`
+  an optional trailing `locale` and threaded `useDisplayLocale()` through the
+  dashboard's `DatasetWidget`. The parameter is OPTIONAL by design, so the
+  producer could land without dragging every consumer with it — which left the
+  consumers it did not reach still formatting in the MACHINE's locale. A German
+  session read a report measure as `1,234.5` directly beside a dashboard measure
+  that, after #4566, rendered `1.234,5`: one number, two spellings, on the same
+  screen. That is a sharper inconsistency than the one before #4566, when both
+  surfaces were uniformly wrong.
+
+  The remaining thirteen call sites now thread `useDisplayLocale()`:
+
+  - `plugin-report`'s `DatasetReportRenderer` (ten) — the grouped table's measure,
+    dimension and grand-total cells, the embedded single-value chart's metric, and
+    the cross-tab's across-axis header, down-axis cell, measure cell, row total,
+    column total and grand total;
+  - `app-shell`'s metadata-admin `DatasetPreview` (two) — the preview table's
+    measure and dimension cells;
+  - `app-shell`'s `DatasetDefaultInspector` (one) — the measure format-hint
+    sample, which is a preview of authored formatting and so has to be rendered
+    through the channel it previews.
+
+  **English output does not move**, and that is the discriminator against the
+  sibling fix. These sites already went through `Intl` with default grouping, so
+  the only thing that changes is WHOSE locale is used — contrast objectui#4553,
+  where `formatPercent` had never grouped at all and moving en `1235%` to
+  `1,235%` WAS the fix. Every new case pins the same value in de AND in en, so
+  at least one half must fail on any runner: before the change both render in the
+  machine's locale, which is what makes the machine locale stop being a test
+  input.
+
+  Two details worth recording:
+
+  - **The cross-tab's header labels are built inside a `useMemo`**, so the locale
+    joins that dependency array. Threading it into the call alone would leave the
+    headers frozen in whatever locale they were first built with — measured, and
+    pinned by a case that changes only the locale and asserts the header
+    re-labels. Removing just the dependency entry turns exactly that one case red
+    and leaves the other nine green.
+  - **The metadata designer's `locale` prop is deliberately not used.** It carries
+    the designer's own chrome language (`useMetadataLocale()`, which resolves to
+    exactly `en-US` or `zh-CN`), not a number-formatting locale — a German session
+    gets `en-US` from it. The preview's numbers have to match what the report and
+    dashboard render for the same dataset, which is `useDisplayLocale()`.
+
+  Both packages are `patch`: their published declarations are unchanged (measured
+  against the built `.d.ts` with `dist/` cleared between builds). The threading is
+  module-local, and the one signature that gained a parameter — the file-local
+  `bucketLabel` helper — is not exported.
+
+  A side effect of the fallback: these surfaces are now DETERMINISTIC where they
+  previously followed whatever locale the machine happened to run in.
+  `useDisplayLocale` ends at a concrete `'en'` rather than the `undefined` that
+  hands `Intl` the machine's locale.
+
+- 3f5f87c: `SchemaRenderer` states its real contract — a typed, required `schema` and a deliberate forwarding surface
+
+  `SchemaRenderer` is the renderer loop: every registered SDUI component is rendered through it. It handed `forwardRef` a props type of `{ schema: SchemaNode } & Record<string, any>`, which puts `string` into `keyof Props`, so `'ref' extends keyof Props` was always true, React's `PropsWithoutRef` took its `Omit` branch, and `Omit` over a type carrying a string index signature keeps only the index signature. Every declared prop was erased. Measured on the pre-fix source: `keyof ComponentProps<typeof SchemaRenderer>` was `string` and `ComponentProps<typeof SchemaRenderer>['schema']` was `any`, while the type argument went on declaring `SchemaNode`. The other half is the same defect seen from the call site — `<SchemaRenderer />` with no schema at all, `<SchemaRenderer schema={12345} />`, and an arbitrary misspelled prop each type-checked in silence. This is objectui#4422 / PR #4438's trap in the most central component in the repo, spelled `Record<string, any>` rather than `[key: string]: any`, which is why every previous sweep's grep and both shipped guards' detector reported the site as clean.
+
+  Graded **minor, not major**, on objectui#4528's reasoning: the type argument has always DECLARED `schema`; the index signature erased it from the resolved type, and restoring what the declaration documents is a fix to the published contract rather than a contract break.
+
+  **The forwarding surface is kept, deliberately.** This component forwards every prop it does not read to the component the schema names, resolved at runtime from a plugin-extensible registry — `packages/react/README.md` documents exactly that, and `@object-ui/components`' form renderer consumes the `onSubmit` it shows being forwarded. Closing that surface would state a false contract and would force every leaf plugin's props into this package. So the two halves are separated: the `forwardRef` type argument is the honest `SchemaRendererProps`, with no index signature for `PropsWithoutRef` to collapse, and the open surface is stated once in an explicit export annotation, which nothing routes through `Omit`. The published `.d.ts` shows the erasure disappearing: `ForwardRefExoticComponent<Omit<{ schema: SchemaNode } & Record<string, any>, "ref"> & RefAttributes<any>>` becomes `ForwardRefExoticComponent<SchemaRendererProps & Record<string, any> & RefAttributes<any>>`.
+
+  `SchemaRendererProps.schema` is declared as `BaseSchema | string | null | undefined` — what this component actually handles. It previously declared `@object-ui/core`'s `SchemaNode` interface, which requires `type: string` and so contradicted the component's own early returns for strings and nullish, while every caller held `@object-ui/types`' wider union. The erasure hid that mismatch completely.
+
+  **One declared behaviour change.** A non-object, non-string primitive schema now renders as its own text. It previously fell through to the shallow copy `{ ...schema }`, which spreads a primitive to an empty object, lost the `type` the renderer then looked up, and surfaced the red "Unknown component type: undefined" box — an accident of the spread rather than a decision. The declared props type excludes `number` / `boolean` so no author is invited to pass them; the runtime handling is defence-in-depth for untyped callers and stored metadata. Strings, `null`, `undefined`, `0` and `false` render exactly as before, and an object naming an unregistered type still gets the error box; all four are pinned.
+
+  Latent defects the erasure had been hiding, each surfaced by the repo-wide type-check and fixed at its call site: `DashboardRenderer` cast its widget schema to `Record<string, any>`, dropping the `type` every branch of `getComponentSchema` sets; `DashboardGridLayout`'s equivalent now states its return type instead of inferring a union that admitted a shape with no `type`; and `ReportViewer` handed a section's `content` array to the renderer whole, so a multi-node section rendered the unknown-component box instead of its content — arrays are mapped rather than widened into the renderer's declared input.
+
+  A repo-wide structural guard replaces the two per-package siblings' blocked direction: it judges every `forwardRef` in `packages/*/src` (219 sites) and its detector resolves `Record<string, …>` and `string`-keyed mapped types in addition to literal index signatures — the spelling the previous detector went blind on. It judges the type argument only, where an index signature is an accidental eraser, and never an export annotation, where one is a stated contract.
+
+- 31ab1ac: fix(print): `window.print()` produces a usable page, and the Print buttons say what they do
+
+  The list, report and dashboard Print controls were bare `window.print()` calls with no
+  print stylesheet, so the browser printed the whole console — sidebar, top bar, chat rail,
+  toasts — with the data table clipped to a single viewport. With no label to the contrary
+  they were being accepted against "export to PDF" requirements, which they have never been.
+
+  - `@object-ui/app-shell/styles.css` gains a shared `@media print` block: it hides the shell
+    chrome, prints the active content area full-width, releases the viewport-height flex chain
+    so long tables paginate instead of clipping, repeats table headers on every sheet, and
+    neutralises dark mode (which otherwise prints white-on-white). One sheet serves list,
+    report and dashboard.
+  - The list and report Print buttons carry a tooltip and accessible name stating that they
+    open the browser's own print dialog and are not a PDF export (new `common.printDialogHint`,
+    translated in all ten locale packs).
+  - The dashboard's `export_dashboard_pdf` action no longer toasts "Preparing PDF export…" —
+    it names the print dialog it actually opens (`dashboardActions.pdfPreparing` is replaced by
+    `dashboardActions.printDialogOpening`).
+
+  No control was removed and no headless detection was added. A real print/PDF primitive
+  remains out of scope (`objectstack-ai/objectstack#1301`, closed NOT_PLANNED).
+
+- Updated dependencies [0e67b53]
+- Updated dependencies [ceccdcf]
+- Updated dependencies [d6e5124]
+- Updated dependencies [debad27]
+- Updated dependencies [dc2aa3e]
+- Updated dependencies [ee66e2e]
+- Updated dependencies [e2e6360]
+- Updated dependencies [ee26e65]
+- Updated dependencies [5900ac5]
+- Updated dependencies [932cbcd]
+- Updated dependencies [734d186]
+- Updated dependencies [f650253]
+- Updated dependencies [3d9769a]
+- Updated dependencies [8f85f8b]
+- Updated dependencies [7ffd616]
+- Updated dependencies [d0c3b26]
+- Updated dependencies [3fc2971]
+- Updated dependencies [aca27fa]
+- Updated dependencies [dde7283]
+- Updated dependencies [f7c6430]
+- Updated dependencies [4dadf0d]
+- Updated dependencies [ae10a01]
+- Updated dependencies [77d6f28]
+- Updated dependencies [0f21348]
+- Updated dependencies [d2e2caf]
+- Updated dependencies [92876f0]
+- Updated dependencies [f279deb]
+- Updated dependencies [4b70d28]
+- Updated dependencies [eb7f586]
+- Updated dependencies [e901131]
+- Updated dependencies [ebb4e0e]
+- Updated dependencies [3a9021e]
+- Updated dependencies [d9d3463]
+- Updated dependencies [2a40f69]
+- Updated dependencies [bec3e14]
+- Updated dependencies [613b167]
+- Updated dependencies [b4d3c22]
+- Updated dependencies [1f9b905]
+- Updated dependencies [8f60d73]
+- Updated dependencies [cb13400]
+- Updated dependencies [828549a]
+- Updated dependencies [e1ade8f]
+- Updated dependencies [bc64bfe]
+- Updated dependencies [abb0f81]
+- Updated dependencies [38ab505]
+- Updated dependencies [51ab34e]
+- Updated dependencies [24bb2de]
+- Updated dependencies [0ca6096]
+- Updated dependencies [3e19fe7]
+- Updated dependencies [bb58d1d]
+- Updated dependencies [433ff9f]
+- Updated dependencies [5cc847c]
+- Updated dependencies [e7663f2]
+- Updated dependencies [fa21254]
+- Updated dependencies [f565418]
+- Updated dependencies [33c32bf]
+- Updated dependencies [66fb4fa]
+- Updated dependencies [b953a97]
+- Updated dependencies [d7f3e30]
+- Updated dependencies [6d641c9]
+- Updated dependencies [7e4f0e5]
+- Updated dependencies [a84385b]
+- Updated dependencies [45e1949]
+- Updated dependencies [51ac39f]
+- Updated dependencies [5e514c4]
+- Updated dependencies [92250d6]
+- Updated dependencies [c1d939f]
+- Updated dependencies [58bebf6]
+- Updated dependencies [36310dc]
+- Updated dependencies [52d878a]
+- Updated dependencies [405e808]
+- Updated dependencies [49ae9f4]
+- Updated dependencies [a3ae404]
+- Updated dependencies [4270c11]
+- Updated dependencies [bfdf3d4]
+- Updated dependencies [bb68488]
+- Updated dependencies [c0f9a4b]
+- Updated dependencies [b1e42d0]
+- Updated dependencies [2459a3e]
+- Updated dependencies [ac853ce]
+- Updated dependencies [fa51109]
+- Updated dependencies [d6aa172]
+- Updated dependencies [fe52a04]
+- Updated dependencies [d46f9b8]
+- Updated dependencies [3f5f87c]
+- Updated dependencies [2fea4d2]
+- Updated dependencies [f5e1143]
+- Updated dependencies [7f1cb33]
+- Updated dependencies [f148a64]
+- Updated dependencies [bb68488]
+- Updated dependencies [2e3b0c0]
+- Updated dependencies [9461dd3]
+- Updated dependencies [78fa331]
+- Updated dependencies [47f551b]
+- Updated dependencies [31ab1ac]
+- Updated dependencies [0082db8]
+- Updated dependencies [ab04728]
+- Updated dependencies [5bf09fd]
+- Updated dependencies [06915b0]
+- Updated dependencies [ff84b05]
+  - @object-ui/i18n@17.5.0
+  - @object-ui/react@17.5.0
+  - @object-ui/components@17.5.0
+  - @object-ui/core@17.5.0
+  - @object-ui/fields@17.5.0
+  - @object-ui/types@17.5.0
+  - @object-ui/plugin-grid@17.5.0
+
+## 17.4.0
+
+### Patch Changes
+
+- 3b1f888: Accept React 19 in `@object-ui/plugin-report`'s peer range, the last UI package still declaring React 18 alone (objectui#3690).
+
+  `peerDependencies.react` and `peerDependencies.react-dom` widen from `^18.0.0` to `^18.0.0 || ^19.0.0`, matching the other 29 packages in the fixed version group. With npm 7+ resolving peers strictly, a React 19 consumer installing this published package hit an `ERESOLVE` on first install while every sibling installed clean — and the package's own README already documented the wider range, so the manifest was the half that was wrong.
+
+  The narrow range was never a constraint anyone stated. `packages/plugin-report/package.json` was hand-authored on 2026-02-06 (`1e557cbda`), by which point nineteen sibling packages already carried `^18.0.0 || ^19.0.0` and every package created afterwards was born with it; the one other package born narrow, `plugin-dashboard`, was corrected on 2026-05-08 (`d2b6ecec6`) in a build fix that touched only itself. No commit in the file's 172-commit history ever revisited the peer line, and no commit message mentions a React 18 requirement.
+
+  Nothing in the package needs React 18. Its entire React surface is `React.FC`, `useState`, `useEffect`, `useMemo`, `useReducer`, `useContext`, `Fragment`, `ComponentType`, `CSSProperties` and `ReactNode` — all unchanged in React 19 — with zero uses of anything React 19 removed (`ReactDOM.render`, `unmountComponentAtNode`, `findDOMNode`, legacy context, string refs, `defaultProps` / `propTypes` on function components, `createFactory`, `useFormState`, `react-dom/test-utils`). `react-dom` is not imported by the source at all; it appears only as a UMD global name in the Vite externals config. The workspace pins `react` to 19.2.8 via a root `pnpm.overrides`, so this package's 78 tests have been running against React 19 the whole time it declared it did not support it.
+
+- Updated dependencies [794c497]
+- Updated dependencies [993336f]
+- Updated dependencies [f0a625a]
+- Updated dependencies [b5980f4]
+- Updated dependencies [8aad9fd]
+- Updated dependencies [6719877]
+- Updated dependencies [56ff091]
+- Updated dependencies [0186cdc]
+- Updated dependencies [7864f03]
+- Updated dependencies [ea41a59]
+- Updated dependencies [0cbdca8]
+- Updated dependencies [d229dfa]
+- Updated dependencies [18c42c6]
+- Updated dependencies [ecae400]
+- Updated dependencies [4bc6c23]
+- Updated dependencies [d3e738a]
+- Updated dependencies [c3b01a7]
+- Updated dependencies [f5f8744]
+- Updated dependencies [7ed3360]
+- Updated dependencies [69becd2]
+- Updated dependencies [5e52495]
+- Updated dependencies [0fa5e4d]
+- Updated dependencies [b750823]
+- Updated dependencies [5bfaabd]
+- Updated dependencies [e06810e]
+- Updated dependencies [ab3ad4f]
+- Updated dependencies [65bb513]
+- Updated dependencies [c97a45e]
+- Updated dependencies [b19162d]
+- Updated dependencies [c2fd122]
+- Updated dependencies [1bd6faa]
+- Updated dependencies [9154d9e]
+- Updated dependencies [ac2139c]
+- Updated dependencies [b14ab3a]
+- Updated dependencies [e24d767]
+- Updated dependencies [8c60819]
+- Updated dependencies [aca561a]
+- Updated dependencies [e64a52e]
+- Updated dependencies [844d17f]
+- Updated dependencies [d8a0be4]
+- Updated dependencies [48132f7]
+- Updated dependencies [4dcd52a]
+- Updated dependencies [42ae5c6]
+- Updated dependencies [0ef9dfd]
+- Updated dependencies [f4b97c8]
+- Updated dependencies [1d723e3]
+- Updated dependencies [0109f54]
+- Updated dependencies [7e5bb5d]
+- Updated dependencies [fbc23e0]
+- Updated dependencies [6d762da]
+- Updated dependencies [e6fdbdc]
+- Updated dependencies [54233b1]
+- Updated dependencies [c2ecbae]
+- Updated dependencies [f9faa7d]
+- Updated dependencies [97b63d7]
+- Updated dependencies [14c59c0]
+- Updated dependencies [aeb8424]
+- Updated dependencies [6bb454a]
+- Updated dependencies [1a33b1a]
+- Updated dependencies [11c1e71]
+- Updated dependencies [523be48]
+- Updated dependencies [7e2b7e9]
+- Updated dependencies [33526fd]
+- Updated dependencies [32413ec]
+- Updated dependencies [c1e1e6b]
+  - @object-ui/components@17.4.0
+  - @object-ui/react@17.4.0
+  - @object-ui/core@17.4.0
+  - @object-ui/fields@17.4.0
+  - @object-ui/i18n@17.4.0
+  - @object-ui/types@17.4.0
+  - @object-ui/plugin-grid@17.4.0
+
 ## 17.3.0
 
 ### Patch Changes
@@ -1425,6 +2115,7 @@
   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
@@ -1434,6 +2125,7 @@
   - 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)
@@ -1483,6 +2175,7 @@
   in the spec.
 
   New exports from `@object-ui/plugin-report`:
+
   - `JoinedBlocksEditor` — standalone component for embedding the
     block editor anywhere.
   - `validateJoinedBlocks` — pure helper returning translated
@@ -1513,6 +2206,7 @@
   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
@@ -1534,12 +2228,14 @@
   - 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:
@@ -1600,6 +2296,7 @@
 
 - 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`.
@@ -1627,6 +2324,7 @@
 ### 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`.
@@ -1770,6 +2468,7 @@
   Library builds (vite lib mode) now externalize every non-relative import instead of bundling third-party CJS dependencies into the published dist. This avoids inlined `require("react")` / `require("react-dom")` calls that cause `Calling \`require\` for "react" in an environment that doesn't expose the \`require\` function` runtime errors when consumer apps re-bundle the published dist.
 
   Specifically fixes:
+
   - `@object-ui/plugin-dashboard` no longer inlines `react-grid-layout` (and its transitive `react-draggable` / `react-resizable` CJS bundles). `react-grid-layout` is now declared as a peer dependency so consumers install a single ESM-friendly copy.
   - `@object-ui/components`, `@object-ui/plugin-calendar`, `@object-ui/plugin-charts`, `@object-ui/plugin-designer` no longer inline `react-i18next` / `i18next` / `use-sync-external-store` CJS shims.
   - All plugin packages now use a unified `external: (id) => !/^[./]/.test(id) && !id.startsWith(__dirname)` rule, ensuring future additions of CJS deps are automatically externalized.