@object-ui/plugin-charts 16.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,476 @@
 # @object-ui/plugin-charts
 
+## 17.2.0
+
+### Minor Changes
+
+- 4a51e77: Stop declaring 14 symbols across ten packages under names `@objectstack/spec`
+  owns (objectui#3161, objectstack#4115 batch 7 — the long tail, one or two
+  entries per package). All ten packages leave the ledger, which drops from 17
+  collisions across 11 packages to 3 across 1.
+
+  **Renamed exports** — in every case the spec exports the same name for a
+  _different_ thing, so the old name was a mis-description rather than a dialect:
+
+  | package                    | was                                | now                                                  | what the spec's same-named export is                                                                                                       |
+  | :------------------------- | :--------------------------------- | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
+  | `@object-ui/fields`        | `FieldWidgetProps`                 | `FieldWidgetComponentProps`                          | the DECLARED field-widget plugin props contract (a zod object; `field.type` is the `FieldType` enum, `readonly`/`required` carry defaults) |
+  | `@object-ui/layout`        | `PageHeaderProps`                  | `PageHeaderComponentProps`                           | the authored `page:header` node — a zod schema of `title`, `subtitle`, an icon NAME, `breadcrumb`, `actions: string[]`                     |
+  | `@object-ui/layout`        | `Page`                             | `PageNodeRenderer`                                   | the authored page metadata DOCUMENT (`name`, `label`, `type`, `regions`)                                                                   |
+  | `@object-ui/plugin-detail` | `ObjectFieldLike`                  | `ObjectDefFieldLike`                                 | the i18n duck type `translateObject` walks (`help`/`description`, plus `[key: string]: any`)                                               |
+  | `@object-ui/plugin-grid`   | `ColumnSummaryConfig`              | `ColumnSummarySetting`                               | the OBJECT form of `ListColumn.summary` **only** — the local one was the whole union, shorthand included                                   |
+  | `@object-ui/plugin-grid`   | `isMultiValueField`                | `hasMultiValueShape`                                 | the spec's classifier, which requires a def with a `type`; the local one is called with `undefined`                                        |
+  | `@object-ui/collaboration` | `RealtimeConfig`                   | `RealtimeSubscriptionConfig`                         | the app's realtime DECLARATION (`enabled`, `transport`, `subscriptions[]`)                                                                 |
+  | `@object-ui/plugin-charts` | `ChartConfig`                      | `ChartContainerConfig`                               | the authored chart document (`type`, `xAxis`, `series`, `showLegend`, …)                                                                   |
+  | `@object-ui/plugin-form`   | `FormSection` / `FormSectionProps` | `FormSectionContainer` / `FormSectionContainerProps` | the authored form-section metadata (`name`, `pane`, `visibleWhen`, `fields`)                                                               |
+  | `@object-ui/providers`     | `Theme`                            | `ThemePreference`                                    | a whole theme DOCUMENT (`name`, `label`, `colors`, `typography`)                                                                           |
+  | `@object-ui/runner`        | `App` (default export)             | `RunnerApp`                                          | the authored application metadata type **and** the `App.create()` builder                                                                  |
+  | `@object-ui/sdui-parser`   | `ValidationResult`                 | `ManifestValidationResult`                           | plugin-manifest validation (`{ valid, errors?, warnings? }`), exported from both `kernel` and `contracts`                                  |
+
+  `ManifestValidationResult` follows the `<what was validated>Validation<Error|Result>`
+  convention registered on objectstack#4115 (`@object-ui/core` took
+  `SchemaNodeValidationResult` in batch 4). `PageHeaderComponentProps` deliberately
+  reuses the name `@object-ui/app-shell` already chose for its own header props in
+  batch 3, so one concept does not acquire two dialect names one package apart.
+
+  **Now derived from the spec instead of hand-written:**
+
+  - `@object-ui/fields` — `isFileIdToken` is re-exported from
+    `@objectstack/spec/data`. The local copy was character-for-character identical
+    to the spec's function while its comment said it "mirrors" it, so every
+    behaviour test passed and only reference identity could tell the two apart.
+    The regex is a wire decision: widening it server-side while a copy here kept
+    the old bound would make every new id read as "not a reference", and the
+    widget would submit the legacy inline blob to a backend expecting a reference.
+  - `@object-ui/plugin-detail` — `FeedFilterMode` is re-exported from
+    `@objectstack/spec/data`, in a file that already imported the sibling
+    `FeedItemType` from the spec.
+  - `@object-ui/plugin-grid` — the eleven-member aggregation union is now the
+    spec's `ColumnSummary` enum, so the total `Record<ColumnSummaryType, string>`
+    label map turns a member the spec adds into a compile error instead of a
+    blank footer cell. `ColumnSummarySetting` is `NonNullable<ListColumn['summary']>`,
+    i.e. whatever forms the spec itself accepts. `hasMultiValueShape` delegates to
+    the spec's `isMultiValueField` rather than re-deriving it from
+    `MULTI_OPTION_TYPES` / `MULTI_CAPABLE_TYPES`.
+  - `@object-ui/providers` — `ThemePreference` is the spec's `ThemeMode` union
+    plus the one legacy `'system'` spelling this provider still honours for stored
+    preferences, read off the schema's own `_zod` carrier so the package takes no
+    zod dependency.
+
+  `@objectstack/spec` moves from `devDependencies` to `dependencies` in
+  `@object-ui/fields` (it re-exports a runtime function) and `@object-ui/providers`
+  (its public `.d.ts` now references the spec).
+
+  Scored `minor`, not `major`, per this repo's fixed-group rule — objectui's major
+  tracks `@objectstack`, so breaking changes of our own ship as minor with the
+  semantics spelled out above (see AGENTS.md §版本号策略). A `major` here would carry
+  all 39 packages of the fixed group to `18.0.0` and off objectstack's 17.x line.
+
+### Patch Changes
+
+- Updated dependencies [4ae0ac4]
+- Updated dependencies [696e3c1]
+- Updated dependencies [bca45cc]
+- Updated dependencies [a889e31]
+- Updated dependencies [09d30a4]
+- Updated dependencies [4bf612c]
+- Updated dependencies [335041c]
+- Updated dependencies [b414983]
+- Updated dependencies [256f8cc]
+- Updated dependencies [d9668a7]
+- Updated dependencies [4b470b9]
+- Updated dependencies [cb82705]
+- Updated dependencies [f572849]
+- Updated dependencies [f6e8d78]
+- Updated dependencies [ea96284]
+- Updated dependencies [d3584c6]
+- Updated dependencies [a8ad6c0]
+- Updated dependencies [444457c]
+- Updated dependencies [850033c]
+- Updated dependencies [022e4c3]
+- Updated dependencies [009e25d]
+- Updated dependencies [726b89c]
+  - @object-ui/types@17.2.0
+  - @object-ui/components@17.2.0
+  - @object-ui/core@17.2.0
+  - @object-ui/react@17.2.0
+  - @object-ui/i18n@17.2.0
+
+## 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 +900,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 { ChartContainerConfig } 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;
+    config?: ChartContainerConfig;
     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/ChartContainerImpl.d.ts

