@object-ui/plugin-charts 17.6.0 → 18.0.0

package/README.md

@@ -20,11 +20,14 @@ pnpm add @object-ui/plugin-charts
 ### Automatic Registration (Side-Effect Import)
 
 ```typescript
-// In your app entry point (e.g., App.tsx or main.tsx)
+// In your app entry point (e.g., App.tsx or main.tsx). This side-effect import
+// is the one that registers the components; the type import below is erased at
+// build time and registers nothing.
 import '@object-ui/plugin-charts';
+import type { BarChartSchema } from '@object-ui/plugin-charts';
 
-// Now you can use chart-bar type in your schemas
-const schema = {
+// Now you can use the bar-chart type in your schemas
+const schema: BarChartSchema = {
   type: 'bar-chart',
   data: [
     { name: 'Jan', value: 400 },
@@ -43,9 +46,11 @@ const schema = {
 import { chartComponents } from '@object-ui/plugin-charts';
 import { ComponentRegistry } from '@object-ui/core';
 
-// Manually register if needed
+// Manually register if needed. The third argument is not optional in practice:
+// `register()` without a namespace is the deprecated form and warns at runtime.
+// `plugin-charts` is the namespace this package registers under itself.
 Object.entries(chartComponents).forEach(([type, component]) => {
-  ComponentRegistry.register(type, component);
+  ComponentRegistry.register(type, component, { namespace: 'plugin-charts' });
 });
 ```
 
