feat(charts): honor ChartAxis.stepSize, ChartConfig.description and .height (framework#3752) (#2888)

The tail of the declared-≠-delivered sweep from #2880 / framework#3729. Three
ChartConfig props reached the renderer and did nothing.

stepSize: Recharts has no "a tick every N units" prop — tickCount is a hint it
may ignore and 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. 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. The
step-count division carries a small epsilon because 0.5/0.1 is
5.000000000000001 one way and 4.999999999999999 the other, and a bare floor()
drops a whole tick in the second case. More than 200 ticks is refused rather
than rendered.

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.

height: was read only by the legacy ChartBarRenderer, not by the advanced path
that draws every real chart. Now an inline style on the chart container, 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.

ChartInteraction.zoom and .clickAction are removed from the schema in the
framework companion rather than implemented here — brush already narrows a
range, and a segment click already has two working owners (drillDown,
onSegmentClick).

Author: os-zhuang

.changeset/chartconfig-remaining-inert-props.md

@@ -0,0 +1,31 @@
+---
+"@object-ui/plugin-charts": minor
+---
+
+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.

packages/plugin-charts/src/AdvancedChartImpl.specConfig.test.tsx

@@ -151,6 +151,36 @@ describe('AdvancedChartImpl — spec annotations', () => {
   });
 });
 
