@pushwoosh/kit-charts 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushwoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai-documentation.md

@@ -0,0 +1,378 @@
+# @pushwoosh/kit-charts - AI Agent Documentation
+
+## Overview
+
+React chart library rendering to SVG, with a Highcharts-shaped configuration
+model.
+
+**Current state:** all five v1 renderers are implemented — `line`, `column`,
+`area`, `pie`, `heatmap` — with `normal` and `percent` stacking, grouped columns,
+donuts via `innerSize`, data labels and stack labels. A series type with no
+registered renderer is skipped: the chart draws its other series and logs which
+module is missing.
+
+`heatmap` takes `[x, row, value]` points, colours each cell through
+`colorAxis` (`min`/`max` plus `stops`), and takes its rows from
+`yAxis.categories`. A second y axis with `linkedTo` mirrors the first one's
+geometry while showing its own labels. The colour axis itself is not drawn as a
+legend yet, so a heatmap contributes no legend items.
+
+## Installation
+
+```bash
+npm install @pushwoosh/kit-charts
+```
+
+## Core Dependencies
+
+- **react**: >= 18.0.0 (peer dependency)
+- **styled-components**: >= 5.3.3 (peer dependency)
+- **@pushwoosh/kit-constants**: runtime dependency — fonts, greys and tooltip
+  colours come from the design system tokens. The series palette is built in.
+
+Scales, tick selection and time formatting are hand-written rather than taken
+from d3, because size is the point of the library.
+
+## Public API
+
+- `Chart` — the general component; takes `options`, optional `renderers`,
+  `isLoading`, `empty`, `loading`, `className`, `containerProps`.
+- `LineChart`, `ColumnChart`, `AreaChart`, `PieChart` — presets that pin one renderer each.
+- `StackedColumnChart` — `ColumnChart` with `stacking` on by default; takes a
+  `stacking` prop (`'normal'` | `'percent'`), and an explicit
+  `plotOptions.column.stacking` still wins.
+- `line`, `column`, `area`, `pie`, `heatmap` — the renderers themselves, for
+  `Chart`'s `renderers` prop or for `registerSeries`.
+- `registerSeries(...renderers)` / `resolveRenderers(local?)` / `getRenderer(map, type)`.
+- `formatTime(pattern, epochMs)` — strftime-style, UTC.
+- `DEFAULT_COLORS` and the other palette constants.
+- All configuration and contract types.
+
+## Configuration Model
+
+`chart`, `title`, `subtitle`, `xAxis`, `yAxis`, `colorAxis`, `legend`, `tooltip`,
+`plotOptions`, `series`, `colors`, `meta`, `numberFormat`.
+
+Three-level inheritance is preserved: `plotOptions.series` → `plotOptions[type]` →
+the series' own options, later winning. Nested objects merge rather than replace.
+
+Deliberate differences from Highcharts:
+
+1. `meta` replaces `custom`, typed via
+   `ChartOptions<TChartMeta, TSeriesMeta, TPointMeta>`.
+2. Formatters take a typed context **argument**; there is no `this`.
+3. Formatters return a `ReactNode`, never an HTML string. There is no `useHTML`.
+4. `TooltipPoint` exposes `prev` and `next` neighbours directly.
+5. Formatters see `ctx.chart.title` and `ctx.chart.meta`, not the option tree.
+6. No `credits` option.
+7. No `reflow`; resize is observed automatically.
+8. `chart.margin*` replaces the computed distance from that edge to the plot,
+   the same as Highcharts, rather than adding to it.
+9. `tooltip` defaults to `shape: 'callout'`: a dark bubble with a beak anchored
+   to the point, matching the product hint style. `shape: 'box'` or
+   `followPointer` gives the floating-near-the-cursor behaviour instead.
+10. A y axis with `categories` becomes a band axis. `reversed` puts the first
+    category on top; `linkedTo` takes the target axis' geometry and keeps its own
+    labels, which is how one grid carries two label columns.
+11. `min`/`max` rounding (`nice`) is automatic and per end, not a user-facing
+    option: an end left unset is rounded outward to a whole tick step; an end the
+    caller set explicitly is used as-is. `yAxis: { min: 0 }` still gets a rounded,
+    label-friendly top end instead of losing headroom to a raw data max.
+12. `states.inactive.opacity` is off unless set. Highcharts dims the series a
+    hover is not on by default; switching that on here would restyle every chart
+    already drawn.
+
+`numberFormat` is the chart-wide number-to-text rule. Axis labels, data labels,
+stack labels and the default tooltip all print through it, so a thousands
+separator is configured once rather than in four callbacks. Anything with its
+own `formatter` or `format` wins over it.
+
+`allowDecimals: false` keeps every tick on an axis whole, as a count axis needs:
+the step is chosen from the candidates that stay integral at its magnitude, and
+never falls below 1.
+
+`labels.allowOverlap` defaults to false on both axes and on data labels. A label
+whose box would run into one already placed loses its text — Highcharts hides
+the label and keeps the tick, and so do we. A data-label formatter returning an
+element cannot be measured, so it is always drawn.
+
+## Plot bands and lines
+
+`plotLines` and `plotBands` live on either axis. A band takes `from`/`to`, a line
+takes `value`; on a category axis both address a category by name and a band
+covers the whole slot. Both accept a `label`, and a `zIndex` of 5 or more draws
+them over the series instead of under it — the value Highcharts users reach for.
+
+## Interaction
+
+`onPointClick(point, event)` reports the point nearest a click inside the plot,
+with its `meta`. Drill-down hangs off this; there is no per-point `events` object.
+
+`chart.zoomType: 'x'` lets a drag across the plot narrow the x axis to what was
+dragged over, with a reset button in the corner (`chart.resetZoomText` renames
+it). The zoom is applied as a `min`/`max` override on the first x axis, so the
+model is built from the options as usual. Only a continuous axis zooms, and a
+drag shorter than a few pixels is treated as a click.
+
+A horizontally scrolling plot (`chart.scrollablePlotArea.minWidth`) lifts its
+left-hand y axes into a fixed layer, so the plot slides under the row labels
+rather than taking them with it. A right-hand axis and a vertically scrolling
+chart stay in the scrolling canvas.
+
+Time values are epoch milliseconds and are formatted in UTC, so output does not
+shift with the viewer's timezone.
+
+## Legend
+
+`legendSymbol` on a series overrides the shape its item keys with — a line series
+draws a dash by default, and a dot reads better when the legend is a plain key
+above the plot rather than a swatch column beside it.
+
+`layout` (`'horizontal' | 'vertical'`, default `'horizontal'`) chooses one row of
+items or one item per row. `verticalAlign` (`'top' | 'middle' | 'bottom'`,
+default `'bottom'`) picks which edge the legend takes: `'top'`/`'bottom'` reserve
+height above/below the plot; `'middle'` has no plot edge to sit on, so it
+reserves width and sits beside the plot instead — the same trade Highcharts
+makes. `align` (`'left' | 'center' | 'right'`, default `'left'`) positions items
+along whichever axis the legend occupies — the row when it's below/above, the
+column when it's at the side. `x`/`y` shift the computed position by an offset.
+
+Geometry lives in one module, `src/core/layout/legend-layout.ts`
+(`measureLegend` reserves the space, `layoutLegend` places the items), so
+`Chart` and the legend component never disagree on where it sits. A heatmap
+draws no legend items — see Overview.
+
+## Data Shapes
+
+A series accepts `number`, `null`, `[x, y]`, `[category, y]`, `[x, y, value]`, or
+`{ x, y, value, name, color, meta }`. A bare number takes its x from the array
+index. `null` is a gap; `NaN` and `Infinity` become gaps with a development
+warning, never zero.
+
+## Extension Point
+
+```ts
+interface SeriesRenderer<TSeries extends SeriesOptionsBase> {
+  readonly type: string;
+  readonly scales: { x: ScaleKind; y: ScaleKind };
+  extendDomain(series: TSeries, acc: DomainAcc): DomainAcc;
+  render(ctx: RenderContext<TSeries>): ReactNode;
+  hitTest(ctx: RenderContext<TSeries>, pointer: Point): PointHit[] | null;
+  legendItems(series: TSeries, seriesIndex: number, colors: readonly string[]): LegendItem[];
+}
+```
+
+`RenderContext` carries already-normalised `points`, the plot rectangle, the
+scales, the resolved colour, hover state and stack values.
+`extendDomain` is where a renderer widens an axis beyond its data — columns and
+areas need the zero baseline included, a heatmap needs half a cell of slack at
+both ends of x. `scales.y` may be a band scale (a categorical axis): a renderer
+that needs numbers on y takes them through `continuousY(ctx)` and draws nothing
+when the axis is categorical. `scales.color` is present when the options declare
+a `colorAxis`.
+
+Register before use:
+
+```ts
+import { registerSeries } from '@pushwoosh/kit-charts';
+import { line } from '@pushwoosh/kit-charts/series/line';
+
+registerSeries(line);
+```
+
+`registerSeries` is idempotent. Registering a *different* renderer under an
+occupied type throws in development and overwrites in production. `Chart` also
+accepts a `renderers` prop that takes priority over the global registry.
+
+**Invariant:** `src/core` must never import from `src/series`. An eslint rule
+enforces it. Breaking it puts every renderer into every consumer's bundle.
+
+## Error Handling
+
+`Chart` wraps its body in an error boundary placed *outside* the component that
+builds the model — a formatter throwing during that build would otherwise escape
+and unmount the surrounding tree. A failed chart shows a fallback in its own box.
+
+An unregistered series type is skipped with a development-time console error; the
+rest of the chart still draws.
+
+## Build and configuration
+
+The package is a *library* on `@pushwoosh/frontend-builder-engine`: `lib:build`
+(tsc, then the engine's own babel pass for styled-components) and `lib:check-types`.
+It therefore carries none of the application-template configuration — no
+`babel.config.js` (the engine's babel pass runs with `configFile: false` and never
+reads one), no `.browserslistrc` and no `.stylelintrc`. Only what something
+actually reads is here: `tsconfig.json`, `playground/tsconfig.json`,
+`eslint.config.mjs` (the engine's config plus this project's two rules),
+`pushwoosh.config.js`, and `jest.config.js`.
+
+`jest.config.js` is hand-written because the engine has no test runner. The
+`playground` script calls webpack directly for the same reason in reverse: the
+engine's `lib:command:playground` currently only prints the command it would run —
+its spawn is commented out upstream — so deferring to it would start nothing.
+
+## Testing
+
+`tests/fixtures/` is the golden corpus: every configuration the library must
+render, named by capability. `renderableCases(implementedTypes)` filters it to
+what the current renderers can draw, so tests do not fail on unwritten types.
+
+Tests live outside `src/` so the build cannot ship them.
+
+## Legend
+
+Legend items are buttons: clicking one hides or shows what it stands for, and the
+chart rescales to what is left. Usually that is a series, but a renderer whose
+legend keys *points* — a pie, one item per slice — sets `pointIndex` on its items,
+and then a click takes out that slice alone and the rest share the circle out
+again. The point stays in `ctx.points` with its index listed in
+`ctx.hiddenPoints`, so the renderer can animate it away: a pie gives it no angle,
+which closes it like a fan while the slices after it slide into the room it
+leaves — the path keeps its command structure throughout, which is what lets the
+browser interpolate it. Nothing counts a hidden point: not a total, not an axis
+extent, not hit testing. Hidden series keep their legend entry — dimmed and
+struck through — and stay mounted, which is what lets the change animate instead
+of popping. How a series leaves is the renderer's call through `exit`: with
+`'collapse'` the renderer redraws its shapes flat on their own baseline when
+`ctx.hidden` is set — a column shrinks into the segment it grew from, so a stacked
+one does not slide through its neighbour — and the fade waits for that to play.
+`'fade'` is the default, for shapes with no baseline to fall onto: lines, areas,
+pie slices, heatmap cells; they are excluded from the domains, the stacks, the
+column slots and hit testing. Keyboard users get the same through Enter/Space and
+a focus ring; `prefers-reduced-motion` turns the transitions off.
+
+Switching off the *last* series would otherwise reshape the axes under it, and the
+line would jump to the new scale before it finished fading — so with nothing on
+show the chart holds the geometry of the last state that had something, and only
+the opacity changes. Switching a series back on rebuilds from the data as usual.
+
+`Chart` owns that state, seeded from `series[].visible` and reset when the series
+list changes. `toggleSeries={false}` makes the legend a plain key again, and
+`onSeriesToggle(seriesIndex, visible)` reports every click for consumers that
+persist the choice.
+
+## Title
+
+`title.text` and `subtitle.text` are drawn at the top of the chart — 18px semibold
+and 12px muted by default, aligned by `align`, and the layout reserves their height.
+
+`title.hint` adds an info disc after the title text: hovering or focusing it opens
+the same dark callout a point uses, with the text wrapped. Escape closes it. Use it
+for what the chart counts — the definition a reader needs and a subtitle has no room
+for. `xAxis.labels.hint(ctx)` puts the same callout on a tick label, for a step
+name that means nothing to a reader who has not been told.
+
+`title.caption` is a muted note on the far end of the title's own row — the period
+the figures cover, when they were counted. Only the main title draws one.
+
+## Animation
+
+`series.animation` sets one series' own transition length — `{ duration: 500 }`,
+or `false` for none. Everything left alone runs on the chart clock below.
+
+Two mechanisms, chosen by the shape being moved.
+
+**CSS transitions** carry shapes whose geometry interpolates correctly component by
+component: the vertices of a line or an area, and the `x`/`y`/`width`/`height` of a
+column. `SeriesLayer` in `Chart.styles.ts` owns those.
+
+**A frame-by-frame tween** (`useTweenedNumbers`) carries shapes that are *generated*
+from numbers, where blending the drawing instructions is not the same as blending
+the shape. A pie is the case in point: interpolating an arc's endpoints drags them
+along straight lines while the radius stays put, so the arc bulges, and the
+large-arc flag flips halfway through into a visible jump. The pie therefore tweens
+its angles and radius and regenerates the arc every frame — the same approach as
+D3's `arcTween`, which interpolates `startAngle`/`endAngle` and re-runs the arc
+generator, and as Highcharts, whose animator tweens the `start`, `end` and `r`
+attributes of its arc symbol. A renderer that does this sets `animatesGeometry`, and
+the chart then keeps CSS off its shapes so the two do not fight.
+
+Both read their duration and easing from `src/core/animation/motion.ts`, so one
+click moves everything at one speed: `MOTION_MS` with `MOTION_EASING`, the CSS
+spelling of the `easeOutCubic` the tween uses. Hover feedback — the hint badge —
+is the one exception at `HOVER_MS`, because an affordance should answer faster
+than the chart does. `prefers-reduced-motion: reduce` switches both mechanisms
+off.
+
+## Tooltip
+
+`tooltip.table` lays the body out as a table instead: a header line, a heading
+row, and one row per series with its swatch. Each column takes a `cell(point)`
+returning a `ReactNode`. Use it when a point carries more than one figure — a
+count and its share — and a single line would run them together. A tabular
+tooltip defaults to a light card, because the dark hint chrome reads badly at
+that size.
+
+A column `title` is a string or a function of the hover, and a function that
+returns `null` drops its column for that hover. That is what a column comparing
+against the previous point needs: it names the date it compares with, and on the
+first point there is no such date and no column.
+
+Default shape is `callout`: a dark bubble with a beak anchored to the point,
+flipping under the point when there is no room above and sliding sideways to stay
+on screen while the beak keeps pointing at the point. `shape: 'box'` or
+`followPointer: true` gives a box that trails the cursor instead.
+
+The default body shows the x (dates through `dateFormat`), a swatch per series and
+the value wrapped in `valuePrefix`/`valueSuffix`. `formatter` replaces the body and
+returns a `ReactNode`; `ctx.points[].prev`/`.next` carry the neighbouring points, so
+a delta needs no extra lookup. `shared: true` collects every series at the hovered x.
+
+Golden cases: `tooltip/callout`, `tooltip/shared-formatter`.
+
+## Styling
+
+The library ships no inline styles: everything visual is either an SVG
+presentation attribute or a styled-component in `*.styles.ts`. Every layout
+distance — label gaps, axis gutters, legend rows, tooltip padding — is a named
+constant in `src/core/layout/metrics.ts`, not a number typed at the point of use;
+that is what keeps the chrome consistent across components. Fonts, greys and
+tooltip colours come from `@pushwoosh/kit-constants`, so charts match the product
+without the consumer configuring anything.
+
+## Columns
+
+`borderPosition: 'top'` strokes only the edge the value reaches — the top of a
+bar counting up, the bottom of one counting down — instead of boxing the bar.
+With `fillOpacity` on the body and `states.hover.fillOpacity` to deepen it, that
+is the funnel look: the series keeps its real colour, so the legend swatch and
+the tooltip dot stay readable, and only the bar is washed out.
+
+A data label whose text carries `\n` is drawn as stacked lines, styled by
+`style` for the first and `secondaryStyle` for the rest. It is one label: it
+moves, measures and hides as one.
+
+## The device pixel grid
+
+`useSize` floors the measured box, so the canvas is always a whole number of
+pixels and never wider than the box that holds it. Browser zoom sizes a box in
+fractions of a css pixel; storing the fraction left the canvas at its old width
+whenever the box moved by less than half a pixel, and the container's
+`overflow: hidden` then shaved the right edge.
+
+`crisp(position, strokeWidth)` in `layout/metrics.ts` puts a stroke where the
+device can draw it in one row: an odd stroke on a half pixel, an even one on a
+whole. Grid lines, the x axis line and its ticks, and plot lines all go through
+it. Without it a 1px line centred on a whole pixel is split across the two rows
+either side and reads as two grey ones, and which lines land where changes at
+every zoom step — the chart appears to change weight as the page zooms. Series
+geometry is deliberately *not* snapped: it carries the data positions the tooltip
+and hit-testing share.
+
+Both rules are Highcharts', arithmetic included, and both work in css pixels:
+neither library reads `devicePixelRatio` (Highcharts 12.6 does not mention it
+once). So the snapping is exact at whole device ratios, and at the rest — 125%,
+or any zoom out, where a 1px css line is thinner than a device pixel and grey
+wherever it sits — it buys consistency rather than sharpness. What it does buy at
+every ratio is that the geometry never changes: measured across zoom 50%–150%,
+the canvas stays 688 in a 688.5 box and the grid stays on the same half pixels,
+which is exactly what Highcharts emits under the same sweep.
+
+## Size
+
+One runtime dependency (`@pushwoosh/kit-constants`, for design-system tokens);
+SVG output; renderers are only bundled when imported, which is what the
+`src/core` import restriction protects. There is no automated size gate —
+adding a dependency or letting the core reach into `src/series` will not be
+caught by CI.

package/core/Chart/Axes.d.ts

@@ -0,0 +1,19 @@
+import { type ReactElement } from 'react';
+import { type AxisModel } from '../model/build-model';
+import { type Rect } from '../types/geometry';
+interface GridProps {
+    plot: Rect;
+    yAxis: AxisModel | undefined;
+}
+export declare function Grid({ plot, yAxis }: GridProps): ReactElement | null;
+interface XAxisProps {
+    plot: Rect;
+    axis: AxisModel;
+}
+export declare function XAxis({ plot, axis }: XAxisProps): ReactElement | null;
+interface YAxisProps {
+    plot: Rect;
+    axis: AxisModel;
+}
+export declare function YAxis({ plot, axis }: YAxisProps): ReactElement | null;
+export {};

package/core/Chart/Axes.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Hinted } from './Hinted';
+import { DEFAULT_FONT_SIZE, measureText } from '../layout/measure-text';
+import { AXIS_LABEL_GAP, AXIS_TITLE_GAP, crisp, TEXT_BASELINE_SHIFT, X_AXIS_LABEL_DROP, X_AXIS_TITLE_GAP } from '../layout/metrics';
+import { DEFAULT_AXIS_COLOR, DEFAULT_GRID_COLOR, DEFAULT_MUTED_TEXT_COLOR } from '../model/palette';
+const textProps = style => ({
+  fill: (style === null || style === void 0 ? void 0 : style.color) ?? DEFAULT_MUTED_TEXT_COLOR,
+  fontFamily: style === null || style === void 0 ? void 0 : style.fontFamily,
+  fontSize: (style === null || style === void 0 ? void 0 : style.fontSize) ?? DEFAULT_FONT_SIZE,
+  fontWeight: style === null || style === void 0 ? void 0 : style.fontWeight
+});
+const ANCHOR = {
+  left: 'start',
+  center: 'middle',
+  right: 'end'
+};
+/** A tick label, wrapped in its explanation when the axis gave it one. */
+function TickLabel({
+  hint,
+  x,
+  y,
+  anchor,
+  style,
+  children
+}) {
+  const text = _jsx("text", {
+    x: x,
+    y: y,
+    textAnchor: anchor,
+    ...textProps(style),
+    children: children
+  });
+  return hint ? _jsx(Hinted, {
+    text: hint,
+    children: text
+  }) : text;
+}
+export function Grid({
+  plot,
+  yAxis
+}) {
+  // A hidden axis takes its grid with it: `visible: false` is how a chart that
+  // labels its bars instead of its axis — a funnel — gets a bare plot.
+  if (!yAxis || yAxis.options.visible === false || yAxis.options.gridLineWidth === 0) {
+    return null;
+  }
+  const color = yAxis.options.gridLineColor ?? DEFAULT_GRID_COLOR;
+  const width = yAxis.options.gridLineWidth ?? 1;
+  const {
+    scale
+  } = yAxis;
+  // A categorical axis draws its grid on the row boundaries rather than through
+  // the middle of a row, so that a row sits inside one cell of the grid.
+  const positions = scale.kind === 'band' ? [...scale.domain().map(value => scale.map(value)), plot.y + plot.height] : yAxis.ticks.map(tick => tick.position);
+  return _jsx("g", {
+    "aria-hidden": true,
+    children: positions.map(position => _jsx("line", {
+      x1: plot.x,
+      x2: plot.x + plot.width,
+      y1: crisp(position, width),
+      y2: crisp(position, width),
+      stroke: color,
+      strokeWidth: width
+    }, `grid-${position}`))
+  });
+}
+function AxisTitle({
+  title,
+  x,
+  y,
+  anchor,
+  defaultRotation
+}) {
+  var _title$style;
+  if (!(title !== null && title !== void 0 && title.text) || ((_title$style = title.style) === null || _title$style === void 0 ? void 0 : _title$style.display) === 'none') {
+    return null;
+  }
+  const rotation = title.rotation ?? defaultRotation;
+  const at = {
+    x: x + (title.x ?? 0),
+    y: y + (title.y ?? 0)
+  };
+  return _jsx("text", {
+    x: at.x,
+    y: at.y,
+    textAnchor: rotation === 0 ? anchor : 'middle',
+    transform: rotation === 0 ? undefined : `rotate(${rotation} ${at.x} ${at.y})`,
+    ...textProps(title.style),
+    children: title.text
+  });
+}
+const titleY = (options, plot) => {
+  var _options$title;
+  const align = ((_options$title = options.title) === null || _options$title === void 0 ? void 0 : _options$title.align) ?? 'middle';
+  if (align === 'high') {
+    return plot.y;
+  }
+  if (align === 'low') {
+    return plot.y + plot.height;
+  }
+  return plot.y + plot.height / 2;
+};
+export function XAxis({
+  plot,
+  axis
+}) {
+  var _options$labels, _options$labels2, _options$title2;
+  const {
+    options
+  } = axis;
+  if (options.visible === false) {
+    return null;
+  }
+  const onTop = options.opposite === true;
+  const offset = options.offset ?? 0;
+  const direction = onTop ? -1 : 1;
+  const baseline = onTop ? plot.y - offset : plot.y + plot.height + offset;
+  const lineColor = options.lineColor ?? DEFAULT_AXIS_COLOR;
+  const tickLength = options.tickLength ?? 0;
+  const tickWidth = options.tickWidth ?? 1;
+  const labelsEnabled = ((_options$labels = options.labels) === null || _options$labels === void 0 ? void 0 : _options$labels.enabled) !== false;
+  const labelY = baseline + direction * (tickLength + (onTop ? AXIS_LABEL_GAP : X_AXIS_LABEL_DROP)) + (((_options$labels2 = options.labels) === null || _options$labels2 === void 0 ? void 0 : _options$labels2.y) ?? 0);
+  return _jsxs("g", {
+    children: [options.lineWidth === 0 ? null : _jsx("line", {
+      x1: plot.x,
+      x2: plot.x + plot.width,
+      y1: crisp(baseline, options.lineWidth ?? 1),
+      y2: crisp(baseline, options.lineWidth ?? 1),
+      stroke: lineColor,
+      strokeWidth: options.lineWidth ?? 1
+    }), axis.ticks.map(tick => {
+      var _options$labels3, _options$labels4;
+      return _jsxs("g", {
+        children: [tickLength > 0 && tickWidth > 0 ? _jsx("line", {
+          x1: crisp(tick.position, tickWidth),
+          x2: crisp(tick.position, tickWidth),
+          y1: crisp(baseline, tickWidth),
+          y2: crisp(baseline + direction * tickLength, tickWidth),
+          stroke: options.tickColor ?? lineColor,
+          strokeWidth: tickWidth
+        }) : null, labelsEnabled && tick.label ? _jsx(TickLabel, {
+          hint: tick.hint,
+          x: tick.position + (((_options$labels3 = options.labels) === null || _options$labels3 === void 0 ? void 0 : _options$labels3.x) ?? 0),
+          y: labelY,
+          anchor: tick.anchor,
+          style: (_options$labels4 = options.labels) === null || _options$labels4 === void 0 ? void 0 : _options$labels4.style,
+          children: tick.label
+        }) : null]
+      }, `x-${tick.value}`);
+    }), _jsx(AxisTitle, {
+      title: options.title,
+      x: plot.x + plot.width / 2,
+      y: labelY + direction * ((((_options$title2 = options.title) === null || _options$title2 === void 0 ? void 0 : _options$title2.offset) ?? 0) + X_AXIS_TITLE_GAP),
+      anchor: "middle",
+      defaultRotation: 0
+    })]
+  });
+}
+export function YAxis({
+  plot,
+  axis
+}) {
+  var _options$labels5, _options$labels6, _options$title3, _options$title4;
+  const {
+    options
+  } = axis;
+  if (options.visible === false) {
+    return null;
+  }
+  const labelsEnabled = ((_options$labels5 = options.labels) === null || _options$labels5 === void 0 ? void 0 : _options$labels5.enabled) !== false;
+  const onRight = options.opposite === true;
+  const offset = options.offset ?? 0;
+  // `offset` pushes the whole axis — labels and title — away from the plot.
+  const edge = onRight ? plot.x + plot.width + AXIS_LABEL_GAP + offset : plot.x - AXIS_LABEL_GAP - offset;
+  const anchor = (((_options$labels6 = options.labels) === null || _options$labels6 === void 0 ? void 0 : _options$labels6.align) && ANCHOR[options.labels.align]) ?? (onRight ? 'start' : 'end');
+  const columnWidth = labelsEnabled ? axis.ticks.reduce((widest, tick) => {
+    var _options$labels7;
+    return Math.max(widest, measureText(tick.label, (_options$labels7 = options.labels) === null || _options$labels7 === void 0 ? void 0 : _options$labels7.style));
+  }, 0) : 0;
+  // Where the labels grow away from the plot, the title has to clear the whole
+  // column of them or it lands on top of the numbers.
+  const outwards = onRight ? anchor !== 'end' : anchor !== 'start';
+  const titleShift = outwards ? Math.ceil(columnWidth * (anchor === 'middle' ? 0.5 : 1)) + AXIS_TITLE_GAP : 0;
+  const titleX = onRight ? edge + titleShift + (((_options$title3 = options.title) === null || _options$title3 === void 0 ? void 0 : _options$title3.offset) ?? 0) : edge - titleShift - (((_options$title4 = options.title) === null || _options$title4 === void 0 ? void 0 : _options$title4.offset) ?? 0);
+  return _jsxs("g", {
+    children: [labelsEnabled ? axis.ticks.map(tick => {
+      var _options$labels8, _options$labels9;
+      return tick.label ? _jsx(TickLabel, {
+        x: edge + (((_options$labels8 = options.labels) === null || _options$labels8 === void 0 ? void 0 : _options$labels8.x) ?? 0),
+        y: tick.position + TEXT_BASELINE_SHIFT,
+        anchor: anchor,
+        hint: tick.hint,
+        style: (_options$labels9 = options.labels) === null || _options$labels9 === void 0 ? void 0 : _options$labels9.style,
+        children: tick.label
+      }, `y-${tick.value}`) : null;
+    }) : null, _jsx(AxisTitle, {
+      title: options.title,
+      x: titleX,
+      y: titleY(options, plot),
+      anchor: anchor,
+      defaultRotation: onRight ? 90 : -90
+    })]
+  });
+}

