@pushwoosh/kit-charts 0.0.11 → 0.0.13

package/ai-documentation.md

@@ -92,6 +92,24 @@ own `formatter` or `format` wins over it.
 the step is chosen from the candidates that stay integral at its magnitude, and
 never falls below 1.
 
+`tickAmount` is Highcharts' demand and not a hint: the y axis stretches the end
+the caller left open until exactly that many ticks fit, so a count of 2 on a
+`tickAmount: 5` axis still draws 0..4 and reads against a stable grid rather than
+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.
+
+`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.
+
+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.
+
 `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.d.ts

@@ -11,6 +11,8 @@ interface XAxisProps {
     axis: AxisModel;
 }
 export declare function XAxis({ plot, axis }: XAxisProps): ReactElement | null;
+/** Drawn after the series: a body sitting on zero would paint over its own axis. */
+export declare function XAxisLine({ plot, axis }: XAxisProps): ReactElement | null;
 interface YAxisProps {
     plot: Rect;
     axis: AxisModel;

package/core/Chart/Axes.js

@@ -1,7 +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_LABEL_DROP, X_AXIS_TITLE_GAP } from '../layout/metrics';
+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 { DEFAULT_AXIS_COLOR, DEFAULT_GRID_COLOR, DEFAULT_MUTED_TEXT_COLOR } from '../model/palette';
 const textProps = style => ({
   fill: style?.color ?? DEFAULT_MUTED_TEXT_COLOR,
@@ -125,16 +126,9 @@ export function XAxis({
   const tickLength = options.tickLength ?? 0;
   const tickWidth = options.tickWidth ?? 1;
   const labelsEnabled = options.labels?.enabled !== false;
-  const labelY = baseline + direction * (tickLength + (onTop ? AXIS_LABEL_GAP : X_AXIS_LABEL_DROP)) + (options.labels?.y ?? 0);
+  const labelY = baseline + direction * xLabelOffset(options, onTop);
   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 => {
+    children: [axis.ticks.map(tick => {
       const content = tickContent(tick);
       return _jsxs("g", {
         children: [tickLength > 0 && tickWidth > 0 ? _jsx("line", {
@@ -162,6 +156,28 @@ export function XAxis({
     })]
   });
 }
+/** Drawn after the series: a body sitting on zero would paint over its own axis. */
+export function XAxisLine({
+  plot,
+  axis
+}) {
+  const {
+    options
+  } = axis;
+  const width = options.lineWidth ?? 1;
+  if (options.visible === false || width === 0) {
+    return null;
+  }
+  const baseline = options.opposite === true ? plot.y - (options.offset ?? 0) : plot.y + plot.height + (options.offset ?? 0);
+  return _jsx("line", {
+    x1: plot.x,
+    x2: plot.x + plot.width,
+    y1: crisp(baseline, width),
+    y2: crisp(baseline, width),
+    stroke: options.lineColor ?? DEFAULT_AXIS_COLOR,
+    strokeWidth: width
+  });
+}
 export function YAxis({
   plot,
   axis

package/core/Chart/Chart.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { Grid, XAxis, YAxis } from './Axes';
+import { Grid, XAxis, XAxisLine, YAxis } from './Axes';
 import { Canvas, Centred, Container, PinnedAxes, ResetZoom, ScrollBox, SeriesLayer, TooltipCell, TooltipDivider, TooltipHeadCell, TooltipName, TooltipRow, TooltipSeriesCell, TooltipSeriesInner, TooltipSwatch, TooltipTable, TooltipTitle, TooltipValue, ZoomBand } from './Chart.styles';
 import { ChartErrorBoundary } from './ChartErrorBoundary';
 import { Legend } from './Legend';
@@ -575,6 +575,9 @@ function ChartBody({
             "aria-hidden": series.hidden,
             children: series.renderer.render(ctx)
           }, `series-${series.index}`) : null;
+        }), model.axisless ? null : _jsx(XAxisLine, {
+          plot: model.plot,
+          axis: model.xAxis
         }), decorations('over'), drag ? _jsx(ZoomBand, {
           x: Math.min(drag.from, drag.to),
           y: model.plot.y,

package/core/layout/metrics.d.ts

@@ -12,6 +12,8 @@ export declare const AXIS_LABEL_GAP = 8;
 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

@@ -12,6 +12,8 @@ export const AXIS_LABEL_GAP = 8;
 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

@@ -58,6 +58,8 @@ export interface ChartModel {
 export declare const hiddenKey: (seriesIndex: number, pointIndex?: number) => string;
 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;
 export interface BuildModelInput {
     options: ChartOptions;
     size: Size;

package/core/model/build-model.js

@@ -3,7 +3,7 @@ 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_TITLE_GAP, MARKER_REACH, VALUE_LABEL_HEADROOM, X_AXIS_LABEL_DROP } from '../layout/metrics';
+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 { nodeText } from '../layout/node-text';
 import { computeSlots } from '../layout/point-width';
 import { layoutTitles } from '../layout/title-layout';
@@ -88,6 +88,27 @@ const grow = (extent, value) => {
   extent.min = Math.min(extent.min, value);
   extent.max = Math.max(extent.max, value);
 };
+/** Axis line to the label baseline; `labels.y` replaces the drop, as in Highcharts. */
+export function xLabelOffset(axis, onTop) {
+  const explicit = axis.labels?.y;
+  if (explicit !== undefined) {
+    return onTop ? -explicit : explicit;
+  }
+  return (axis.tickLength ?? 0) + (onTop ? AXIS_LABEL_GAP : X_AXIS_LABEL_DROP);
+}
+/** Highcharts' air around a series: a share of the range beyond each open end. */
+function axisPadding(axis, domain) {
+  const span = domain.max - domain.min;
+  const low = axis.min === undefined ? axis.minPadding ?? 0 : 0;
+  const high = axis.max === undefined ? axis.maxPadding ?? 0 : 0;
+  if (!Number.isFinite(span) || span <= 0 || low === 0 && high === 0) {
+    return domain;
+  }
+  return {
+    min: domain.min - span * low,
+    max: domain.max + span * high
+  };
+}
 const settled = (extent, fallback) => Number.isFinite(extent.min) && Number.isFinite(extent.max) ? [extent.min, extent.max] : fallback;
 function buildXScale(axis, kind, extent, categories, range, hint) {
   if (kind === 'band') {
@@ -128,7 +149,11 @@ function buildYScale(axis, extent, range, hint, linked) {
   if (linked) {
     return linked;
   }
-  const [min, max] = settled(extent, [0, 1]);
+  const padded = axisPadding(axis, {
+    min: extent.min,
+    max: extent.max
+  });
+  const [min, max] = settled(padded, [0, 1]);
   return createLinearScale({
     domain: [axis.min ?? min, axis.max ?? max],
     range,
@@ -139,6 +164,7 @@ function buildYScale(axis, extent, range, hint, linked) {
       max: axis.max === undefined
     },
     tickHint: hint,
+    tickCount: axis.tickAmount,
     allowDecimals: axis.allowDecimals
   });
 }
@@ -409,10 +435,11 @@ export function buildChartModel({
     renderer
   }) => renderer.scales.x === 'band');
   const pad = bandOnContinuous ? halfStepPadding(resolved) : 0;
-  const xDomain = pad > 0 ? {
+  const padded = pad > 0 ? {
     min: acc.x.min - pad,
     max: acc.x.max + pad
   } : acc.x;
+  const xDomain = xKind === 'band' ? padded : axisPadding(xAxisOptions, padded);
   const yDomains = acc.y;
   const spacing = resolveSpacing(options.chart);
   const [spaceTop, spaceRight, spaceBottom, spaceLeft] = spacing;
@@ -421,8 +448,8 @@ export function buildChartModel({
   // A tick label is drawn a tick's length plus a fixed drop away from the axis
   // line, and `labels.y` pushes it further still. Reserving only its text height
   // leaves it hanging over the chart edge, where the svg clips it.
-  const xLabelPush = labelsOnTop ? Math.max(0, -(xAxisOptions.labels?.y ?? 0)) : Math.max(0, xAxisOptions.labels?.y ?? 0);
-  const xLabelHeight = axisless || xAxisOptions.labels?.enabled === false ? 0 : textHeight(labelStyle) + (xAxisOptions.tickLength ?? 0) + (labelsOnTop ? AXIS_LABEL_GAP : X_AXIS_LABEL_DROP) + xLabelPush;
+  const xLabelDrop = Math.max(0, xLabelOffset(xAxisOptions, labelsOnTop));
+  const xLabelHeight = axisless || xAxisOptions.labels?.enabled === false ? 0 : textHeight(labelStyle) + xLabelDrop;
   const legendEnabled = options.legend?.enabled !== false;
   const legend = legendEnabled ? all.flatMap(({
     renderer,
@@ -486,7 +513,7 @@ export function buildChartModel({
     }), 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 + title;
+    return Math.ceil(widest) + AXIS_GUTTER_PADDING + (axis.labels?.padding ?? AXIS_LABEL_PADDING) + title;
   };
   const gutter = axisless || yAxes[0]?.visible === false ? 0 : measureGutter(32);
   const legendAlign = options.legend?.align ?? 'left';

package/core/scale/linear.d.ts

@@ -9,6 +9,8 @@ export interface LinearScaleOptions {
     range: readonly [number, number];
     nice?: boolean | NiceEnds;
     tickHint?: number;
+    /** Highcharts' `tickAmount`: stretch the open end so exactly this many ticks fit. */
+    tickCount?: number;
     /** False keeps every tick a whole number, as a count axis needs. */
     allowDecimals?: boolean;
 }

package/core/scale/linear.js

@@ -31,18 +31,32 @@ export function createLinearScale(options) {
     range,
     nice = false,
     tickHint = 5,
+    tickCount,
     allowDecimals = true
   } = options;
   let [min, max] = options.domain;
+  const niceMin = nice === true || typeof nice === 'object' && nice.min === true;
+  const niceMax = nice === true || typeof nice === 'object' && nice.max === true;
   if (!Number.isFinite(min) || !Number.isFinite(max)) {
     [min, max] = [0, 1];
   } else if (min === max) {
     const pad = Math.abs(min) || 1;
-    [min, max] = [min - pad, max + pad];
+    // An end the caller pinned stays put: padding both would take a `min: 0`
+    // count axis below zero on a day where every value is zero.
+    [min, max] = [min - (niceMin || !niceMax ? pad : 0), max + (niceMax || !niceMin ? pad : 0)];
   }
-  const niceMin = nice === true || typeof nice === 'object' && nice.min === true;
-  const niceMax = nice === true || typeof nice === 'object' && nice.max === true;
-  if (niceMin || niceMax) {
+  if (tickCount !== undefined && tickCount > 1 && niceMax) {
+    let step = niceStep((max - min) / (tickCount - 1), allowDecimals);
+    if (niceMin) {
+      min = Math.floor(min / step) * step;
+    }
+    // Rounding the low end down lengthens the run, which can leave the last tick
+    // short of the data; widen the step until the fixed number of them covers it.
+    while (min + (tickCount - 1) * step < max) {
+      step = niceStep(step * 1.5, allowDecimals);
+    }
+    max = min + (tickCount - 1) * step;
+  } else if (niceMin || niceMax) {
     const step = niceStep((max - min) / tickHint, allowDecimals);
     if (niceMin) {
       min = Math.floor(min / step) * step;

package/core/types/options.d.ts

@@ -88,6 +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;
     style?: TextStyle;
 }
 /** `zIndex` at or above this draws over the series instead of under it. */
@@ -132,6 +134,9 @@ export interface AxisOptions {
     categories?: readonly string[];
     min?: number;
     max?: number;
+    /** Share of the data range added beyond each end, Highcharts' axis padding. */
+    minPadding?: number;
+    maxPadding?: number;
     visible?: boolean;
     opposite?: boolean;
     reversed?: boolean;

package/package.json

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