+describe('AdvancedChartImpl — spec container props (#3752)', () => {
+  it('announces the accessibility description', () => {
+    const { container } = render(<AdvancedChartImpl {...base} description="Invoice value by status" />);
+    const el = container.querySelector('[data-slot="chart"]');
+    expect(el?.getAttribute('role')).toBe('img');
+    expect(el?.getAttribute('aria-label')).toBe('Invoice value by status');
+  });
+
+  it('leaves the container unlabelled when no description is declared', () => {
+    // No description is not the same as an empty one — don't stamp role="img"
+    // on an unlabelled graphic, which is worse for a screen reader than a
+    // plain div it can skip.
+    const { container } = render(<AdvancedChartImpl {...base} />);
+    expect(container.querySelector('[data-slot="chart"]')?.getAttribute('role')).toBeNull();
+  });
+
+  it('applies an explicit height over the container default', () => {
+    const { container } = render(<AdvancedChartImpl {...base} height={420} />);
+    expect((container.querySelector('[data-slot="chart"]') as HTMLElement)?.style.height).toBe('420px');
+  });
+
+  it('lays y ticks at the declared stepSize', () => {
+    const { container } = render(
+      <AdvancedChartImpl {...base} yAxes={[{ field: 'total', min: 0, max: 120, stepSize: 40 }]} />,
+    );
+    const texts = Array.from(container.querySelectorAll('text')).map((t) => t.textContent ?? '');
+    for (const tick of ['0', '40', '80', '120']) expect(texts).toContain(tick);
+  });
+});
+
 describe('AdvancedChartImpl — spec interaction', () => {
   it('adds the brush when interaction.brush is on', () => {
     const { container } = render(<AdvancedChartImpl {...base} interaction={{ brush: true }} />);

packages/plugin-charts/src/AdvancedChartImpl.tsx

@@ -47,7 +47,7 @@ import {
   ChartConfig
 } from './ChartContainerImpl';
 import { mapScatterClick, mapTreemapClick, mapSankeyClick } from './chartDrillEvents';
-import { formatterFor, domainFor, type NormalizedAxis, type NormalizedSeries } from './normalizeChartSchema';
+import { formatterFor, domainFor, ticksFor, type NormalizedAxis, type NormalizedSeries } from './normalizeChartSchema';
 import { buildCategoryRank } from '@object-ui/core';
 
 // Default color fallback for chart series
@@ -160,6 +160,14 @@ export interface AdvancedChartImplProps {
   /** 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`. */
@@ -238,6 +246,8 @@ export default function AdvancedChartImpl({
   showDataLabels,
   title,
   subtitle,
+  description,
+  height,
   annotations,
   interaction,
 }: AdvancedChartImplProps) {
@@ -252,7 +262,15 @@ export default function AdvancedChartImpl({
   // tell ChartContainer to skip its settle re-mount — avoids a needless 1-frame
   // reflow on the dashboard's first paint (#2756). Animated callers keep the
   // heal; this object is empty for them, leaving their markup unchanged.
-  const containerProps = isAnimationActive === false ? { disableSettleRemount: true } : {};
+  // Everything every ChartContainer call site needs, so a new container-level
+  // spec prop lands on all eight chart families at once instead of one branch.
+  const containerProps = {
+    ...(isAnimationActive === false ? { disableSettleRemount: true as const } : {}),
+    // An explicit height beats the container's default `h-[350px]` class
+    // because an inline style wins over a utility class.
+    ...(height ? { style: { height } } : {}),
+    ...(description ? { role: 'img' as const, 'aria-label': description } : {}),
+  };
   const [isMobile, setIsMobile] = React.useState(false);
 
   // Recharts' top-level onClick payload: { activeLabel, activePayload, ... }
@@ -434,19 +452,40 @@ export default function AdvancedChartImpl({
     [secondaryY?.format, formatYTick],
   );
 
-  /** Recharts props derived from one spec y-axis (domain / scale / label). */
-  const yAxisSpecProps = React.useCallback((axis: NormalizedAxis | undefined) => {
+  /**
+   * Every number plotted on one side of a dual axis (or on the only axis) —
+   * the range `stepSize` lays its ticks over.
+   */
+  const axisValues = React.useCallback((side: 'left' | 'right') => {
+    const keys = series
+      .filter((s: any) => (hasDualAxis ? (s.yAxis === 'right' ? 'right' : 'left') === side : side === 'left'))
+      .map((s: any) => s.dataKey);
+    const out: number[] = [];
+    for (const row of data) {
+      for (const k of keys) {
+        const n = Number(row?.[k]);
+        if (Number.isFinite(n)) out.push(n);
+      }
+    }
+    return out;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data, series, hasDualAxis]);
+
+  /** Recharts props derived from one spec y-axis (domain / scale / ticks / label). */
+  const yAxisSpecProps = React.useCallback((axis: NormalizedAxis | undefined, side: 'left' | 'right' = 'left') => {
     if (!axis) return {};
     const domain = domainFor(axis);
+    const ticks = ticksFor(axis, axisValues(side));
     return {
+      ...(ticks ? { ticks } : {}),
       ...(domain ? { domain } : {}),
       // `allowDataOverflow` is what makes an explicit domain actually clip
       // rather than being silently widened to fit the data.
       ...(domain ? { allowDataOverflow: true } : {}),
       ...(axis.logarithmic ? { scale: 'log' as const, domain: domain ?? ([1, 'auto'] as any) } : {}),
       ...(axis.title ? { label: { value: axis.title, angle: -90, position: 'insideLeft' as const } } : {}),
     };
-  }, []);
+  }, [axisValues]);
 
   // `showGridLines` is per-axis in the spec; the renderer draws one grid, so
   // an explicit `false` on EITHER axis turns off that axis's lines.
@@ -785,7 +824,7 @@ export default function AdvancedChartImpl({
           <CartesianGrid {...gridProps} />
           <XAxis dataKey={xAxisKey} {...xAxisCommonProps} />
           <YAxis yAxisId="left" tickLine={false} axisLine={false} tickFormatter={yTickFormatter} width={48} {...yAxisSpecProps(primaryY)} />
-          <YAxis yAxisId="right" orientation="right" tickLine={false} axisLine={false} tickFormatter={y2TickFormatter} width={48} {...yAxisSpecProps(secondaryY)} />
+          <YAxis yAxisId="right" orientation="right" tickLine={false} axisLine={false} tickFormatter={y2TickFormatter} width={48} {...yAxisSpecProps(secondaryY, 'right')} />
           {tooltipsEnabled ? <ChartTooltip content={<ChartTooltipContent />} /> : null}
           {legendVisible ? (
             <ChartLegend
@@ -902,7 +941,7 @@ export default function AdvancedChartImpl({
                 axisLine={false}
                 tickFormatter={y2TickFormatter}
                 width={48}
-                {...yAxisSpecProps(secondaryY)}
+                {...yAxisSpecProps(secondaryY, 'right')}
               />
             ) : null}
           </>

packages/plugin-charts/src/ChartRenderer.tsx

@@ -61,6 +61,8 @@ export interface ChartRendererProps {
     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
@@ -160,6 +162,8 @@ export const ChartRenderer: React.FC<ChartRendererProps> = ({ schema, onChartCli
         showDataLabels={props.spec.showDataLabels}
         title={props.spec.title}
         subtitle={props.spec.subtitle}
+        description={props.spec.description}
+        height={props.spec.height ?? schema.height}
         annotations={props.spec.annotations}
         interaction={props.spec.interaction}
       />

packages/plugin-charts/src/normalizeChartSchema.test.ts

@@ -10,7 +10,7 @@
  *      (DashboardRenderer / ObjectView / the dataset path pass it explicitly).
  */
 import { describe, it, expect } from 'vitest';
-import { normalizeChartSchema, formatterFor, domainFor } from './normalizeChartSchema';
+import { normalizeChartSchema, formatterFor, domainFor, ticksFor } from './normalizeChartSchema';
 
 describe('normalizeChartSchema — spec shape', () => {
   it('resolves the ChartConfig axis + series shape', () => {
@@ -140,6 +140,59 @@ describe('formatterFor', () => {
   });
 });
 
+describe('normalizeChartSchema — container-level props (#3752)', () => {
+  it('carries description and height', () => {
+    const out = normalizeChartSchema({ description: 'Invoice value by status', height: 320 });
+    expect(out.description).toBe('Invoice value by status');
+    expect(out.height).toBe(320);
+  });
+
+  it('ignores a non-positive height rather than collapsing the chart', () => {
+    expect(normalizeChartSchema({ height: 0 }).height).toBeUndefined();
+    expect(normalizeChartSchema({ height: -10 }).height).toBeUndefined();
+  });
+
+  it('carries stepSize on an axis', () => {
+    expect(normalizeChartSchema({ yAxis: [{ field: 'total', stepSize: 25 }] }).yAxes?.[0].stepSize).toBe(25);
+  });
+
+  it('ignores a non-positive stepSize', () => {
+    expect(normalizeChartSchema({ yAxis: [{ field: 'total', stepSize: 0 }] }).yAxes?.[0].stepSize).toBeUndefined();
+  });
+});
+
+describe('ticksFor', () => {
+  it('lays ticks over the data range at the declared step', () => {
+    expect(ticksFor({ stepSize: 50 }, [10, 120])).toEqual([0, 50, 100, 150]);
+  });
+
+  it('honours an explicit domain over the data', () => {
+    expect(ticksFor({ min: 100, max: 300, stepSize: 100 }, [10, 20])).toEqual([100, 200, 300]);
+  });
+
+  it('reaches an explicit max the step would otherwise overshoot', () => {
+    expect(ticksFor({ min: 0, max: 25, stepSize: 10 }, [])).toEqual([0, 10, 20, 25]);
+  });
+
+  it('does not drift on a fractional step', () => {
+    expect(ticksFor({ min: 0, max: 0.5, stepSize: 0.1 }, [])).toEqual([0, 0.1, 0.2, 0.3, 0.4, 0.5]);
+  });
+
+  it('returns undefined with no stepSize — Recharts keeps its automatic ticks', () => {
+    expect(ticksFor({ min: 0, max: 100 }, [])).toBeUndefined();
+    expect(ticksFor(undefined, [])).toBeUndefined();
+  });
+
+  it('refuses an absurd tick count instead of hanging the page', () => {
+    // 100_000 / 0.5 ticks is a wrong config, not a chart.
+    expect(ticksFor({ stepSize: 0.5 }, [0, 100_000])).toBeUndefined();
+  });
+
+  it('returns undefined when there is nothing to measure', () => {
+    expect(ticksFor({ stepSize: 10 }, [])).toBeUndefined();
+  });
+});
+
 describe('domainFor', () => {
   it('pins both ends', () => {
     expect(domainFor({ min: 0, max: 100 })).toEqual([0, 100]);

packages/plugin-charts/src/normalizeChartSchema.ts

@@ -88,6 +88,8 @@ export interface NormalizedAxis {
   format?: string;
   min?: number;
   max?: number;
+  /** Distance between ticks on this axis. */
+  stepSize?: number;
   /** Default true, per the spec schema. */
   showGridLines?: boolean;
   logarithmic?: boolean;
@@ -123,6 +125,10 @@ export interface NormalizedChartSchema {
   showDataLabels?: boolean;
   title?: string;
   subtitle?: string;
+  /** Accessibility description — announced to screen readers. */
+  description?: string;
+  /** Fixed plot height in pixels. */
+  height?: number;
   annotations?: AnyRec[];
   interaction?: AnyRec;
 }
@@ -156,6 +162,8 @@ function normalizeAxis(raw: unknown): NormalizedAxis | undefined {
   if (min !== undefined) out.min = min;
   const max = num(raw.max);
   if (max !== undefined) out.max = max;
+  const stepSize = num(raw.stepSize);
+  if (stepSize !== undefined && stepSize > 0) out.stepSize = stepSize;
   if (typeof raw.showGridLines === 'boolean') out.showGridLines = raw.showGridLines;
   if (typeof raw.logarithmic === 'boolean') out.logarithmic = raw.logarithmic;
   const position = str(raw.position);
@@ -270,6 +278,10 @@ export function normalizeChartSchema(schema: unknown): NormalizedChartSchema {
   if (title) out.title = title;
   const subtitle = label(schema.subtitle);
   if (subtitle) out.subtitle = subtitle;
+  const description = label(schema.description);
+  if (description) out.description = description;
+  const height = num(schema.height);
+  if (height !== undefined && height > 0) out.height = height;
   if (Array.isArray(schema.annotations) && schema.annotations.length) {
     out.annotations = schema.annotations.filter(isRec);
   }
@@ -321,6 +333,59 @@ export function formatterFor(format: string | undefined): ((value: any) => strin
   };
 }
 
+/**
+ * Explicit tick positions for an axis that declares a `stepSize`, or
+ * `undefined` to keep Recharts' automatic ticks.
+ *
+ * Recharts has no "every N units" prop — `tickCount` is a hint it may ignore
+ * and `interval` is for categorical axes — so honoring `stepSize` means
+ * handing it the tick array outright. The range comes 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.
+ *
+ * `values` should be every number plotted on this axis. An empty range, a
+ * non-finite one, or a step that would produce an absurd number of ticks
+ * (>`MAX_TICKS`) yields `undefined` — a 10,000-tick axis is a wrong config,
+ * and drawing it would hang the page rather than report the mistake.
+ */
+const MAX_TICKS = 200;
+
+export function ticksFor(axis: NormalizedAxis | undefined, values: number[]): number[] | undefined {
+  const step = axis?.stepSize;
+  if (!step || step <= 0) return undefined;
+
+  const finite = values.filter((v) => Number.isFinite(v));
+  const dataMin = finite.length ? Math.min(...finite) : undefined;
+  const dataMax = finite.length ? Math.max(...finite) : undefined;
+  // A value axis conventionally starts at zero unless told otherwise, which is
+  // also what Recharts' own auto domain does for bars/areas.
+  const lo = axis.min ?? Math.min(0, dataMin ?? 0);
+  const hi = axis.max ?? dataMax;
+  if (hi === undefined || !Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo) return undefined;
+
+  const start = Math.floor(lo / step) * step;
+  // An explicit `max` pins the domain, so the last tick must not overshoot it
+  // (Recharts would place a tick outside the plot). A data-derived max is not
+  // pinned, so round UP to the next step — otherwise the topmost value sits
+  // above the last gridline and the axis reads as truncated.
+  const end = axis.max !== undefined ? axis.max : Math.ceil(hi / step) * step;
+  // `(end - start) / step` is exact in decimal but not in binary: 0.5 / 0.1 is
+  // 5.000000000000001 one way and 4.999999999999999 the other, and a bare
+  // floor() drops a whole tick in the second case.
+  const count = Math.floor((end - start) / step + 1e-9) + 1;
+  if (count < 1 || count > MAX_TICKS) return undefined;
+
+  const out: number[] = [];
+  for (let i = 0; i < count; i++) {
+    // Re-derive from the index rather than accumulating, so a fractional step
+    // (0.1) does not drift into 0.30000000000000004 territory across the axis.
+    out.push(Number((start + i * step).toPrecision(12)));
+  }
+  // Make sure an explicit max is actually reachable as a tick.
+  if (axis.max !== undefined && out[out.length - 1] < axis.max) out.push(axis.max);
+  return out;
+}
+
 /**
  * Recharts `domain` for an axis, or `undefined` to keep the auto domain.
  * A half-open range (only `min`, only `max`) pins that end and leaves the