package/core/Chart/Chart.d.ts

@@ -0,0 +1,33 @@
+import { type HTMLAttributes, type MouseEvent as ReactMouseEvent, type ReactElement, type ReactNode } from 'react';
+import { type ChartOptions } from '../types/options';
+import { type AnySeriesRenderer } from '../types/renderer';
+/** The point a click landed on, as handed to `onPointClick`. */
+export interface ClickedPoint<TPointMeta = unknown> {
+    seriesIndex: number;
+    seriesName: string;
+    pointIndex: number;
+    x: number | string;
+    y: number | null;
+    value: number | null;
+    color: string;
+    meta: TPointMeta;
+}
+export interface ChartProps<TChartMeta = unknown, TSeriesMeta = unknown> {
+    options: ChartOptions<TChartMeta, TSeriesMeta>;
+    renderers?: readonly AnySeriesRenderer[];
+    isLoading?: boolean;
+    empty?: ReactNode;
+    loading?: ReactNode;
+    className?: string;
+    containerProps?: HTMLAttributes<HTMLDivElement>;
+    /** Set false to make the legend a plain key again. */
+    toggleSeries?: boolean;
+    /**
+     * Called after a legend click with the visibility it lands on. `pointIndex` is
+     * set when the item stood for a single point, as a pie's items do.
+     */
+    onSeriesToggle?: (seriesIndex: number, visible: boolean, pointIndex?: number) => void;
+    /** Called with the point nearest a click inside the plot; drill-down hangs off this. */
+    onPointClick?: (point: ClickedPoint, event: ReactMouseEvent<SVGSVGElement>) => void;
+}
+export declare function Chart<TChartMeta = unknown, TSeriesMeta = unknown>(props: ChartProps<TChartMeta, TSeriesMeta>): ReactElement;