@pushwoosh/kit-charts 0.0.14 → 0.0.16

package/ai-documentation.md

@@ -99,17 +99,33 @@ filling the plot. An end pinned with `max` cannot be stretched, so a tick amount
 alongside one is ignored.
 
 An x axis measures `labels.y` from the axis line itself, as Highcharts does: a
-config that sets it replaces the default drop rather than adding to it. Left
-unset, the label falls the tick's length plus a fixed drop below the line.
+config that sets it replaces the default drop rather than adding to it. Left unset,
+the label falls `labels.distance` below the line.
 
 `minPadding`/`maxPadding` add a share of the data range beyond an end the caller
-left open — Highcharts' axis air, off unless asked for. `labels.padding` is the
-gap Highcharts leaves between the y label column and the plot; it defaults to 5
-and widens the gutter, so a migrated config keeps its left edge.
+left open — Highcharts' axis air. There they default to 0.01 on x and 0.05 on y;
+here they default to 0, because switching them on would move every chart already
+drawn. `labels.distance` is Highcharts' one number for how far a label sits from the
+plot perimeter (15), and both the gutter reserve and the drawn column read it, so
+they cannot drift apart. `labels.x` on a y axis and `labels.y` on an x axis override
+it, exactly as `pick(labels.x, distance)` does there.
 
 The x axis line is drawn after the series, so a bar or an area sitting on zero
 cannot paint over the line it stands on.
 