@@ -70,17 +75,27 @@ const schema: BarChartSchema = {
 
 ## Schema API
 
-```typescript
-{
-  type: 'bar-chart',
-  data?: Array<Record<string, any>>,  // Chart data
-  dataKey?: string,                    // Y-axis data key (default: 'value')
-  xAxisKey?: string,                   // X-axis label key (default: 'name')
-  height?: number,                     // Chart height in pixels (default: 400)
-  color?: string,                      // Bar color (default: '#8884d8')
-  className?: string                   // Tailwind classes
-}
-```
+`BarChartSchema` is the published contract — import it (see **TypeScript Support**
+above) rather than re-declaring this shape in your own code. It is re-exported
+from `@object-ui/types`, so the type you annotate with and the schema that
+validates your document are the same declaration.
+
+| Member | Type | Required | Default | Notes |
+| --- | --- | --- | --- | --- |
+| `type` | `'bar-chart'` | yes | — | The registry keyword this schema renders under. |
+| `data` | `Array<Record<string, any>>` | no | `[]` | Rows to plot — one bar per row. |
+| `dataKey` | `string` | no | `'value'` | Row key holding the bar's value (the y axis). |
+| `xAxisKey` | `string` | no | `'name'` | Row key holding the bar's category label (the x axis). |
+| `height` | `number` | no | `400` | Chart height in pixels — a number, not a CSS length. |
+| `color` | `string` | no | `hsl(var(--primary))` | Bar fill colour, forwarded to Recharts verbatim. |
+| `className` | `string` | no | `''` | Tailwind classes. Inherited from `BaseSchema`. |
+
+Every default above is the renderer's own — the parameter defaults of
+`ChartBarRenderer`'s implementation in `src/ChartImpl.tsx`, which is what an
+omitted member actually resolves to at render time. Note `color`: the type's
+JSDoc and the registration's `defaultProps` both still record `'#8884d8'`, but
+neither is read on the render path, so an omitted `color` renders as the theme
+token above.
 
 ## Lazy Loading Architecture
 
@@ -93,7 +108,7 @@ When bundled, Vite automatically creates separate chunks:
 - `index.js` (~200 bytes) - The entry point
 - `ChartImpl-xxx.js` (~541 KB minified, ~136 KB gzipped) - The lazy-loaded implementation
 
-The Recharts library is only downloaded when a `chart-bar` component is actually rendered, not on initial page load.
+The Recharts library is only downloaded when a `bar-chart` component is actually rendered, not on initial page load.
 
 ## Build Output Example
 

package/dist/AdvancedChartImpl.d.ts

@@ -1,5 +1,5 @@
-import { ChartContainerConfig } from './ChartContainerImpl';
-import { NormalizedAxis, NormalizedSeries } from './normalizeChartSchema';
+import { ChartContainerConfig } from './ChartContainerImpl.js';
+import { DeclaredChartFamily, NormalizedAxis, NormalizedSeries } from './normalizeChartSchema.js';
 import { ChartSegmentClickEvent } from '@object-ui/core';
 /**
  * ObjectUI
@@ -11,11 +11,22 @@ import { ChartSegmentClickEvent } from '@object-ui/core';
 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.
+     * Chart family, as the schema names it. `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.
+     *
+     * Typed as the declared chart families ({@link DeclaredChartFamily}: the
+     * spec's `ChartType` and the `object-chart` node's own union, by reference),
+     * so a misspelled family does not compile. The family dispatch below is the
+     * one place a family becomes a form: a chart for `RENDERABLE`, the number
+     * card for the single-value families, the tabular notice for the tabular
+     * ones, and a notice for anything else, which is how a value from unvalidated
+     * JSON outside the type is answered at runtime. ⛔ There is no default family
+     * (objectui#11520): an absent family is that notice too, never a bar. A
+     * caller that means a bar passes `'bar'`.
      */
-    chartType?: 'bar' | 'column' | 'horizontal-bar' | 'line' | 'area' | 'pie' | 'donut' | 'radar' | 'scatter' | 'funnel' | 'combo' | 'treemap' | 'sankey';
+    chartType?: DeclaredChartFamily;
     data?: Array<Record<string, any>>;
     config?: ChartContainerConfig;
     xAxisKey?: string;
@@ -83,17 +94,24 @@ export interface AdvancedChartImplProps {
     onChartClick?: (event: ChartSegmentClickEvent) => void;
     /**
      * Spec `ChartAxis` presentation for the category axis — `format` (tick
-     * formatter), `title`, `showGridLines`. Its `field` already arrived as
+     * formatter), `title`, `showGridLines`, `position` (the side it is drawn
+     * on — see `placeXAxis`), and on scatter's measure x axis `min` / `max` /
+     * `stepSize` / `logarithmic` as well. 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`.
+     * Index 0 is the primary axis. A second entry turns on the second value
+     * axis; each entry's `position` picks the slot it is drawn in, and
+     * `series[].yAxis` binds a series to a slot (`placeYAxes` in
+     * `normalizeChartSchema`). A lone entry is the chart's only value axis,
+     * drawn on the side it names. Carries `min`/`max` (domain), `format`
+     * (ticks), `logarithmic` (scale) and `title`. An entry after the second
+     * (after the first on `scatter`, which draws one y axis) is drawn on no
+     * axis, and the chart carries a note naming it (`yAxisUndrawnNotes`,
+     * objectui#10691, objectui#10721).
      */
     yAxes?: NormalizedAxis[];
     /** Spec `ChartConfig.showLegend`. Omitted → shown (the schema default). */

package/dist/ChartRenderer.d.ts

@@ -34,12 +34,28 @@ export interface ChartRendererProps {
          * 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.
+         * blank. `normalizeChartSchema` translates every entry, of either shape,
+         * uniformly — see the normalization comment in the component body.
+         *
+         * Both arms carry the per-series family override `type`, with the same
+         * member type (objectui#8086): the renderer honours it on either shape,
+         * because every entry goes through `normalizeSeries` (`01c27c431`), and
+         * `ChartDataSeriesSchema` declares `dataKey` and `name` independently
+         * optional beside it — so a `dataKey` entry carrying `type` is what the
+         * contract and the renderer both accept, and this union says so.
+         * `chartType` stays on the `dataKey` arm alone: it is the renderer's
+         * INTERNAL spelling of `type`, and it wins when an entry writes both.
+         * Pinned at compile time in `ChartRenderer.seriesTypeArm-8086.test.ts`.
+         *
+         * `aggregate` is internal too, on the `dataKey` arm alone (objectui#11681):
+         * the measure's aggregate, carried by `buildChartSeries` from the dataset
+         * answer, so a value axis over counts draws whole-number ticks. The
+         * authoring face refuses it by name (`ChartDataSeriesSchema.aggregate`).
          */
         series?: Array<{
             dataKey: string;
             label?: string;
+            type?: string;
             variant?: 'current' | 'comparison';
             opacity?: number;
             dashArray?: string;
@@ -47,6 +63,7 @@ export interface ChartRendererProps {
             stack?: string;
             yAxis?: 'left' | 'right';
             color?: string;
+            aggregate?: string;
         } | {
             name: string;
             label?: unknown;

package/dist/ObjectChart.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
-import { humanizeLabel } from '@object-ui/core';
+import { humanizeLabel, ChartSegmentClickEvent } from '@object-ui/core';
+import { BaseSchema, ObjectChartSchema } from '@object-ui/types';
 /**
  * Humanize a snake_case or kebab-case string into Title Case.
  *
@@ -28,16 +29,84 @@ export declare function aggregateValueKey(aggregate: {
     field?: string;
     function?: string;
 }): string;
+/**
+ * The category axis this chart plots BY — resolved ONCE, for every reader.
+ *
+ * ## Why this is a function and not three inline reads
+ *
+ * "Which column is the category?" was spelled three times in this file, at
+ * three fidelities, and the refusal below would have been a fourth. That is the
+ * objectui#5042 / objectui#7544 drift shape — a second opinion of one question
+ * that nothing keeps in agreement — and objectui#7544's fix
+ * (`resolveListChartBinding` in `plugin-list/src/ListView.tsx`) is the same move
+ * one layer up, on the AUTHORED list-view chart block.
+ *
+ * ⚠️ It is one layer up, not this layer. `resolveListChartBinding` reads
+ * `{ chart, options.chart }` — the block an author writes on a LIST VIEW, whose
+ * only binding since objectui#6152 round 15 is an ADR-0021 `dataset` (its
+ * pre-ADR-0021 `xAxisField` / `categoryField` / `yAxisFields` leg retired). By
+ * the time a schema reaches this component the relays have already translated
+ * that block into `{ dataset, dimensions, values }`, or, for a block naming no
+ * dataset, into an object-bound node naming no category, and the producers that never
+ * had such a block at all (the two dashboard surfaces, and directly authored
+ * `object-chart` metadata) compose the translated shape straight away. So the
+ * upstream resolver cannot be CALLED here — asked for `schema.chart` it would
+ * read `undefined` off every chart this component renders and answer
+ * "unresolvable" for all of them. What is shared is the QUESTION and the rule
+ * for answering it; the vocabulary is necessarily this layer's.
+ *
+ * ## The three legs, in the order the render pipeline applies them
+ *
+ * 1. A structured `GroupBy` node (`{ field, dateGranularity }`) — its `field`
+ *    IS the category, and nothing substitutes for it: `runAggregate` sends the
+ *    node itself as the server's `groupBy`, so a node naming no field has no
+ *    other spelling that could rescue it.
+ * 2. A legacy string `aggregate.groupBy`.
+ * 3. Otherwise the chart plots rows as fetched, and the category is whatever
+ *    `normalizeChartSchema` — this package's ONE translation of the spec's
+ *    author-facing chart shape into the renderer's internal contract — resolves
+ *    for the x axis: `xAxisKey`, else spec `xAxis.field`, else a bare string
+ *    `xAxis`. Reading `schema.xAxisKey` alone here would have refused a chart
+ *    that authored the spec spelling and renders correctly today, because
+ *    `ChartRenderer` normalizes DOWNSTREAM of this component.
+ *
+ * Returns `undefined` only when the schema names no category by any declared
+ * spelling — a real answer, and what {@link ObjectChart}'s refusal keys on.
+ *
+ * ⚠️ LEDGERED, on purpose: this is the one `normalizeChartSchema` call in the
+ * package that passes NO language (objectui#8943). It is safe here and only
+ * here — the call reads `.xAxisKey`, a COLUMN NAME, and nothing else. No
+ * `I18nLabel` slot on the result is ever read through this path, so there is no
+ * label for a language to resolve. Keeping the function pure (it is called from
+ * plain module scope, outside any component) is worth more than a language
+ * argument that would change no byte of its answer. ⛔ If this ever starts
+ * reading `title` / `subtitle` / `description` / an axis `title` / a series
+ * `label`, it needs the viewer's language and can no longer be called from
+ * outside a component.
+ */
+export declare function resolveChartCategoryField(schema: {
+    aggregate?: {
+        groupBy?: unknown;
+    } | undefined;
+    xAxisKey?: unknown;
+    xAxis?: unknown;
+} | undefined | null): string | undefined;
 /** 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.
+ *
+ * `function` is optional because the `switch` below already implements that:
+ * an absent (or unknown) function falls through to `sum`. The parameter used to
+ * say `function: string`, which was a claim about the CALLER rather than about
+ * this body — and no caller could satisfy it once `ObjectChartSchema.aggregate`
+ * was declared with the requiredness its own reads have (objectui#7946).
  */
 export declare function aggregateRecords(records: any[], aggregate: {
     field?: string;
-    function: string;
+    function?: string;
     groupBy: string;
 }): any[];
 /**
@@ -55,7 +124,52 @@ export declare function aggregateRecords(records: any[], aggregate: {
  */
 export declare function resolveGroupByLabels(data: any[], groupByField: string, objectSchema: any, dataSource?: any, translateOption?: (value: string, fallbackLabel: string) => string): Promise<any[]>;
 export { extractRecords } from '@object-ui/core';
-export declare const ObjectChart: (props: any) => React.JSX.Element;
+/**
+ * Props of {@link ObjectChart} — anchored to the published `ObjectChartSchema`
+ * (objectui#7946, maintainer ruling 2026-09-09 option A), as objectui#6576 did
+ * for `ObjectGalleryProps.schema`.
+ *
+ * ## What this replaces, and what it buys
+ *
+ * This component was published as `(props: any)`, so every `schema={{ … }}`
+ * literal handed to it — including the two in `app-shell`'s `ObjectView` — was
+ * type-checked against NOTHING. That is the mechanism that let objectui#7891's
+ * undeclared `config` rung live from the day it was written until someone read
+ * the spec by hand, and it is why the two `as any` casts on those literals
+ * measured INERT: an `any` consumer accepts a cast and its absence alike.
+ *
+ * With the anchor, a wrong VALUE TYPE on a declared key is a compile error at
+ * the producer (`xAxisKey: 42`, `series: 'x'`, `type: 'chart'`, and every
+ * `BaseSchema` member — `visible: 42`). ⚠️ A MISSPELLED key was still accepted
+ * while `BaseSchema` carried `[key: string]: any` (objectui#5155), the same
+ * ceiling objectui#6576 accepted knowingly; objectui#8347 removed it, so a
+ * misspelled key in a fresh literal is refused now.
+ * `__tests__/ObjectChart.schemaAnchor-7946.test.ts` pins both halves, the
+ * flipped ceiling row included, so the anchor is not read as more than it is.
+ */
+export interface ObjectChartProps {
+    /**
+     * The `object-chart` node — anchored to the exported schema type. Every
+     * `BaseSchema` member is writable, `bind` / `className` / `data` included;
+     * the widget's own keys are declared there.
+     */
+    schema: ObjectChartSchema;
+    /**
+     * Host data source. `any` deliberately, and it is NOT a residue of the shape
+     * this card removed: it is the type `SchemaRendererContext.dataSource`
+     * itself carries, and this component falls back to that context value, so a
+     * narrower declaration here would claim a guarantee the fallback cannot
+     * keep. Narrowing it is a repo-wide `dataSource` interface, not this card.
+     */
+    dataSource?: any;
+    /**
+     * Optional host-owned segment click. When provided (e.g. a dataset widget
+     * that owns precise drill-through), it takes over the chart click and the
+     * widget's own object-drill drawer is suppressed.
+     */
+    onSegmentClick?: (ev: ChartSegmentClickEvent) => void;
+}
+export declare const ObjectChart: (props: ObjectChartProps) => React.JSX.Element;
 /**
  * Registry shell for `object-chart` — maps the spec's
  * `PageComponentSchema.dataSource` binding onto the keys {@link ObjectChart}
@@ -67,5 +181,23 @@ export declare const ObjectChart: (props: any) => React.JSX.Element;
  * spec documents rendered an empty frame with no error and no request. Lives
  * here, beside the registration, rather than in `ChartContainerImpl` — the
  * binding is a registry-boundary concern, not a rendering one.
+ *
+ * ## Its props type — the node BEFORE the gate (objectui#8885)
+ *
+ * This shell used to be published as `(props: any)`. `schema` is now
+ * `BaseSchema`, the node `SchemaRenderer` hands every registered renderer, and
+ * ⛔ NOT `ObjectChartSchema`. The node arrives here before the gate has mapped
+ * its `dataSource` binding, and nothing has validated it as a chart. Typing it
+ * post-gate would claim a validation that has not happened, and that type's
+ * `type: 'object-chart'` literal is also false for the `chart` alias that
+ * `index.tsx` registers this same shell under.
+ *
+ * Every other prop is `ObjectChart`'s own, taken from `ObjectChartProps`, so
+ * the type is CLOSED: a misspelled prop name is an excess-property error, not
+ * an `any` passed straight through. Both halves are existing exported names;
+ * no new type is minted. Pinned by
+ * `__tests__/ObjectChartBlock.props-8885.test.tsx`.
  */
-export declare const ObjectChartBlock: (props: any) => React.JSX.Element;
+export declare const ObjectChartBlock: (props: Omit<ObjectChartProps, "schema"> & {
+    schema: BaseSchema;
+}) => React.JSX.Element;

package/dist/index.d.ts

@@ -1,10 +1,70 @@
-import { ChartBarRenderer, ChartRenderer } from './ChartRenderer';
-export type { BarChartSchema } from './types';
+import { ChartBarRenderer, ChartRenderer } from './ChartRenderer.js';
+export type { BarChartSchema } from './types.js';
 export { ChartBarRenderer, ChartRenderer };
-export { ObjectChart, ObjectChartBlock } from './ObjectChart';
-export { normalizeChartSchema } from './normalizeChartSchema';
-export type { NormalizedChartSchema } from './normalizeChartSchema';
+export { ObjectChart, ObjectChartBlock } from './ObjectChart.js';
+export type { ObjectChartProps } from './ObjectChart.js';
+export { normalizeChartSchema } from './normalizeChartSchema.js';
+export type { NormalizedChartSchema } from './normalizeChartSchema.js';
 export declare const chartComponents: {
-    'bar-chart': import('react').FC<import('./ChartRenderer').ChartBarRendererProps>;
-    chart: import('react').FC<import('./ChartRenderer').ChartRendererProps>;
+    'bar-chart': import('react').FC<import('./ChartRenderer.js').ChartBarRendererProps>;
+    chart: import('react').FC<import('./ChartRenderer.js').ChartRendererProps>;
 };
+/**
+ * ⛔ The `pie-chart`, `donut-chart` and `radar-chart` node type keys are
+ * RETIRED (objectui#10859 batch 8, phase 2c, the seat's fork ruling on that
+ * card, by the objectui#10393 / objectui#8760 route). Each family is reached as
+ * `{ type: 'chart', chartType: 'pie' | 'donut' | 'radar' }`, the spelling that
+ * draws ("chartType is the spelling that draws", objectui#8760).
+ *
+ * ## What was here, and why it went
+ *
+ * Three registrations of the generic `ChartRenderer`, one per key, each in the
+ * `plugin-charts` namespace, so each stored `plugin-charts:KEY` and the bare
+ * `KEY` fallback; their families came from `CHART_TYPE_KEYWORD_FAMILIES` rows
+ * (objectui#7401), which went in the same change. No `@object-ui/types` arm
+ * claims any of the three, so `objectui validate` refused such a node at
+ * `type` while the registry mounted it.
+ *
+ * ## Why unregistering is the whole retirement
+ *
+ * Phase 2b found one producer and reported the three as a fork:
+ * `examples/chart-examples.ts` in this package authored all three, pinned by
+ * objectui#7401's "the in-repo examples draw what they say". The fork ruling
+ * moved those examples to `chart` + `chartType` first; the 7401 pin still
+ * asserts each draws its family and no bar. Re-measured for phase 2c after that
+ * move: 0 producers in source, docs, examples, the catalog or objectstack, and
+ * 0 runtime emission. The console's lazy stubs went in the same change, so no
+ * table or host keeps a key alive. The pie, donut and radar FAMILIES are
+ * untouched.
+ */
+/**
+ * ⛔ The `scatter-chart` node type key is RETIRED (objectui#10859 batch 8,
+ * phase 2b, the seat's ruling on that card, by the objectui#10393 /
+ * objectui#8760 route). The scatter family is reached the way every other
+ * family is: `{ type: 'chart', chartType: 'scatter' }`, the spelling that
+ * draws ("chartType is the spelling that draws", objectui#8760).
+ *
+ * ## What was here, and why it went
+ *
+ * A registration of the generic `ChartRenderer` under `scatter-chart` in the
+ * `plugin-charts` namespace (described, not quoted: source readers such as
+ * `@object-ui/types`' node-slot test take a quoted call in a comment for a live
+ * one) — a second key on the generic renderer, which stored
+ * both `plugin-charts:scatter-chart` and the bare `scatter-chart` fallback, and
+ * whose family came from its `CHART_TYPE_KEYWORD_FAMILIES` row (objectui#7401).
+ * No `@object-ui/types` arm claims it, so `objectui validate` refused a node
+ * authored `type: 'scatter-chart'` at `type` while the registry mounted it.
+ *
+ * ## Why unregistering is the whole retirement
+ *
+ * Nothing wrote the node: 0 producers in source, docs, examples, the catalog
+ * or objectstack, and 0 runtime emission, re-measured for phase 2b. Its
+ * `CHART_TYPE_KEYWORD_FAMILIES` row and the console's lazy stub
+ * (`apps/console/src/register-plugins.ts`) went in the same change, so no table
+ * or host keeps the key alive. The `scatter` FAMILY is untouched.
+ *
+ * `pie-chart`, `donut-chart` and `radar-chart` were ruled the same way. Phase
+ * 2b kept them registered as a fork, because `examples/chart-examples.ts` still
+ * authored them; phase 2c retired them once those examples had moved (the note
+ * above).
+ */