@@ -11,7 +11,23 @@ declare const THEMES: {
     readonly light: "";
     readonly dark: ".dark";
 };
-export type ChartConfig = {
+/**
+ * Per-series presentation for `<ChartContainer>`: a map from series dataKey to
+ * the legend label, icon and colour (or per-theme colours) that key renders
+ * with. Shadcn's chart primitive, kept in this package's own copy of it.
+ *
+ * Named `ChartContainerConfig`, not `ChartConfig` (objectui#3161,
+ * objectstack#4115 ledger batch 7). `@objectstack/spec/ui` owns `ChartConfig`
+ * for the authored chart METADATA — `type: bar | line | pie | …`, `xAxis`,
+ * `yAxis`, `series`, `showLegend`, `annotations` — and the collision was not
+ * theoretical here: `AdvancedChartImpl.tsx` declares `config?: ChartConfig`
+ * meaning THIS map, three lines above doc comments that say "Spec
+ * `ChartConfig.yAxis`" and "Spec `ChartConfig.showLegend`" meaning the other
+ * one. One identifier, two concepts, one file. `normalizeChartSchema` is the
+ * seam between them: it reads the authored spec chart and produces the
+ * renderer's axes/series, of which this map is the styling half.
+ */
+export type ChartContainerConfig = {
     [k in string]: {
         label?: React.ReactNode;
         icon?: React.ComponentType;
@@ -24,7 +40,7 @@ export type ChartConfig = {
     });
 };
 declare function ChartContainer({ id, className, children, config, disableSettleRemount, ...props }: React.ComponentProps<"div"> & {
-    config: ChartConfig;
+    config: ChartContainerConfig;
     children: React.ComponentProps<typeof ResponsiveContainer>["children"];
     /**
      * Skip the settle re-mount below. Set by callers that render their series with
@@ -36,7 +52,7 @@ declare function ChartContainer({ id, className, children, config, disableSettle
 }): React.JSX.Element;
 declare const ChartStyle: ({ id, config }: {
     id: string;
-    config: ChartConfig;
+    config: ChartContainerConfig;
 }) => React.JSX.Element | null;
 declare const ChartTooltip: typeof Tooltip;
 declare function ChartTooltipContent({ active, payload, className, indicator, hideLabel, hideIndicator, label, labelFormatter, labelClassName, formatter, color, nameKey, labelKey, }: any): React.JSX.Element | null;