@object-ui/plugin-charts 17.3.0 → 17.6.0

package/CHANGELOG.md

@@ -1,5 +1,645 @@
 # @object-ui/plugin-charts
 
+## 17.6.0
+
+### Minor Changes
+
+- 9ce096f: Give a chart bucket an identity distinct from its display label
+  
+  objectui#4508. `buildChartSeries` used the bucket's DISPLAY string as the
+  bucket's own key, so two pairs of genuinely different groups were conflated —
+  and the segment click that drills a bar back to its records inherited both
+  conflations. The maintainer ruling (2026-08-14) approved the sentinel-identity
+  direction, aligning the chart branch with the distinct-bucket-id form the pivot
+  TABLE (`buildPivot`) already uses over the same dataset rows.
+  
+  Two collisions, one cause:
+  
+  - **A null group and an empty-string group drew ONE bar.** The pivot branch
+    keyed buckets by `String(xRaw ?? '')`, which spells `null` and `''`
+    identically. The bar took its label from whichever row created the bucket, and
+    the other group's segment then resolved to no row at all — a visible bar whose
+    click did nothing.
+  - **A record whose stored value spells the bucket label stole the null bucket's
+    drill.** A row storing the literal text `(None)` (or any localized
+    `chart.nullCategory` — `(未指定)` and the other nine packs) kept its own
+    bucket, so two bars carried the same axis text and BOTH resolved to the first.
+    That one is a wrong drill, not a dead one: clicking the null bucket's bar
+    opened the drawer on another group's records.
+  
+  What changed:
+  
+  - **`chartBucketId`** (`@object-ui/core`) is the bucket identity — the SAME
+    encoder `buildPivot` keys its buckets with (`pivotBucketId` over
+    `pivotDimensionValue`), so the two surfaces stop answering one question two
+    ways. The pivot branch now buckets by it, which is what makes null and `''`
+    two groups again.
+  - **`CHART_BUCKET_ID_KEY`** carries that identity on an emitted row, written
+    exactly where two DISTINCT buckets paint the same axis text — the complete set
+    of cases where the display string cannot name what was clicked. An ordinary
+    chart's rows are returned untouched (by identity), so no renderer-internal key
+    reaches an authoring surface.
+  - **`findChartSeriesRow`** takes that identity back as `options.bucketId` and
+    treats it as authoritative. The renderers forward it: the drill event gains
+    `categoryId` (`ChartSegmentClickEvent`, now declared once in
+    `@object-ui/core` instead of inline in three packages), `AdvancedChartImpl`
+    reads it off the clicked row on the cartesian, pie and funnel paths, and
+    `DatasetWidget.handleChartDrill` hands it to the lookup.
+  
+  Behaviour change worth noting: an empty-string category no longer resolves to a
+  null-valued row. That tolerance was justified as the drill layer's own spelling
+  of "no group value", but no producer of this lookup's `category` writes it,
+  while `''` IS the axis text a genuine empty-string group paints — so the
+  tolerance was giving that group's bar a different group's records. A host that
+  forwards no `categoryId` keeps its existing drill unchanged.
+
+### Patch Changes
+
+- e132433: A grouped chart whose SECOND dimension was never projected says so instead of
+  drawing an empty frame.
+  
+  "Cannot know refuses loudly" was answered on the first dimension only.
+  `AdvancedChartImpl`'s `hasNoCategoryKey` (framework#4033) names an unprojected
+  x-axis dimension rather than drawing a bare axis; the series axis had no
+  counterpart, so a pivot whose second dimension was absent from the result rows
+  produced `series: []` and rendered axes, grid, tooltip and legend around zero
+  marks — indistinguishable, to the author, from "no data matched".
+  
+  Such a chart now renders the same explanatory placeholder
+  (`data-chart-error="no-plottable-series"`) and logs the same diagnostic pair the
+  category-axis guard logs: the axis it did plot, and the keys its rows actually
+  carry.
+  
+  The three-way distinction is unchanged and pinned: null / empty-string group
+  values still DRAW (they are real groups with real buckets), a partially
+  projected group key still draws what projects — mirroring the category axis,
+  which refuses only when NOT ONE row carries the key — and an ordinary pivot
+  renders unchanged. The refusal is limited to the families whose marks come from
+  `series` and nothing else (bar, horizontal-bar, line, area, combo); pie, donut,
+  funnel, radar and scatter draw from a `value` column with no series declared, so
+  they are untouched. A caller that computed no series binding at all
+  (`series === undefined`) is also untouched.
+- f95434b: Combo charts drill from their marks
+  
+  objectui#4692, ruled Option B. `AdvancedChartImpl` built `cartesianClickProps` once and
+  applied it to exactly one element — the final cartesian `ChartComponent`. The `combo`
+  branch returns earlier, from its own `ComposedChart`, which was rendered with `data` and
+  no click props at all, so a combo chart fired `onChartClick` never: not on a mark, not on
+  the axis. Its marks are the same `Bar` / `Line` / `Area` components the drillable branch
+  renders.
+  
+  The trap that made this worth fixing rather than documenting is that the family is
+  **derived**, not only authored: `effectiveChartFamily` resolves a chart to `combo`
+  whenever its series declare different families (objectui#2945), so adding `type: 'line'`
+  to one series of a drillable bar chart silently turned that chart's drill-through off —
+  nothing in the authored spec said drill had been touched, and nothing errored.
+  
+  A combo's `Bar` / `Line` / `Area` marks now emit `{ category, categoryId, series, value }`
+  with the same semantics the plain cartesian branch gives, reusing the item-level
+  series-identity machinery from objectui#4672 / objectui#4682: the mark handler records the
+  series it was rendered with, the chart-level handler composes the one event, so a gesture
+  still produces exactly one `onChartClick`. Retyping one series now changes that series'
+  mark and nothing else.
+  
+  **Only the marks drill.** A click on a combo's plot surface or axis stays silent, where
+  the plain cartesian branch falls back to its axis-level answer. A combo plots several
+  measures on one plot, so a surface click there has no single series to report and the
+  fallback would have to invent one — the same reasoning objectui#4672's ruling gave the
+  pivoted case. Combo also carries no chart-wide pointer cursor for that reason; the
+  affordance sits on the marks that answer.
+  
+  Radar is now the one cartesian-adjacent family with no click wiring. The `onChartClick`
+  doc comment, corrected in objectui#4705 to say combo was a no-op, states the new rule and
+  its one deliberate exception.
+- e05db88: A clicked cartesian mark names its own series, and the drill title reads its label
+  
+  objectui#4672, objectui#4682.
+  
+  **The dead pivoted drill.** objectui#4680 fixed what a cartesian click could
+  read out of recharts 3's `MouseHandlerDataParam`, and measured the wall it could
+  not get past: a chart-level click is an AXIS interaction, and recharts
+  dispatches those with `activeDataKey` hard-coded `undefined`, because the shared
+  cursor spans every series at that tick. A pivoted dataset chart — 2 dimensions,
+  1 measure, the shape ADR-0021 introduced — needs the series to resolve its drill
+  row, so every segment of every such dashboard chart stayed a dead click. The
+  series was left unresolved rather than guessed, and the card carried the rest.
+  
+  The answer is the mark itself. This renderer draws the `Bar` / `Line` / `Area`,
+  so an item-level `onClick` closes over the very `dataKey` it was rendered with —
+  the series is statically known, not inferred from tooltip state.
+  
+  Both handlers fire for one gesture (measured: item first, chart second, sharing
+  one `nativeEvent` object), so the item handler does not emit. It RECORDS its
+  series, stamped with that gesture, and the chart-level handler composes the one
+  event. That is the double-fire answer and the additive property together:
+  
+  - **one click, one drill event**, because there is one emit site — not a second
+    event suppressed after the fact;
+  - **a click that lands on no mark is untouched**: it records nothing and falls
+    through to the objectui#4680 axis answer exactly as shipped — category, bucket
+    identity, and the series only where one series is plotted. Empty plot area
+    stays category-only, and "drill the whole category" was rejected as a
+    different product question. Nothing that resolved before stops resolving; a
+    line's `dot={false}` stroke simply GAINS the exact series where it is hit;
+  - pairing on the shared DOM event rather than on a flag means a record left by
+    one gesture can never be adopted by a later click.
+  
+  The clicked key is forwarded exactly as rendered, `''` included: the
+  empty-string second-dimension group draws its own bar since objectui#4673, and
+  `''` is falsy, so a truthiness test on the way out would send no series at all
+  and leave that bar's drill standing on the reader's coercion instead of on what
+  was clicked.
+  
+  **The opaque drill title.** `ChartSegmentClickEvent` gains `seriesLabel`, and
+  `DatasetWidget`'s drill drawer titles itself from `seriesLabel ?? series`.
+  `ev.series` stays the LOOKUP key — `findChartSeriesRow` resolves it through the
+  same assignment `buildChartSeries` made — and only the title reads the label.
+  
+  The two strings are equal for every ordinary group, which is why reading the key
+  as a title went unnoticed. They part company when a group's label cannot name
+  it: the null bucket beside a record whose stored value literally spells
+  `(None)`, which is objectui#4508's collision on the series axis, reachable since
+  objectui#4673. Both groups then key by `chartBucketId`, and the drawer opened on
+  the right records under the title `Backlog / [null]`. An internal id where a
+  label belongs reads as broken DATA rather than as a broken title.
+  
+  Neither string can do the other's job, which is why this is a second field
+  rather than a change to the first: the label is not resolvable (it is exactly
+  what the colliding groups share) and the key is not showable. `seriesLabel` is
+  optional and absent wherever a renderer resolved no label, so every other
+  chart's title is byte-identical.
+- d298be8: Cartesian chart clicks report the clicked series and value again
+  
+  objectui#4672. `AdvancedChartImpl`'s chart-level click handler built its drill
+  event from `payload.activePayload[0]` — a **recharts 2** field. This package is
+  on recharts 3, which hands a chart-level `onClick` a `MouseHandlerDataParam`:
+  `{ activeCoordinate, activeDataKey, activeIndex, activeLabel, activeTooltipIndex,
+  isTooltipActive }`, and nothing else. `activePayload` appears nowhere in the
+  shipped library, so the read was `undefined` on **every** cartesian click and
+  every bar / line / area drill event carried `series: undefined, value: undefined`.
+  Nothing went red: the payload is typed `any` at the call site, and every existing
+  drill test either calls the pure lookup directly or stubs the chart.
+  
+  The handler now works from the payload recharts 3 actually sends:
+  
+  - **The value** is read off the clicked row — `data[activeTooltipIndex]`, the
+    array this component was given — for the resolved measure, the same way the
+    bucket identity has been read since objectui#4508.
+  - **The series** comes from `activeDataKey` when the payload carries one, and
+    otherwise from the chart's own series list when it plots exactly one series,
+    where the clicked column can belong to nothing else.
+  - **A click with no active tick** (the plot margins, an axis label) resolves to
+    no row instead of to bucket zero. recharts reports a **null** index there, not
+    an absent one, and `Number(null)` is `0` — so such a click used to drill the
+    first bucket's records. That is a wrong drill, not a dead one.
+  
+  A drill on a single-measure chart therefore names its measure and carries its
+  value again — `resolveDrillTitle` composes the drawer title from them, and an
+  authored drill filter can reference `${event.value}`.
+  
+  **Still open, deliberately:** a chart plotting several series under the default
+  SHARED cursor. Measured against recharts 3.10.1, an axis interaction is
+  dispatched with `activeDataKey` hard-coded `undefined` (bar, line and area
+  alike, on the mark and on empty plot area), so the payload names no series at
+  all — and a pivoted dataset chart's drill lookup requires one. The series is
+  left unresolved rather than guessed: naming a series the user did not click
+  drills to another group's records, which is worse than the dead click. Resolving
+  it needs the clicked mark rather than this payload; objectui#4672 carries that
+  half.
+- Updated dependencies [88085e3]
+- Updated dependencies [69251bf]
+- Updated dependencies [57e668f]
+- Updated dependencies [516663d]
+- Updated dependencies [41ac1b7]
+- Updated dependencies [1eaf0a1]
+- Updated dependencies [460c4d0]
+- Updated dependencies [0ae27f7]
+- 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 [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 [af5e292]
+- Updated dependencies [3fbbea1]
+- Updated dependencies [7f96b10]
+- Updated dependencies [167ec42]
+- Updated dependencies [616a2a5]
+- Updated dependencies [0046d8f]
+- Updated dependencies [f1d4748]
+- Updated dependencies [bea374e]
+- Updated dependencies [b1119ec]
+- Updated dependencies [9f23d2b]
+- Updated dependencies [578e025]
+- Updated dependencies [af025ee]
+- Updated dependencies [d109a4d]
+- Updated dependencies [598c89a]
+- Updated dependencies [4a0bd17]
+- Updated dependencies [b8b9af4]
+- Updated dependencies [31676be]
+- Updated dependencies [8c0d52e]
+- 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 [d2ce342]
+- Updated dependencies [9695da7]
+- 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 [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/i18n@17.6.0
+  - @object-ui/react@17.6.0
+  - @object-ui/components@17.6.0
+  - @object-ui/core@17.6.0
+
+## 17.5.0
+
+### Minor Changes
+
+- 5fac011: Publish `normalizeChartSchema` from the package entry.
+
+  `normalizeChartSchema` is the single place the author-facing chart schema is translated into the renderer's internal pipeline contract, and `ChartRenderer` calls it on every render. It was not reachable from the package's only entry point, so a consumer that wanted to assert what `AdvancedChartImpl` is actually handed had to restate the translation rather than run it. It is now exported from the entry, along with the `NormalizedChartSchema` type it returns.
+
+  Additive only: nothing is removed or renamed, and the module was already in the entry's eager import graph via `ChartRenderer`, so this publishes a name rather than shipping new bytes.
+
+### Patch Changes
+
+- 5900ac5: Analytics surfaces now run resolved select-option labels through the locale bundle — the chart legend and the related list on one page stop disagreeing
+
+  A dashboard widget grouped by a `select` field rendered the option's authored English label while the related list beside it rendered the translation. The decisive evidence in objectui#4030 is the stored value `orion`: the chart read `Orion Engineered Carbons`, a string with no resemblance to the value and matching the object's `label` byte for byte. So the analytics path had already RESOLVED the option label — it simply never ran the result through the i18n bundle before display. (`domestic → Domestic` differs from its value by case alone, which is why the first diagnosis, "the report groups by stored value", was wrong.)
+
+  There is exactly one resolution channel and this change reuses it rather than adding a chart-side dialect: `fieldOptionLabel` from `useObjectLabel`, i.e. `{ns}.fieldOptions.<object>.<field>.<value>` — the convention `@objectstack/spec` names objectui as the reader of, and the one list, form, kanban and record-picker surfaces already translate select options through. The bundle is applied ONCE, at the output of the label net that landed in objectui#4053/#4263, on the shared option list every consumer reads: chart axis and legend, the table/pivot cells of a dotted dimension, that table's CSV export, per-category colours and the declared category order. `@object-ui/core` gains `localizeFieldOptions` (the pure mirror of `translateOptions`), an optional translator on `buildDimensionLabelMap`, and `resolveDimensionFieldMeta` — the same single relationship walk `resolveDimensionFieldOptions` performs, now keeping the object that OWNS the terminal field, because for `crm_account.industry` the bundle key is `crm_account`, not the dataset's base object.
+
+  Two properties the fix is shaped around. The rows reach this net keyed either way — by stored value when the server did not resolve the dimension, by the English label when it did (ADR-0021) — and the reported screen is the second case, so the map answers to both keys and lands on the same translated display. And identity is untouched: `relabelDimensions` still rewrites display only, so a drilled chart segment clicked as `欧励隆` filters by `orion`, bucket ids and pivot totals keep their raw keys, and an option with no bundle entry (or an `en` console) renders exactly the authored label it renders today.
+
+  The per-locale work moved from the metadata fetch into the render, so switching language now re-labels in place instead of waiting for a refetch.
+
+  Not covered, and unchanged here: a LOCAL select dimension on a table/pivot, whose label the server resolves and whose client-side net is deliberately off (objectui#4263), and a dashboard global filter's own field label, which has no object name in its metadata to key a bundle lookup with — tracked on objectui#4030.
+
+- 3fc2971: A null-keyed group renders as an explicit bucket instead of silently vanishing from a chart (objectui#4466)
+
+  `buildChartSeries`' single-dimension branch passed rows through verbatim, so a row whose category VALUE is `null` reached recharts with a null category and drew no mark. The visible outcome was not an empty chart but a quietly wrong one: rows `[{user_id: null, event_count: 51}, {user_id: 'Dev Admin', event_count: 2}]` drew exactly ONE bar — the dominant group, 51 of 53 events, dropped while the y-axis scale still accommodated it, so the chart understated its own data and the axis proved the data had been there. With every group null it drew axes, gridlines and an axis title with zero marks and no empty state, which is the shipped first-boot state of the built-in System Overview board's "Events by User" (every seeded `sys_audit_log` row is written with `user_id = NULL`).
+
+  The mapping lives in the shared series layer, so dashboard widgets and standalone `ObjectChart` get one answer rather than a per-chart patch in the recharts wrapper. It resolves the two-answers disagreement the card names as well: an empty result set keeps the designed empty state, a non-empty result always draws bars — the null bucket included.
+
+  `@object-ui/core` gains `NULL_CATEGORY_LABEL` and `ChartSeriesOptions`; `buildChartSeries` and `findChartSeriesRow` each take an optional trailing `options`. Both additive — every existing call site compiles and behaves identically, and a result with no null category is still returned by array identity. The two helpers are a pair on purpose: the caller matches a clicked segment against rows that still carry the raw `null`, so `findChartSeriesRow` reads the bucket label back to that row and the newly-visible bar keeps its drill-through instead of resolving to `-1`.
+
+  The label goes through the i18n channel (`chart.nullCategory`, en `(None)` / zh `(未指定)`, all ten packs), passed down by the renderer: `@object-ui/core` is React-free and cannot read the locale bundle, so it takes the resolved string the same way `dimensionOptionTranslator` takes a resolver. Its English constant is the floor for a provider-less host, not the mechanism.
+
+  `hasNoCategoryKey` (framework#4033) is untouched and now documented against this: a row that does not carry the category key AT ALL is a different defect — a dimension grouped by but never projected — and keeps its explanatory placeholder. The bucket deliberately never ADDS the key to such a row, which is what keeps that guard's signal alive. Key absent → the placeholder; key present with a null value → the bucket.
+
+- aca27fa: The multi-dimension pivot branch buckets a null first-dimension value instead of dropping its bar (objectui#4497)
+
+  `buildChartSeries`' pivot branch (2+ dimensions, single measure) bucketed rows by `String(xRaw ?? '')` but wrote the RAW value into the emitted row, so a null first-dimension value produced `{status: null, Low: 3}` and reached recharts with a null category — which draws no mark. Measured at the DOM: a two-group pivot drew ONE bar, and an all-null pivot drew axes and gridlines with zero bar rectangles and no empty state. That is the same mechanism objectui#4466 fixed one branch below, on the branch that card deliberately left pinned as-is until the pivot's own bucketing had been measured.
+
+  The pivot now maps a null/undefined first-dimension VALUE to the same bucket label the single-dimension branch uses — `ChartSeriesOptions.nullCategoryLabel`, defaulting to `NULL_CATEGORY_LABEL`. One doctrine, one predicate, two call sites; no new export, and every existing call site compiles and behaves identically.
+
+  The bucket KEY is untouched, which is what keeps this a display fix: `String(xRaw ?? '')` still decides which rows share a bar, so every existing grouping is byte-identical and only the label the bucket carries changes. Rows that lack the category key entirely are still not bucketed — that shape is a dimension grouped by but never projected (framework#4033), a different defect with a different answer.
+
+  Drill-through needed no change, which was measured rather than assumed: the pivot's emitted rows are AGGREGATED, so they are not index-aligned with `drillRawRows` and the one production caller (`DatasetWidget.handleChartDrill`) already drills by SEARCHING the raw rows through `findChartSeriesRow`. Those raw rows still carry their null, and objectui#4466's label-matching covers the multi-dimension arm as well as the single-dimension one, so the newly-visible bar resolves to the right record. Pinned at both levels so a regression in either half surfaces as the dead click it would be.
+
+- 613b167: A dataset dimension on a dotted relationship path now renders its option labels instead of the raw stored enum
+
+  A `DatasetDimension` whose `field` is a relationship path (`crm_account.industry`) got no select-option resolution at all: the chart plotted `education`, `finance`, `manufacturing` — the database column, unresolved — while the **same underlying field** reached as a **local** dimension rendered `Education`, `Finance`, `Manufacturing` beside it on the same dashboard. Nothing errored, so the widget just quietly showed database enum values to end users; on a non-English deployment those are words that appear nowhere else in the UI, since every form and list shows the translated label.
+
+  The label lookup read options as `baseObject.fields[<path>]`, which only ever matches the local spelling. For a dotted path the options live on the **related** object, so the lookup missed and the renderer fell through to the stored value.
+
+  The object-resolution step of that one lookup now walks the path: each segment before the last must be a declared relationship (`lookup` / `master_detail`, target read from `reference` / `reference_to` / `referenceTo` / `reference_to_object`), and the terminal field's options are read off the object that actually owns it. This is the same lookup for both spellings rather than a dotted-path variant beside it — a single-segment path never enters the walk and resolves exactly as before, so the local and joined paths cannot drift apart. Multi-hop paths (`crm_account.owner.department`) resolve too, which is the shape the dataset designer already emits.
+
+  Hops ride the caller's existing `GET /meta/object/:name` channel — the same authenticated read that fetched the base object — so no new fetch layer is introduced, and objects are fetched once per resolution even when several dimensions share a prefix. Every failure stays best-effort: a segment that is not a relationship, a target that cannot be loaded, or a terminal field with no options yields no mapping and the raw value survives, exactly as it does today.
+
+  Applies to both surfaces that carried this lookup: dashboard dataset widgets (`DatasetWidget`) and the chart view's dataset path (`ObjectChart`).
+
+  Scope: this ends at "the label is in hand". Whether that label then passes through the i18n bundle is a separate gap tracked upstream as objectstack#5076.
+
+- 0b49d60: Analytics: `ObjectChart` consumes the shared label-net helpers instead of a third copy
+
+  objectui#4389 (PR #4404) named two copies of the analytics label-net glue — the dashboard's `DatasetWidget` and plugin-report's dataset block — and retired both into `@object-ui/core` + `@object-ui/react`. There was a THIRD, which that card did not name and its PR deliberately left out of scope: `packages/plugin-charts/src/ObjectChart.tsx` carried its own `translatorFor` closure, its own `buildDimensionLabelMap` loop, and its own base-object-read-then-walk composition. The `translatorFor` copy was logically identical to the two that were deleted, down to the comment explaining the binding.
+
+  `ObjectChart` now calls core's `dimensionOptionTranslator`, `deriveDimensionLabelMaps` and `loadDimensionFieldMeta` directly. Nothing about what a label IS changes — those helpers are the same code the two retired copies were rewritten onto, so the part that was genuinely duplicated three times is now written once.
+
+  Behaviour is unchanged by construction: same two metadata reads in the same order on the dataset path, same one read on the aggregate path, same best-effort fallback (an unresolvable path yields no entry and the raw value survives), same locale-applying memo boundary. `plugin-charts`' 22 test files / 170 assertions pass unchanged and their files are byte-identical to before, which is the acceptance evidence for a pure swap.
+
+  The card's second, optional step — moving the DATASET path's metadata read onto `@object-ui/react`'s `useDatasetDimensionMeta` — was attempted and declined on measurement; the shape blocker is recorded on objectui#4405 and in the PR. The two bug-fix properties the family exists to state (the read rides the host's authenticated `apiFetch`, objectui#4121; the fetched metadata stays locale-free, objectui#4030 / PR #4324) therefore remain stated locally in this file, exactly as before, and are undisturbed by this change.
+
+- bcd3e02: `ObjectChart`'s category option-color / dimension-label probe now rides the host's
+  authenticated fetch (`SchemaRendererContext.apiFetch`) instead of the bare global
+  `fetch`.
+
+  Both metadata reads the effect makes — `GET /api/v1/meta/dataset/{dataset}` and
+  `GET /api/v1/meta/object/{object}` — went out on the global `fetch`, so in a hosted
+  console they skipped whatever the host supplies on that channel (Authorization /
+  tenant headers, base-URL rewrite, draft-preview params). A bearer-token session
+  carries its credential in a header rather than a cookie, so `credentials: 'include'`
+  alone left these two reads unauthenticated. The effect is best-effort and swallows
+  every failure, which made the symptom silent: semantic option colors and dataset
+  dimension labels simply never applied, and the chart fell back to the positional
+  theme palette and raw stored values.
+
+  Standalone embeds are unaffected — with no provider (or a provider that supplies no
+  `apiFetch`) the probe still uses the global `fetch`, the same documented fallback
+  `useRecordEditable` and `provider: 'api'` view sources use.
+
+- Updated dependencies [0e67b53]
+- Updated dependencies [ceccdcf]
+- Updated dependencies [d6e5124]
+- Updated dependencies [debad27]
+- Updated dependencies [dc2aa3e]
+- Updated dependencies [ee66e2e]
+- Updated dependencies [ee26e65]
+- Updated dependencies [5900ac5]
+- Updated dependencies [932cbcd]
+- Updated dependencies [734d186]
+- Updated dependencies [f650253]
+- Updated dependencies [3d9769a]
+- Updated dependencies [8f85f8b]
+- Updated dependencies [d0c3b26]
+- Updated dependencies [3fc2971]
+- Updated dependencies [aca27fa]
+- Updated dependencies [dde7283]
+- Updated dependencies [f7c6430]
+- Updated dependencies [4dadf0d]
+- Updated dependencies [ae10a01]
+- Updated dependencies [92876f0]
+- Updated dependencies [f279deb]
+- Updated dependencies [4b70d28]
+- Updated dependencies [eb7f586]
+- Updated dependencies [e901131]
+- Updated dependencies [d9d3463]
+- Updated dependencies [2a40f69]
+- Updated dependencies [bec3e14]
+- Updated dependencies [613b167]
+- Updated dependencies [b4d3c22]
+- Updated dependencies [1f9b905]
+- Updated dependencies [cb13400]
+- Updated dependencies [828549a]
+- Updated dependencies [e1ade8f]
+- Updated dependencies [bc64bfe]
+- Updated dependencies [abb0f81]
+- Updated dependencies [38ab505]
+- Updated dependencies [3e19fe7]
+- Updated dependencies [bb58d1d]
+- Updated dependencies [5cc847c]
+- Updated dependencies [fa21254]
+- 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 [92250d6]
+- Updated dependencies [c1d939f]
+- Updated dependencies [58bebf6]
+- Updated dependencies [405e808]
+- Updated dependencies [49ae9f4]
+- Updated dependencies [a3ae404]
+- 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/types@17.5.0
+
+## 17.4.0
+
+### Patch Changes
+
+- a7e39a8: `ChartContainer`'s min-size fallback survives a consumer-supplied `style` (objectstack#7026)
+
+  The container wrote `style={{ minHeight: 280, minWidth: 0, ...props.style }}` and
+  then spread `{...props}` on the line BELOW it. `props` is the rest of
+  `ComponentProps< "div" >` — only `id`, `className`, `children`, `config` and
+  `disableSettleRemount` are destructured out of it — so it still carried the
+  consumer's `style`, and a later JSX attribute of the same name replaces an earlier
+  one outright. Any caller that passed a `style` therefore replaced the whole object:
+  both `minHeight` and `minWidth` vanished, and the `...props.style` merge written
+  inside it never executed even once. It was dead code that read, to anyone auditing
+  the file, as if the fallback were guaranteed.
+
+  That fallback is not decorative. It exists so Recharts' `ResponsiveContainer`
+  always has a non-zero box to measure: a dashboard widget that overrides the
+  container's `h-[350px]` class and wraps the chart in flex/grid without an explicit
+  child height leaves the box at 0, Recharts measures `width/height = -1`, and the
+  chart renders invisibly — the exact failure the guard was added for.
+
+  `style` is now destructured out of the rest props and merged explicitly, so which
+  side wins is stated in code instead of being decided by JSX attribute order, and
+  `{...props}` can no longer reach `style` at all.
+
+  Precedence: **an author's explicit size wins.** Simply spreading `{...props}`
+  first and merging unconditionally would have traded this bug for its mirror image
+  — `minHeight: 280` injected next to an authored `height: 100` floors that 100 to
+  280, silently overriding the author. So each half of the fallback applies only
+  when the consumer style declares neither of its own keys: `height`/`minHeight`
+  gate the height half, `width`/`minWidth` gate the width half, and a key present
+  but set to `undefined`/`null` counts as not declared. Every other consumer style
+  key passes through untouched.
+
+  Behaviour change surface, deliberately narrow. A caller that supplies no `style`
+  is byte-for-byte unchanged. A caller whose `style` declares a height — which today
+  is the only shape in the tree, `AdvancedChartImpl`'s `containerProps` forwarding
+  `ChartConfig.height` — keeps exactly the height it authored, also unchanged, and
+  additionally regains the `minWidth: 0` half. What changes is the case the issue
+  was filed for: a `style` carrying no size key (a margin, a padding, an
+  aspect-ratio, any future container-level presentation prop routed through the same
+  `containerProps` path) now keeps the min-size fallback instead of silently
+  stripping it.
+
+  Pinned in both directions, since a one-sided pin would have been satisfied by the
+  mirror-image fix: a non-size `style` keeps `min-height: 280` / `min-width: 0`
+  (red before this change), and an explicit `height: 100` renders as 100 with no
+  `min-height` floor (red under the unconditional-merge alternative).
+
+- 4bc6c23: Converge dashboard widget `compareTo` on the executor's `{ kind, dimension? }` contract, and make the dataset path actually render a comparison
+
+  `CompareToConfig` was a three-branch union (`'previousPeriod' | 'previousYear' | { offset }`). `@objectstack/spec` collapsed it to the shape the analytics executor already implements — `DatasetCompareTo`, a plain strict object `{ kind: 'previousPeriod' | 'previousYear'; dimension?: string }` (objectstack#5011) — so this renderer now reads that one shape:
+
+  - `shiftFilterByCompareTo` / `compareToTrendLabelKey` dispatch on `compareTo.kind`. The `{ offset }` duration shift is gone: `{ offset: '1y' }` is `kind: 'previousYear'`, while `'7d'` / `'1M'` have no faithful target and are restated by the author on the widget's own `filter` plus `kind: 'previousPeriod'`. No trend label key is retired — the offset arm resolved to `vsPreviousPeriod`, which survives as the `previousPeriod` fallback.
+  - `DatasetWidget` no longer discards part of `compareTo`. It used to forward only the object form because the two string forms had no meaning downstream; with one shape there is nothing to discard, and a stale string is now invalid metadata rejected where it is authored rather than silently reinterpreted here.
+  - **The comparison now actually runs on the dataset path.** A widget states its window in its own `filter` (a date macro, or the dashboard date-range filter merged in), but the executor shifts a `timeDimensions` entry carrying a `dateRange` — so a dataset widget asking for a comparison got "compareTo needs a dated window to shift" and rendered none. When (and only when) a comparison is requested, the resolved filter's bounded date windows are lowered into `selection.timeDimensions[].dateRange` and moved out of `runtimeFilter` (a copy left behind would intersect the shifted window with the current one and empty every comparison column). Which dimension gets shifted stays the executor's decision: every window found is lowered under the name the author wrote, and zero or two candidates surfaces the executor's own error, listing them.
+  - The `<measure>__compare` columns that come back are now shown: a delta + window label on KPI widgets, a comparison column on tables, and a `variant: 'comparison'` overlay series on charts — the same treatment and the same `dashboard.trend.*` labels the inline object-provider widgets already use.
+
+- 5bfaabd: `PageComponentSchema.dataSource` now reaches every object-bound block, not just
+  `list-view` — and `element:record_picker` stops discarding `view`
+  (objectstack#6953).
+
+  objectstack#5576 wired the spec's per-element data binding
+  (`dataSource: { object, view?, filter?, sort?, limit? }`) to `list-view` and left
+  the same declaration inert on every other page component. Two gaps remained, and
+  both were silent:
+
+  - **`element:record_picker` read four of the five keys and dropped `view`.** So
+    `dataSource: { object: 'account', view: 'hot' }` — the spec's own example —
+    built a picker over EVERY account instead of the rows the saved view selects.
+    Nothing threw and nothing rendered an error; the option list was simply wider
+    than what was authored, which also means a user could select a record the page
+    said was out of scope.
+  - **`object-grid` / `object-form` / `object-kanban` / `object-calendar` /
+    `object-chart` / `object-metric` / `record:related_list` read none of it.**
+    Each gates its fetch on its own `objectName`, and nothing mapped
+    `dataSource.object` onto it, so a page written the way the spec documents
+    rendered an empty grid / a field-less form / a board with no cards / an empty
+    month / an empty chart / a static metric number — with no request and no
+    diagnostic anywhere. Spec-valid metadata rendering nothing is the
+    objectstack#4413 shape.
+
+  Composition follows objectstack#5576's landed semantics unchanged on every block:
+  a named saved view supplies the baseline, a key written on the component itself
+  overrides it, an explicit binding key overrides both, `filter` AND-combines
+  ("additional filter criteria" — a binding can narrow a view, never widen it), and
+  a `view` name that does not resolve renders a configuration error instead of
+  degrading to the object's full scope.
+
+  - `@object-ui/react` — new `useElementDataSourceSchema(schema, mapping, dataSource?)`
+    and `ElementDataSourceGate` apply a resolved binding to the schema keys a given
+    block reads, plus `ElementDataSourceErrorPanel` / `ElementDataSourceLoadingPanel`
+    for the two non-final states. One precedence table for all blocks rather than
+    one copy per block — that copy is how "additional filter criteria" would have
+    become two dialects.
+  - A mapping names **only** keys its block genuinely reads. A composed value
+    written onto a key the block ignores would be accepted and dropped, which is
+    the defect being removed, one layer deeper — so a kanban's swimlane `columns`
+    never receive a view's field list, and a block with no row cap leaves `limit`
+    unmapped. The per-block coverage table, including two residual gaps that are
+    named rather than papered over, is in `content/docs/guide/data-source.md`.
+
+  No behaviour changes for a block that carries no `dataSource`: the binding-free
+  path returns the schema by reference, so nothing remounts and nothing refetches.
+
+- Updated dependencies [794c497]
+- Updated dependencies [993336f]
+- Updated dependencies [f0a625a]
+- Updated dependencies [b5980f4]
+- Updated dependencies [8aad9fd]
+- Updated dependencies [6719877]
+- Updated dependencies [56ff091]
+- Updated dependencies [7864f03]
+- Updated dependencies [0cbdca8]
+- Updated dependencies [d229dfa]
+- 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 [c2fd122]
+- Updated dependencies [ac2139c]
+- Updated dependencies [b14ab3a]
+- Updated dependencies [e24d767]
+- Updated dependencies [8c60819]
+- Updated dependencies [aca561a]
+- Updated dependencies [e64a52e]
+- Updated dependencies [844d17f]
+- Updated dependencies [48132f7]
+- Updated dependencies [4dcd52a]
+- Updated dependencies [42ae5c6]
+- Updated dependencies [0ef9dfd]
+- Updated dependencies [1d723e3]
+- Updated dependencies [0109f54]
+- Updated dependencies [7e5bb5d]
+- Updated dependencies [fbc23e0]
+- Updated dependencies [6d762da]
+- Updated dependencies [e6fdbdc]
+- Updated dependencies [54233b1]
+- Updated dependencies [f9faa7d]
+- Updated dependencies [97b63d7]
+- Updated dependencies [6bb454a]
+- 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/i18n@17.4.0
+  - @object-ui/types@17.4.0
+
 ## 17.3.0
 
 ### Minor Changes
@@ -872,6 +1512,7 @@
   project `health`) painted its categories from the generic `--chart-1..5`
   palette — the same gap the chart view (`object-chart`) had before #1932. It now
   resolves the dimension field's option colors (using the dataset's base `object`
+
   - dimension→field map the query already returns) and threads them to the
     renderer as a per-category `categoryColors` map, so health green/red/yellow
     paints semantically.
@@ -1078,6 +1719,7 @@
 - 991b62d: Add `compareTo` field to dashboard widgets for period-over-period
   comparison. Supports `'previousPeriod'`, `'previousYear'`, and
   `{ offset: '7d' | '4w' | '1M' | '1y' }`.
+
   - **Metric / gauge widgets** now compute a delta percentage when `compareTo`
     is set and surface it as a derived `trend` (auto-labelled via
     `dashboard.trend.vsLast*` i18n keys sniffed from the filter macros).
@@ -1562,6 +2204,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.
@@ -1795,6 +2438,7 @@
 - New plugin-object and ObjectQL SDK updates
 
   **Added:**
+
   - New Plugin: @object-ui/plugin-object - ObjectQL plugin for automatic table and form generation
     - ObjectTable: Auto-generates tables from ObjectQL object schemas
     - ObjectForm: Auto-generates forms from ObjectQL object schemas with create/edit/view modes
@@ -1803,6 +2447,7 @@
   - ObjectQL Integration: Enhanced ObjectQLDataSource with getObjectSchema() method using MetadataApiClient
 
   **Changed:**
+
   - Updated @objectql/sdk from ^1.8.3 to ^1.9.1
   - Updated @objectql/types from ^1.8.3 to ^1.9.1
 
@@ -1819,6 +2464,7 @@
 - Patch release: Add automated changeset workflow and CI/CD improvements
 
   This release includes infrastructure improvements:
+
   - Added changeset-based version management
   - Enhanced CI/CD workflows with GitHub Actions
   - Improved documentation for contributing and releasing