@object-ui/plugin-charts 16.1.0 → 17.1.0

package/CHANGELOG.md

@@ -1,5 +1,380 @@
 # @object-ui/plugin-charts
 
+## 17.1.0
+
+### Minor Changes
+
+- f1c04b6: fix(charts): a spec `series[].type` override actually draws, and a spec-shape `series` plots at all (#2945)
+
+  #2945 listed `combo` (`plugin-charts`) as renderer-local dialect to "promote or
+  delete". Neither: the spec **already models a combo chart**, per-series, and its
+  own field comment says so —
+
+  ```ts
+  // spec/src/ui/chart.zod.ts — ChartSeriesSchema
+  /** Series type override (combo charts) */
+  type: ChartTypeSchema.optional().describe('Override chart type for this series'),
+  ```
+
+  — exactly as it models stacking with `ChartSeries.stack` rather than a
+  `stacked-bar` family. So `combo` is not a name an author should reach for; it is
+  what "the series disagree about their family" looks like from the renderer's
+  side. `effectiveChartFamily` now derives it, and `combo` stays a documented
+  renderer-local marker (internal callers pass it directly today).
+
+  Chasing that turned up two live bugs, both silent, on the path a spec author
+  takes.
+
+  **1. The per-series override was parsed, carried, and then dropped.** Only the
+  renderer's `chartType === 'combo'` branch read `series[].chartType`, so
+
+  ```ts
+  { type: 'bar', series: [{ name: 'revenue' }, { name: 'margin', type: 'line' }] }
+  ```
+
+  drew `margin` as a bar. Nothing was wrong at any layer but the last — a unit test
+  even asserted the value was carried.
+
+  **2. A spec-shape `series` rendered nothing at all.** `series` is the one binding
+  both shapes spell with the same key, so `ChartRenderer`'s blanket "internal props
+  win" rule let the author's `[{ name }]` shadow the normalized `[{ dataKey }]` and
+  reach a renderer that reads `dataKey`. Blank chart. Every other spec binding has a
+  distinct name (`xAxis` vs `xAxisKey`), which is why only this one broke — and why
+  the isolated normalization tests all passed over a dead path. The raw array is now
+  preferred only when it already speaks the internal shape, so internal callers are
+  byte-for-byte unchanged and a mixed array works too.
+
+  **Also fixed in passing:** the combo branch had an `area` arm under a `BarChart`
+  container, and Recharts renders an `<Area>` child of `BarChart` as nothing — so an
+  authored combo with an `area` series drew a blank series. The container is now
+  `ComposedChart`, which is what Recharts provides for mixed marks.
+
+  Widening only. A chart whose series all resolve to one family keeps its own
+  family, an explicit `combo` is untouched, and a family with no per-series meaning
+  (`pie`, `horizontal-bar`, …) is never widened. A derived combo binds series to the
+  left axis unless one asks for `yAxis: 'right'` — the spec's own default — so
+  widening changes the series' mark and not its scale; the legacy bar→left/line→right
+  guess is kept for an authored `combo`, where it was historically the only way to
+  reach a second axis.
+
+  Guards: `effectiveChartFamily` / `comboBaseFamily` are unit-tested over the whole
+  family matrix; DOM-level tests assert the **marks** rather than the derived family,
+  since the carry was already covered and the drawing was what broke; and
+  `spec-derived-unions.test.ts` asserts `combo` is absent from the spec's
+  `ChartTypeSchema`, so the day it is adopted upstream the derivation is named as the
+  thing to retire.
+
+### Patch Changes
+
+- Updated dependencies [62311b6]
+- Updated dependencies [fc0272a]
+- Updated dependencies [9e7349e]
+- Updated dependencies [8864971]
+- Updated dependencies [1cf0de7]
+- Updated dependencies [752e18f]
+- Updated dependencies [c785740]
+- Updated dependencies [b41f401]
+- Updated dependencies [19e9fa0]
+- Updated dependencies [d61efd1]
+- Updated dependencies [95b7214]
+- Updated dependencies [7d9734d]
+- Updated dependencies [6ae818e]
+- Updated dependencies [9eb932b]
+- Updated dependencies [746dd00]
+- Updated dependencies [aebfa4f]
+- Updated dependencies [38ca8be]
+- Updated dependencies [3cb9646]
+- Updated dependencies [68ef584]
+- Updated dependencies [4952edf]
+- Updated dependencies [7f0252e]
+- Updated dependencies [c4d7b20]
+- Updated dependencies [c769d3d]
+- Updated dependencies [7639a61]
+- Updated dependencies [94e63ef]
+- Updated dependencies [c735bf7]
+- Updated dependencies [02aef0c]
+- Updated dependencies [6f29aa5]
+- Updated dependencies [d21794c]
+- Updated dependencies [c4db402]
+- Updated dependencies [5319bf1]
+- Updated dependencies [49e5671]
+- Updated dependencies [9a04d25]
+- Updated dependencies [b5b97e2]
+- Updated dependencies [f59f2c1]
+- Updated dependencies [07de839]
+- Updated dependencies [2a40b5e]
+- Updated dependencies [df613fa]
+- Updated dependencies [4874117]
+- Updated dependencies [ad0183a]
+- Updated dependencies [ce08d55]
+- Updated dependencies [eb4b740]
+- Updated dependencies [5b084eb]
+- Updated dependencies [aa1240a]
+- Updated dependencies [2374a49]
+- Updated dependencies [390c071]
+- Updated dependencies [d10f526]
+- Updated dependencies [2d5d594]
+- Updated dependencies [ea7f477]
+- Updated dependencies [379728f]
+- Updated dependencies [7f23cd0]
+- Updated dependencies [0ded602]
+- Updated dependencies [24e0e0a]
+- Updated dependencies [f8a95e5]
+- Updated dependencies [3a6cf24]
+- Updated dependencies [aa35561]
+- Updated dependencies [03bd53b]
+- Updated dependencies [3c1f321]
+- Updated dependencies [a045a32]
+- Updated dependencies [912496d]
+- Updated dependencies [80edbd4]
+- Updated dependencies [9867281]
+  - @object-ui/core@17.1.0
+  - @object-ui/components@17.1.0
+  - @object-ui/react@17.1.0
+  - @object-ui/types@17.1.0
+  - @object-ui/i18n@17.1.0
+
+## 17.0.0
+
+### Minor Changes
+
+- aa88056: feat(charts): honor `ChartAxis.stepSize`, `ChartConfig.description` and `ChartConfig.height` (framework#3752)
+
+  The tail of the declared-≠-delivered sweep from framework#3729 / #2880. Three
+  `ChartConfig` props reached the renderer and did nothing:
+
+  - **`ChartAxis.stepSize`** — Recharts has no "a tick every N units" prop
+    (`tickCount` is a hint it may ignore, `interval` is for categorical axes), so
+    honoring a step means handing it the tick array outright. `ticksFor` builds it
+    from the axis's own `min`/`max` where declared and from the plotted values
+    otherwise, so a step works with or without a pinned domain. A data-derived max
+    rounds UP to the next step (otherwise the topmost bar sits above the last
+    gridline and the axis reads as truncated); an explicit `max` clamps instead,
+    since a tick outside a pinned domain would be drawn outside the plot. A step
+    that would produce more than 200 ticks is refused rather than rendered — that
+    is a wrong config, and drawing it would hang the page instead of surfacing the
+    mistake.
+  - **`ChartConfig.description`** — the accessibility description. A chart is a
+    picture to a screen reader; the container now carries `role="img"` +
+    `aria-label`. Without a description it stays an ordinary div, because
+    stamping `role="img"` on an _unlabelled_ graphic is worse than leaving one a
+    screen reader can skip.
+  - **`ChartConfig.height`** — was read only by the legacy `ChartBarRenderer`, not
+    by the advanced path that draws every real chart. Now applied to the chart
+    container as an inline style, which beats its default `h-[350px]` class.
+
+  `height` and `description` ride on the shared container props, so they apply to
+  all eight chart families rather than one branch.
+
+- 9b53d72: feat(charts): ObjectChart honors the spec `ChartConfig` author shape (objectui#2880 / framework#3729)
+
+  `ChartConfigSchema` is the chart protocol, but the renderer only ever read a
+  Recharts-flavoured internal shape — `chartType`, `xAxisKey`, `series[].dataKey`.
+  Everything an author wrote in the SPEC shape reached the renderer and was
+  silently dropped, which is exactly what ADR-0078 forbids. framework#3725
+  documented the gap by trimming the published contract down to the props that
+  actually worked; this closes it the other way round.
+
+  **S1 — one normalization boundary.** `normalizeChartSchema` translates the
+  author shape into the internal pipeline contract in a single place, rather than
+  scattering `??` fallbacks through the render tree (framework PD #12: one
+  translation is a contract mapping, N fallbacks are a second dialect):
+
+  - `type` → `chartType`, `xAxis: { field }` → `xAxisKey`, `series: [{ name }]` →
+    `series: [{ dataKey }]`
+  - the report surface's bare-string `xAxis`/`yAxis` resolve too
+  - `yAxis: [{ field }]` alone plots, with no `series` declared
+  - **internal props win**, so `DashboardRenderer`, `ObjectView` and the dataset
+    path are byte-for-byte unaffected — there is no migration
+
+  **The `type` collision.** `ChartConfig.type` is the chart family, but on any
+  surface that flattens chart config into a props bag `type` is already the SDUI
+  envelope's component discriminator. Spreading props last let an author's
+  `type="bar"` replace `object-chart` so the block stopped resolving; stamping the
+  discriminator last ate the author's value instead. The react-page wrapper now
+  keeps both: the discriminator wins the `type` slot and the author's value is
+  preserved beside it as `specType`, which the normalizer reads back.
+
+  **S2 — axis presentation.** `ChartAxis.format` drives the tick formatter (via
+  `Intl.NumberFormat`, no new dependency), `min`/`max` pin the domain,
+  `logarithmic` swaps the scale, `title` labels the axis, and `showGridLines` is
+  honored. A second `yAxis` entry (or `position: 'right'`) turns on the secondary
+  axis that `series[].yAxis` binds to — in combo charts an explicit binding now
+  beats the family-derived bar→left/line→right guess. `showLegend` is honored,
+  and `title`/`subtitle` render above the plot instead of only titling the
+  drill-down drawer.
+
+  **S3 — `series[].stack`, `annotations`, `interaction`.** Stacking passes the
+  author's group name through as Recharts' `stackId`. Annotations render as
+  `ReferenceLine` (`type: 'line'`) / `ReferenceArea` (`type: 'region'`) with the
+  declared axis, colour, style and label. `interaction.tooltips: false` suppresses
+  the hover card and `interaction.brush: true` adds the range selector;
+  `showDataLabels` prints values on the marks. `interaction.zoom` has no Recharts
+  primitive behind it and is deliberately still unimplemented rather than faked.
+
+### Patch Changes
+
+- 7b35e4b: fix(dashboard,charts): resolve `{current_user_id}` in widget filters (framework #3574)
+
+  A dashboard widget filtered on `{current_user_id}` rendered `0`. The token
+  reached SQL as a literal, matched no row, and nothing was logged on the client
+  or the server — a silent zero that reads as "you have no work" rather than
+  "this filter did not resolve". The same token in a list-view filter resolved
+  correctly, so a user-scoped list and a user-scoped widget over the same data
+  disagreed.
+
+  There was no shared resolver. Three ad-hoc implementations had grown up
+  independently — `ObjectView` for list views, `ObjectDataPage` for URL filter
+  triples, `NavigationRenderer` for hrefs — and each understood only the filter
+  shape its own surface used. `ObjectView`'s opened with
+  `if (!Array.isArray(filter)) return filter`, so it could not have been reused
+  by dashboard widgets even in principle: widget filters are MongoDB-style
+  objects. Widgets therefore got no resolution at all — `DatasetWidget` called
+  `resolveDateMacros` and nothing else, which is why `{today}` worked in a widget
+  and `{current_user_id}` silently did not.
+
+  - **`@object-ui/core`** — new `utils/filter-tokens.ts` with
+    `resolveContextTokens` and `resolveFilterPlaceholders`. The latter expands
+    _every_ placeholder vocabulary in one call and is what surfaces should use;
+    resolving only some of them is the whole defect. The walk handles arrays and
+    plain objects uniformly, so one resolver covers both platform filter shapes.
+  - **`@object-ui/react`** — new `FilterScopeProvider` / `useFilterScope`. The
+    renderer packages deliberately do not depend on `@object-ui/auth`, so the
+    shell supplies the session values. This is a separate context from
+    `PredicateScopeContext`, which is the expression evaluation scope and carries
+    no organization.
+  - **`@object-ui/plugin-dashboard` / `@object-ui/plugin-charts`** — all six
+    widgets that previously resolved date macros only now resolve both
+    vocabularies: `DatasetWidget`, `ObjectMetricWidget`, `ObjectDataTable`,
+    `ObjectPivotTable`, and `ObjectChart` (dataset-bound and inline paths). The
+    chart's `compareTo` comparison filter gets the session pass too — otherwise
+    the overlay series silently ignored the owner clause the primary series
+    honoured.
+  - **`@object-ui/app-shell`** — `ObjectView`'s local `substituteFilterTokens`
+    and `ObjectDataPage`'s inline `=== '{current_user_id}'` ternary now delegate
+    to the shared resolver, so both also gain `{current_org_id}` and date macros.
+    Two of the three ad-hoc implementations are gone rather than joined by a
+    fourth.
+
+  An unresolvable token is left intact rather than dropped: leaving it yields an
+  empty result, whereas dropping the clause would _widen_ the result set and show
+  a signed-out viewer everyone's data. It is no longer silent — the resolver
+  warns, naming the token, and suggests the intended spelling for known
+  near-misses (`{current_user}`, `{user_id}`, `{organization_id}`). Authoring-time
+  enforcement lands separately as `filter-token-unknown` in `@objectstack/lint`.
+
+- e16ed2d: fix(dashboard,charts): send widget `dateGranularity`/`sortBy`/`limit` to the query, and give funnels a real stage order (framework#3588)
+
+  `DatasetWidget` never read `widget.options`. Four keys an author writes there
+  change the query the server compiles, so a widget declaring
+  `options: { dateGranularity: 'month' }` grouped by the raw timestamp and drew
+  one bar per record, and `sortBy`/`sortOrder` produced no ordering at all.
+
+  - `DatasetWidget` lowers `options.dateGranularity`, `options.sortBy` +
+    `options.sortOrder`, and `options.limit` into the `DatasetSelection` it posts.
+    A `sortBy` naming something the widget does not project is dropped rather than
+    sent, so a stale sort key left by an edit degrades to "unordered" instead of
+    failing the widget against the server's stricter validation. These keys also
+    join the refetch signature, so editing one in the designer refetches instead
+    of re-rendering the previous grid.
+  - Funnel stages follow a **declared order**. `AdvancedChartImpl` sorted funnel
+    segments by value descending, unconditionally — which overrode any server
+    ordering and rendered a sales pipeline as a tidy narrowing shape whatever the
+    stages' real sequence, hiding the very anomaly (a bulge at Proposal) the chart
+    exists to show. It now honours a `categoryOrder`, which `DatasetWidget`
+    derives from the dimension field's picklist option order — the pipeline order
+    an author already declared on the object — or from an explicit
+    `options.stageOrder`. With no declared order the value-descending default is
+    unchanged, and a category missing from the order is kept (after the declared
+    ones), never dropped.
+  - New `@object-ui/core` helpers `buildCategoryOrder` / `buildCategoryRank`,
+    keyed by both the stored value and the display label like the existing
+    `buildOptionColorMap`, so ordering works whether or not the server resolved
+    the dimension's labels.
+
+  Requires the framework-side fix in objectstack#3588 for the selection keys to
+  take effect server-side.
+
+- 6e8fd3c: fix(charts): a fieldless `count` aggregate keyed its value column `undefined`, so the chart plotted nothing (framework#3701)
+
+  framework#3701 pinned down what an OBJECT-bound chart aggregate names its result
+  columns — the raw field names it was given (`groupBy` for the category, `field`
+  for the value; no `sum_`-style decoration, unlike a dataset measure), plus the
+  literal `count` when a `count` omits `field`, which is the alias the engine
+  projects `COUNT(*)` under. `os validate` now lints page sources against that
+  convention, so the paths that build these rows have to honour it exactly.
+
+  Three of the four did. The odd one out was `count` — the one function that may
+  legitimately omit `field` — because every row builder read `params.field`
+  directly:
+
+  - `aggregateRecords` / `ObjectDataSource.aggregateClientSide` emitted
+    `{ [groupBy]: key, [undefined]: value }`, i.e. a column literally named
+    `undefined` that no axis binding could ever name;
+  - the legacy analytics path was worse: it remapped the server's `count` measure
+    onto `params.field` and **deleted** the original key, so the value the server
+    did return was thrown away before the chart saw it.
+
+  All of them now resolve the column through one helper (`aggregateValueKey`) so a
+  fieldless count lands under `count`, matching the framework contract. The
+  comparison-overlay column is derived from the same key (`count__comparison`
+  instead of `undefined__comparison`), and `aggregate.field` is typed optional to
+  match the spec's `ChartAggregateSchema`. Charts that name a field are unchanged.
+
+- Updated dependencies [7b21891]
+- Updated dependencies [0b3be01]
+- Updated dependencies [3c4d935]
+- Updated dependencies [4b60d2d]
+- Updated dependencies [952b978]
+- Updated dependencies [de5e40c]
+- Updated dependencies [1a03af6]
+- Updated dependencies [3e886eb]
+- Updated dependencies [cfc675e]
+- Updated dependencies [20df08c]
+- Updated dependencies [1767124]
+- Updated dependencies [8ecf5a6]
+- Updated dependencies [af705b9]
+- Updated dependencies [0502a7c]
+- Updated dependencies [7b35e4b]
+- Updated dependencies [8fb1295]
+- Updated dependencies [e16ed2d]
+- Updated dependencies [c6fd752]
+- Updated dependencies [f9bbddb]
+- Updated dependencies [dfd3705]
+- Updated dependencies [c77108c]
+- Updated dependencies [2735de6]
+- Updated dependencies [c19ac11]
+- Updated dependencies [6dee2cb]
+- Updated dependencies [e05f052]
+- Updated dependencies [0502a7c]
+- Updated dependencies [faad45e]
+- Updated dependencies [09c6a17]
+- Updated dependencies [c7cff19]
+- Updated dependencies [ba73a02]
+- Updated dependencies [cd09a7b]
+- Updated dependencies [f1abf0e]
+- Updated dependencies [f05b84e]
+- Updated dependencies [9b4b952]
+- Updated dependencies [2f947e4]
+- Updated dependencies [7d46648]
+- Updated dependencies [9b53d72]
+- Updated dependencies [bb4aa25]
+- Updated dependencies [75f1cdf]
+- Updated dependencies [662bdf9]
+- Updated dependencies [059a052]
+- Updated dependencies [53642d4]
+- Updated dependencies [8aae006]
+- Updated dependencies [c6cfdf1]
+- Updated dependencies [d147a13]
+- Updated dependencies [c6aaed8]
+- Updated dependencies [263f885]
+- Updated dependencies [dc334da]
+  - @object-ui/components@17.0.0
+  - @object-ui/i18n@17.0.0
+  - @object-ui/react@17.0.0
+  - @object-ui/types@17.0.0
+  - @object-ui/core@17.0.0
+
 ## 16.1.0
 
 ### Patch Changes
@@ -429,7 +804,7 @@
   `ObjectView` emit the dataset shape. The legacy inline aggregate is kept as a
   deprecated fallback so pre-ADR-0021 metadata keeps rendering.
 
-  Refs objectstack-ai/framework#1890
+  Refs objectstack-ai/objectstack#1890
 
 - ab168e4: Dashboard charts no longer render blank on first paint. Recharts'
   `ResponsiveContainer` was a child of a `flex … justify-center` box, so it

package/dist/AdvancedChartImpl.d.ts

@@ -1,4 +1,5 @@
 import { ChartConfig } from './ChartContainerImpl';
+import { NormalizedAxis, NormalizedSeries } from './normalizeChartSchema';
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -8,18 +9,20 @@ import { ChartConfig } from './ChartContainerImpl';
  */
 import * as React from "react";
 export interface AdvancedChartImplProps {
+    /**
+     * Chart family. `combo` is renderer-local and rarely needs to be passed:
+     * series declaring different families derive it (`effectiveChartFamily`),
+     * which is how `@objectstack/spec` expresses a combo chart.
+     */
     chartType?: 'bar' | 'column' | 'horizontal-bar' | 'line' | 'area' | 'pie' | 'donut' | 'radar' | 'scatter' | 'funnel' | 'combo' | 'treemap' | 'sankey';
     data?: Array<Record<string, any>>;
     config?: ChartConfig;
     xAxisKey?: string;
-    series?: Array<{
-        dataKey: string;
-        chartType?: 'bar' | 'line' | 'area';
-        variant?: 'current' | 'comparison';
-        opacity?: number;
-        dashArray?: string;
-        label?: string;
-    }>;
+    /**
+     * Plotted series, in the renderer's internal shape. Authors write the spec
+     * `series: [{ name, stack, yAxis, … }]`; `normalizeChartSchema` translates.
+     */
+    series?: NormalizedSeries[];
     className?: string;
     /** Categorical/series colour palette. Overrides the theme's `--chart-1..n`
      *  defaults so a page/dashboard can brand its charts (data-screens). */
@@ -33,6 +36,20 @@ export interface AdvancedChartImplProps {
      * categories absent here fall back to the positional palette, then the theme.
      */
     categoryColors?: Record<string, string>;
+    /**
+     * Declared category order for ordered-sequence charts (funnel / pyramid),
+     * keyed like {@link categoryColors} by the category VALUE or its display
+     * LABEL, listed in domain order.
+     *
+     * A funnel's shape asserts a sequence, so without this the renderer can only
+     * guess at one and sorts by value descending. That is right for a generic
+     * "biggest first" funnel and wrong for a sales pipeline, where the stages
+     * have a declared order (Qualification → Needs Analysis → Proposal →
+     * Negotiation) that a healthy pipeline happens to narrow along — and an
+     * unhealthy one does not. When supplied, this order wins; categories not
+     * listed keep their incoming relative order after the listed ones.
+     */
+    categoryOrder?: string[];
     /**
      * Optional drill-down click handler. Fires when a chart segment is clicked
      * with `{ category, series, value }`. Wired for bar/horizontal-bar/line/
@@ -43,6 +60,40 @@ export interface AdvancedChartImplProps {
         series?: string;
         value?: number;
     }) => void;
+    /**
+     * Spec `ChartAxis` presentation for the category axis — `format` (tick
+     * formatter), `title`, `showGridLines`. Its `field` already arrived as
+     * {@link AdvancedChartImplProps.xAxisKey}. Resolved by
+     * `normalizeChartSchema`, so the renderer never parses the author shape.
+     */
+    xAxis?: NormalizedAxis;
+    /**
+     * Spec `ChartConfig.yAxis` — one entry per value axis, in declaration order.
+     * Index 0 is the primary axis; a second entry (or one with
+     * `position: 'right'`) turns on the secondary axis that `series[].yAxis`
+     * binds to. Carries `min`/`max` (domain), `format` (ticks), `logarithmic`
+     * (scale) and `title`.
+     */
+    yAxes?: NormalizedAxis[];
+    /** Spec `ChartConfig.showLegend`. Omitted → shown (the schema default). */
+    showLegend?: boolean;
+    /** Spec `ChartConfig.showDataLabels` — print each point's value on the mark. */
+    showDataLabels?: boolean;
+    /** Spec `ChartConfig.title` / `.subtitle`, rendered above the plot. */
+    title?: string;
+    subtitle?: string;
+    /**
+     * Spec `ChartConfig.description` — the accessibility description. A chart is
+     * a picture to a screen reader; without this it announces as an unlabelled
+     * graphic, so the container carries it as `role="img"` + `aria-label`.
+     */
+    description?: string;
+    /** Spec `ChartConfig.height` — fixed plot height in pixels. */
+    height?: number;
+    /** Spec `ChartConfig.annotations` — reference lines / bands. */
+    annotations?: Array<Record<string, any>>;
+    /** Spec `ChartConfig.interaction` — `tooltips`, `brush`. */
+    interaction?: Record<string, any>;
     /**
      * Disable Recharts' entrance animation when `false`. Animations drive the
      * reveal via `requestAnimationFrame`, which browsers throttle/pause in
@@ -55,7 +106,10 @@ export interface AdvancedChartImplProps {
     isAnimationActive?: boolean;
 }
 /**
- * AdvancedChartImpl - The heavy implementation that imports Recharts with full features
- * This component is lazy-loaded to avoid including Recharts in the initial bundle
+ * Public entry point. A THIN wrapper purely so the unreadable-data guard can
+ * short-circuit without breaking the rules of hooks: the condition depends on
+ * `data`, which arrives asynchronously, so an early return inside the renderer
+ * would change its hook count between renders. The wrapper's own hook list is
+ * fixed, and the renderer below is reached with data it can actually plot.
  */
-export default function AdvancedChartImpl({ chartType: rawChartType, data: rawData, config, xAxisKey, series, className, colors, categoryColors, onChartClick, isAnimationActive, }: AdvancedChartImplProps): React.JSX.Element;
+export default function AdvancedChartImpl(props: AdvancedChartImplProps): React.JSX.Element;

package/dist/ChartRenderer.d.ts

@@ -23,7 +23,19 @@ export interface ChartRendererProps {
         chartType?: 'bar' | 'column' | 'horizontal-bar' | 'line' | 'area' | 'pie' | 'donut' | 'radar' | 'scatter' | 'funnel' | 'combo' | 'treemap' | 'sankey';
         data?: Array<Record<string, any>>;
         config?: Record<string, any>;
+        /** Internal binding. Authors write the spec `xAxis: { field }` (or the
+         *  report surface's bare string); `normalizeChartSchema` resolves both. */
         xAxisKey?: string;
+        /**
+         * Plotted series — **both shapes**, unlike the bindings below.
+         *
+         * `series` is the one binding the spec and the internal contract spell with
+         * the same key, so declaring only the internal shape here made
+         * `series: [{ name: 'total' }]` a type error on an author who was writing
+         * the protocol correctly — and, until #2945, one whose chart also rendered
+         * blank. `normalizeChartSchema` translates; an array that already speaks the
+         * internal shape passes through untouched.
+         */
         series?: Array<{
             dataKey: string;
             label?: string;
@@ -31,12 +43,46 @@ export interface ChartRendererProps {
             opacity?: number;
             dashArray?: string;
             chartType?: 'bar' | 'line' | 'area';
+            stack?: string;
+            yAxis?: 'left' | 'right';
+            color?: string;
+        } | {
+            name: string;
+            label?: unknown;
+            type?: string;
+            variant?: 'current' | 'comparison' | 'primary';
+            opacity?: number;
+            dashArray?: string;
+            stack?: string;
+            yAxis?: 'left' | 'right';
+            color?: string;
         }>;
+        /** Spec `ChartConfig` shape — honored via `normalizeChartSchema`
+         *  (objectui#2880). Listed here so the author-facing contract type-checks;
+         *  the internal props above win when both are present. */
+        xAxis?: unknown;
+        yAxis?: unknown;
+        showLegend?: boolean;
+        showDataLabels?: boolean;
+        title?: unknown;
+        subtitle?: unknown;
+        description?: unknown;
+        height?: number;
+        annotations?: Array<Record<string, any>>;
+        interaction?: Record<string, any>;
+        /** An author `type` rescued from the SDUI envelope's discriminator
+         *  collision by the react-page wrapper — see `normalizeChartSchema`. */
+        specType?: string;
         colors?: string[];
         /** Per-category colour map (value/label → colour). Wins over `colors` per
          *  category; see AdvancedChartImpl. Set by ObjectChart from select/lookup
          *  dimension option colours and/or an explicit author map. */
         categoryColors?: Record<string, string>;
+        /** Declared category order (value/label keys, in domain order) for
+         *  ordered-sequence charts — funnel/pyramid stages. Set by DatasetWidget
+         *  from the dimension's picklist order or an explicit `stageOrder`; see
+         *  AdvancedChartImpl. Omitted → the funnel's value-descending default. */
+        categoryOrder?: string[];
         /** Pass `false` for a deterministic, export-safe render with no entrance
          *  animation (see AdvancedChartImpl). Omitted → animated default. */
         isAnimationActive?: boolean;

package/dist/ObjectChart.d.ts

@@ -4,13 +4,29 @@ import { default as React } from 'react';
  * Local implementation to avoid a dependency on @object-ui/fields.
  */
 export declare function humanizeLabel(value: string): string;
+/**
+ * The result column an object-bound `aggregate` projects its value under
+ * (framework#3701, `chartAggregateValueKey` in `@objectstack/spec/ui`).
+ *
+ * The raw `field` name — an object-bound aggregate does NOT decorate it the way
+ * a dataset measure is named (`sum_amount`). Only `count` may omit `field`, and
+ * it then lands under the literal `'count'`, which is the alias the engine
+ * projects `COUNT(*)` under. Exported so every path that builds these rows
+ * agrees on one key instead of each re-deriving it.
+ */
+export declare function aggregateValueKey(aggregate: {
+    field?: string;
+    function?: string;
+}): string;
+/** Suffix the previous-window value carries under a compareTo overlay. */
+export declare const COMPARISON_SUFFIX = "__comparison";
 /**
  * Client-side aggregation for fetched records.
  * Groups records by `groupBy` field and applies the aggregation function
  * to the `field` values in each group.
  */
 export declare function aggregateRecords(records: any[], aggregate: {
-    field: string;
+    field?: string;
     function: string;
     groupBy: string;
 }): any[];