+A y axis with `labels.enabled: false` reserves no gutter at all — only a rotated
+title still takes room — so the plot starts at `chart.spacing`, where Highcharts
+starts it, rather than a label column in from there.
+
+An end the axis leaves unpadded puts its extreme point on the plot edge, where
+half of the point's marker would fall outside the SVG and be cut. Such an end
+keeps `MARKER_REACH` of room: the plot edge moves in to 5px from the canvas
+unless the gutter, the spacing or `chart.marginLeft`/`marginRight` already leaves
+at least that much, so a chart with `spacing: 0` and no gutter is 5px in rather
+than flush. Only an end that can draw a marker pays it: `marker.enabled: false`
+does not release the room — the hover dot is drawn regardless, as in Highcharts —
+but `marker.states.hover.enabled: false` does, and then no dot is drawn either.
+
 `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.

package/core/Chart/Axes.js

@@ -1,8 +1,8 @@
 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_TITLE_GAP } from '../layout/metrics';
-import { xLabelOffset } from '../model/build-model';
+import { AXIS_TITLE_GAP, crisp, TEXT_BASELINE_SHIFT, X_AXIS_TITLE_GAP } from '../layout/metrics';
+import { xLabelOffset, yLabelGap } from '../model/build-model';
 import { DEFAULT_AXIS_COLOR, DEFAULT_GRID_COLOR, DEFAULT_MUTED_TEXT_COLOR } from '../model/palette';
 const textProps = style => ({
   fill: style?.color ?? DEFAULT_MUTED_TEXT_COLOR,
@@ -140,7 +140,7 @@ export function XAxis({
           strokeWidth: tickWidth
         }) : null, labelsEnabled && content !== null ? _jsx(TickLabel, {
           hint: tick.hint,
-          x: tick.position + (options.labels?.x ?? 0),
+          x: tick.position + tick.shift + (options.labels?.x ?? 0),
           y: labelY,
           anchor: tick.anchor,
           style: options.labels?.style,
@@ -192,7 +192,8 @@ export function YAxis({
   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 gap = yLabelGap(options);
+  const edge = onRight ? plot.x + plot.width + gap + offset : plot.x - gap - offset;
   const anchor = (options.labels?.align && ANCHOR[options.labels.align]) ?? (onRight ? 'start' : 'end');
   const columnWidth = labelsEnabled ? axis.ticks.reduce((widest, tick) => Math.max(widest, measureText(tick.label, options.labels?.style)), 0) : 0;
   // Where the labels grow away from the plot, the title has to clear the whole
@@ -204,7 +205,7 @@ export function YAxis({
     children: [labelsEnabled ? axis.ticks.map(tick => {
       const content = tickContent(tick);
       return content === null ? null : _jsx(TickLabel, {
-        x: edge + (options.labels?.x ?? 0),
+        x: edge,
         y: tick.position + TEXT_BASELINE_SHIFT,
         anchor: anchor,
         hint: tick.hint,

package/core/layout/metrics.d.ts

@@ -8,12 +8,10 @@
 export declare const TEXT_BASELINE_SHIFT = 4;
 /** Tick label to the plot edge, on either axis. */
 export declare const AXIS_LABEL_GAP = 8;
+/** Highcharts' `labels.distance`: label to the plot perimeter, on either axis. */
+export declare const AXIS_LABEL_DISTANCE = 15;
 /** Baseline of an x axis label below the axis line, tick length aside. */
 export declare const X_AXIS_LABEL_DROP = 14;
-/** Air added to the tick label column when measuring the y axis gutter. */
-export declare const AXIS_GUTTER_PADDING = 10;
-/** `labels.padding` when the axis does not set it — the Highcharts default. */
-export declare const AXIS_LABEL_PADDING = 5;
 /** A rotated axis title to the column of tick labels it stands beside. */
 export declare const AXIS_TITLE_GAP = 6;
 /** An x axis title below its labels. */

package/core/layout/metrics.js

@@ -8,12 +8,10 @@
 export const TEXT_BASELINE_SHIFT = 4;
 /** Tick label to the plot edge, on either axis. */
 export const AXIS_LABEL_GAP = 8;
+/** Highcharts' `labels.distance`: label to the plot perimeter, on either axis. */
+export const AXIS_LABEL_DISTANCE = 15;
 /** Baseline of an x axis label below the axis line, tick length aside. */
 export const X_AXIS_LABEL_DROP = 14;
-/** Air added to the tick label column when measuring the y axis gutter. */
-export const AXIS_GUTTER_PADDING = 10;
-/** `labels.padding` when the axis does not set it — the Highcharts default. */
-export const AXIS_LABEL_PADDING = 5;
 /** A rotated axis title to the column of tick labels it stands beside. */
 export const AXIS_TITLE_GAP = 6;
 /** An x axis title below its labels. */

package/core/model/build-model.d.ts

@@ -28,6 +28,8 @@ export interface AxisTick {
     /** What the axis draws where a formatter returned something other than text. */
     node?: ReactNode;
     anchor: TickAnchor;
+    /** Slide along the axis that keeps an end label's box inside the canvas. */
+    shift: number;
     /** Sentence this tick explains itself with, opened from the label on hover. */
     hint?: string;
 }
@@ -60,6 +62,8 @@ declare const isBand: (scale: AnyScale) => scale is BandScale;
 declare const isContinuous: (scale: AnyScale) => scale is ContinuousScale;
 /** Axis line to the label baseline; `labels.y` replaces the drop, as in Highcharts. */
 export declare function xLabelOffset(axis: AxisOptions, onTop: boolean): number;
+/** Plot edge to the y label column: `labels.x` when set, `labels.distance` otherwise. */
+export declare const yLabelGap: (axis: AxisOptions) => number;
 export interface BuildModelInput {
     options: ChartOptions;
     size: Size;

package/core/model/build-model.js

@@ -3,11 +3,11 @@ import { normalizePoints } from '../data/points';
 import { applyValueFormat, formatTime } from '../format/time';
 import { measureLegend } from '../layout/legend-layout';
 import { measureText, textHeight } from '../layout/measure-text';
-import { AXIS_GUTTER_PADDING, AXIS_LABEL_GAP, AXIS_LABEL_PADDING, AXIS_TITLE_GAP, MARKER_REACH, VALUE_LABEL_HEADROOM, X_AXIS_LABEL_DROP } from '../layout/metrics';
+import { AXIS_LABEL_GAP, AXIS_LABEL_DISTANCE, AXIS_TITLE_GAP, MARKER_REACH, VALUE_LABEL_HEADROOM } from '../layout/metrics';
 import { nodeText } from '../layout/node-text';
 import { computeSlots } from '../layout/point-width';
 import { layoutTitles } from '../layout/title-layout';
-import { resolveAxes, resolveSeries, isSeriesVisible } from '../options/normalize';
+import { resolveAxes, resolveSeries, isSeriesVisible, showsHoverMarker, showsMarkers } from '../options/normalize';
 import { createBandScale } from '../scale/band';
 import { createColorScale } from '../scale/color';
 import { createLinearScale } from '../scale/linear';
@@ -94,8 +94,10 @@ export function xLabelOffset(axis, onTop) {
   if (explicit !== undefined) {
     return onTop ? -explicit : explicit;
   }
-  return (axis.tickLength ?? 0) + (onTop ? AXIS_LABEL_GAP : X_AXIS_LABEL_DROP);
+  return onTop ? -(axis.labels?.distance ?? AXIS_LABEL_DISTANCE) : axis.labels?.distance ?? AXIS_LABEL_DISTANCE;
 }
+/** Plot edge to the y label column: `labels.x` when set, `labels.distance` otherwise. */
+export const yLabelGap = axis => axis.labels?.x !== undefined ? Math.abs(axis.labels.x) : axis.labels?.distance ?? AXIS_LABEL_DISTANCE;
 /** Highcharts' air around a series: a share of the range beyond each open end. */
 function axisPadding(axis, domain) {
   const span = domain.max - domain.min;
@@ -185,22 +187,22 @@ const EXPLICIT_ANCHOR = {
   center: 'middle',
   right: 'end'
 };
-function tickAnchor(label, position, axis, bounds) {
-  const explicit = axis.labels?.align && EXPLICIT_ANCHOR[axis.labels.align];
-  if (explicit) {
-    return explicit;
-  }
-  if (!bounds || !label) {
-    return 'middle';
+function tickAnchor(axis) {
+  return axis.labels?.align && EXPLICIT_ANCHOR[axis.labels.align] || 'middle';
+}
+/** Highcharts slides an end label until its box sits inside the canvas, keeping it centred. */
+function tickShift(label, position, axis, bounds) {
+  if (!bounds || !label || axis.labels?.align) {
+    return 0;
   }
   const half = measureText(label, axis.labels?.style) / 2;
   if (position - half < bounds[0]) {
-    return 'start';
+    return bounds[0] - (position - half);
   }
   if (position + half > bounds[1]) {
-    return 'end';
+    return bounds[1] - (position + half);
   }
-  return 'middle';
+  return 0;
 }
 /**
  * Blanks the label of any tick whose text would run into the last one kept.
@@ -263,7 +265,8 @@ function axisTicks(axis, scale, hint, timePattern, along, numberFormat, bounds)
       position,
       label,
       node,
-      anchor: tickAnchor(label, position, axis, bounds),
+      anchor: tickAnchor(axis),
+      shift: along === 'x' ? tickShift(label, position, axis, bounds) : 0,
       hint: axis.labels?.hint?.({
         value,
         index,
@@ -472,7 +475,7 @@ export function buildChartModel({
   const yLabelsShown = !axisless && yAxes[0]?.visible !== false && yAxes[0]?.labels?.enabled !== false;
   const markerReach = resolved.some(({
     options: series
-  }) => series.marker?.enabled !== false) ? MARKER_REACH : 0;
+  }) => showsMarkers(series.marker)) ? MARKER_REACH : 0;
   // The topmost tick label is centred on the plot's top edge, so half of it hangs
   // above the plot: without this the highest grid line and its label sit on the
   // chart border.
@@ -496,10 +499,13 @@ export function buildChartModel({
   })();
   const marginTop = spaceTop + titleHeight + (legendAtTop ? legendHeight : 0) + (labelsOnTop ? xLabelHeight : 0) + Math.max(labelHeadroom, topOverflow);
   const marginBottom = spaceBottom + (labelsOnTop ? 0 : xLabelHeight) + (legendAtTop ? 0 : legendHeight);
-  const measureGutter = estimate => {
+  const measureGutter = () => {
     const axis = yAxes[0] ?? {};
+    const title = axis.title?.text && (axis.title.rotation ?? -90) !== 0 ? textHeight(axis.title.style) + AXIS_TITLE_GAP : 0;
+    // Highcharts measures the label column and nothing else, so an axis without
+    // labels leaves the plot flush with the chart edge rather than indented.
     if (axis.labels?.enabled === false) {
-      return estimate;
+      return title;
     }
     const labels = axis.categories?.length ? [...axis.categories] : axisTicks(axis, createLinearScale({
       domain: (() => {
@@ -512,15 +518,26 @@ export function buildChartModel({
       allowDecimals: axis.allowDecimals
     }), axis.tickAmount ?? 5, undefined, 'y', numberFormat).map(tick => tick.label);
     const widest = labels.reduce((widest_, label) => Math.max(widest_, measureText(label, axis.labels?.style)), 0);
-    const title = axis.title?.text && (axis.title.rotation ?? -90) !== 0 ? textHeight(axis.title.style) + AXIS_TITLE_GAP : 0;
-    return Math.ceil(widest) + AXIS_GUTTER_PADDING + (axis.labels?.padding ?? AXIS_LABEL_PADDING) + title;
+    // Highcharts reserves the widest label plus the distance it is drawn at; the two
+    // must be one number or the plot edge and the label column drift apart.
+    return Math.ceil(widest) + yLabelGap(axis) + title;
   };
-  const gutter = axisless || yAxes[0]?.visible === false ? 0 : measureGutter(32);
+  const gutter = axisless || yAxes[0]?.visible === false ? 0 : measureGutter();
   const legendAlign = options.legend?.align ?? 'left';
   const legendBesideLeft = legendMetrics.beside && legendAlign === 'left';
+  // A point on the plot edge draws half its marker outside the canvas, where the
+  // svg cuts it; an end the axis pads keeps that room already.
+  const edgeMarkers = !axisless && xKind !== 'band' && resolved.some(({
+    renderer,
+    options: series
+  }) => renderer.scales.x !== 'band' && (showsMarkers(series.marker) || showsHoverMarker(series.marker)));
+  const hoverReach = edgeMarkers ? MARKER_REACH : 0;
+  const domainMin = xAxisOptions.min ?? xDomain.min;
+  const domainMax = xAxisOptions.max ?? xDomain.max;
+  const edgeRoom = (margin, flush) => flush ? Math.max(margin, hoverReach) : margin;
   // Highcharts margins replace the computed edge distance rather than adding to it.
-  const left = options.chart?.marginLeft ?? spaceLeft + gutter + (legendBesideLeft ? legendMetrics.width : 0);
-  const right = options.chart?.marginRight ?? spaceRight + (legendMetrics.beside && !legendBesideLeft ? legendMetrics.width : 0);
+  const left = options.chart?.marginLeft ?? edgeRoom(spaceLeft + gutter + (legendBesideLeft ? legendMetrics.width : 0), domainMin === acc.x.min);
+  const right = options.chart?.marginRight ?? edgeRoom(spaceRight + (legendMetrics.beside && !legendBesideLeft ? legendMetrics.width : 0), domainMax === acc.x.max);
   const top = options.chart?.marginTop ?? marginTop;
   const bottom = options.chart?.marginBottom ?? marginBottom;
   const plot = {
@@ -567,9 +584,9 @@ export function buildChartModel({
       options: xAxisOptions,
       scale: xScale,
       ticks: axisTicks(xAxisOptions, xScale, xHint, timePattern, 'x', numberFormat,
-      // Highcharts turns an end label inwards only where it would leave the
-      // canvas, not where it leaves the plot: the gutter is room to hang over.
-      [0, size.width])
+      // Highcharts justifies against the chart spacing box, not the plot: the
+      // gutter is room to hang over, the spacing is not.
+      [Math.min(plot.x, spaceLeft), Math.max(plot.x + plot.width, size.width - spaceRight)])
     },
     yAxes: yAxisModels,
     titles: titles.entries,

package/core/options/normalize.d.ts

@@ -1,4 +1,4 @@
-import { type AxisOptions, type ChartOptions, type SeriesOptionsBase } from '../types/options';
+import { type AxisOptions, type ChartOptions, type MarkerOptions, type SeriesOptionsBase } from '../types/options';
 export declare const toAxisArray: (axis: AxisOptions | readonly AxisOptions[] | undefined) => AxisOptions[];
 export declare function resolveSeries(options: ChartOptions): SeriesOptionsBase[];
 export declare function resolveAxes(options: ChartOptions): {
@@ -6,3 +6,7 @@ export declare function resolveAxes(options: ChartOptions): {
     yAxes: AxisOptions[];
 };
 export declare const isSeriesVisible: (series: SeriesOptionsBase) => boolean;
+/** A marker at every point of the series. */
+export declare const showsMarkers: (marker: MarkerOptions | undefined) => boolean;
+/** The dot under the pointer, which Highcharts draws whatever `marker.enabled` says. */
+export declare const showsHoverMarker: (marker: MarkerOptions | undefined) => boolean;

package/core/options/normalize.js

@@ -40,4 +40,8 @@ export function resolveAxes(options) {
     yAxes: toAxisArray(options.yAxis)
   };
 }
-export const isSeriesVisible = series => series.visible !== false;
+export const isSeriesVisible = series => series.visible !== false;
+/** A marker at every point of the series. */
+export const showsMarkers = marker => marker?.enabled !== false && marker?.symbol !== 'none';
+/** The dot under the pointer, which Highcharts draws whatever `marker.enabled` says. */
+export const showsHoverMarker = marker => marker?.states?.hover?.enabled !== false;

package/core/types/options.d.ts

@@ -88,8 +88,8 @@ export interface AxisLabelsOptions {
     align?: 'left' | 'center' | 'right';
     x?: number;
     y?: number;
-    /** Air between the label column and the plot, as Highcharts reserves it. */
-    padding?: number;
+    /** Label to the plot perimeter, Highcharts' `labels.distance`; `x`/`y` override it. */
+    distance?: number;
     style?: TextStyle;
 }
 /** `zIndex` at or above this draws over the series instead of under it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/kit-charts",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Small React chart library on SVG, with a Highcharts-shaped configuration model",
   "license": "MIT",
   "repository": {

package/series/area/area.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { drawable, projectSeries, toAreaPath, toLinePath } from '../../core/geometry/path';
+import { showsHoverMarker } from '../../core/options/normalize';
 import { includeZero } from '../shared/domain';
 import { nearestByX } from '../shared/hit';
 import { seriesLegend } from '../shared/legend';
@@ -41,7 +42,7 @@ export const area = {
         marker: ctx.series.marker,
         projected: projected,
         color: color
-      }), hovered ? _jsx("circle", {
+      }), hovered && showsHoverMarker(ctx.series.marker) ? _jsx("circle", {
         cx: hovered.px,
         cy: hovered.py,
         r: ctx.series.marker?.states?.hover?.radius ?? 4,

package/series/line/line.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { drawable, projectSeries, toLinePath } from '../../core/geometry/path';
+import { showsHoverMarker } from '../../core/options/normalize';
 import { nearestByX } from '../shared/hit';
 import { seriesLegend } from '../shared/legend';
 import { Markers } from '../shared/Markers';
@@ -33,7 +34,7 @@ export const line = {
         marker: ctx.series.marker,
         projected: projected,
         color: color
-      }), hovered ? _jsx("circle", {
+      }), hovered && showsHoverMarker(ctx.series.marker) ? _jsx("circle", {
         cx: hovered.px,
         cy: hovered.py,
         r: ctx.series.marker?.states?.hover?.radius ?? 4,

package/series/shared/Markers.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { showsMarkers } from '../../core/options/normalize';
 const markerRadius = marker => marker?.radius ?? (marker?.width ? marker.width / 2 : 3);
 export function Markers({
   marker,
   projected,
   color
 }) {
-  if (marker?.enabled === false || marker?.symbol === 'none') {
+  if (!showsMarkers(marker)) {
     return null;
   }
   const radius = markerRadius(marker);