@pushwoosh/kit-charts 0.0.5 → 0.0.7

package/ai-documentation.md

@@ -94,8 +94,15 @@ 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.
+the label and keeps the tick, and so do we.
+
+An axis or data-label `formatter` may return a `ReactNode` and not just text; the
+axis draws the node and measures the text inside it, so an edge label still turns
+inwards and the y gutter still widens. A node the walk cannot read text out of —
+a bare shape, a component — measures as a point: it is always drawn, and a text
+label too close to it is dropped as it would be beside any other label. Inside an
+axis label the node lands in an SVG `<text>`, so `<tspan>` and strings render and
+an HTML element does not.
 
 ## Plot bands and lines
 
@@ -339,12 +346,15 @@ the value wrapped in `valuePrefix`/`valueSuffix`. `formatter` replaces the body
 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.
 
-`headerFormat` and `pointFormatter` are taken under their Highcharts names, so a
-config that already carries them needs no rewrite: `headerFormat: ''` drops the
-header, a template fills `{point.key}`, `{point.x}`, `{point.y}` and
-`{series.name}` (markup in it is dropped — the chrome is the library's), and
-`pointFormatter` is handed the point and returns a `ReactNode`. `formatter` and
-`table` both outrank them. Golden case: `area/header-format`.
+`headerFormat`, `pointFormat` and `pointFormatter` are taken under their Highcharts
+names, so a config that already carries them needs no rewrite: `headerFormat: ''`
+drops the header and `pointFormat` writes the row after the swatch. Both templates
+fill `{point.key}`, `{point.x}`, `{point.y}`, `{point.value}` and `{series.name}`,
+date an x through `{point.x:%b %d}` (a padded pattern is trimmed) and pass numbers
+through the chart's `numberFormat`; markup in them is dropped, because the chrome
+around a tooltip is the library's. `pointFormatter` is handed the point and returns
+a `ReactNode`, and outranks `pointFormat`; `formatter` and `table` outrank all
+three. Golden cases: `area/header-format`, `line/point-format-template`.
 
 `ctx.points[].pointMeta` is the hovered point's own `meta` — the third type
 parameter of `ChartOptions<TChartMeta, TSeriesMeta, TPointMeta>`, the same object

package/core/Chart/Axes.js

@@ -14,6 +14,13 @@ const ANCHOR = {
   center: 'middle',
   right: 'end'
 };
+/** What a tick draws: its own node if a formatter made one, its text otherwise. */
+const tickContent = tick => {
+  if (tick.node !== undefined && tick.node !== null) {
+    return tick.node;
+  }
+  return tick.label === '' ? null : tick.label;
+};
 /** A tick label, wrapped in its explanation when the axis gave it one. */
 function TickLabel({
   hint,
@@ -125,23 +132,26 @@ export function XAxis({
       y2: crisp(baseline, options.lineWidth ?? 1),
       stroke: lineColor,
       strokeWidth: options.lineWidth ?? 1
-    }), axis.ticks.map(tick => _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.labels?.x ?? 0),
-        y: labelY,
-        anchor: tick.anchor,
-        style: options.labels?.style,
-        children: tick.label
-      }) : null]
-    }, `x-${tick.value}`)), _jsx(AxisTitle, {
+    }), axis.ticks.map(tick => {
+      const content = tickContent(tick);
+      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 && content !== null ? _jsx(TickLabel, {
+          hint: tick.hint,
+          x: tick.position + (options.labels?.x ?? 0),
+          y: labelY,
+          anchor: tick.anchor,
+          style: options.labels?.style,
+          children: content
+        }) : null]
+      }, `x-${tick.value}`);
+    }), _jsx(AxisTitle, {
       title: options.title,
       x: plot.x + plot.width / 2,
       y: labelY + direction * ((options.title?.offset ?? 0) + X_AXIS_TITLE_GAP),
@@ -173,14 +183,17 @@ export function YAxis({
   const titleShift = outwards ? Math.ceil(columnWidth * (anchor === 'middle' ? 0.5 : 1)) + AXIS_TITLE_GAP : 0;
   const titleX = onRight ? edge + titleShift + (options.title?.offset ?? 0) : edge - titleShift - (options.title?.offset ?? 0);
   return _jsxs("g", {
-    children: [labelsEnabled ? axis.ticks.map(tick => tick.label ? _jsx(TickLabel, {
-      x: edge + (options.labels?.x ?? 0),
-      y: tick.position + TEXT_BASELINE_SHIFT,
-      anchor: anchor,
-      hint: tick.hint,
-      style: options.labels?.style,
-      children: tick.label
-    }, `y-${tick.value}`) : null) : null, _jsx(AxisTitle, {
+    children: [labelsEnabled ? axis.ticks.map(tick => {
+      const content = tickContent(tick);
+      return content === null ? null : _jsx(TickLabel, {
+        x: edge + (options.labels?.x ?? 0),
+        y: tick.position + TEXT_BASELINE_SHIFT,
+        anchor: anchor,
+        hint: tick.hint,
+        style: options.labels?.style,
+        children: content
+      }, `y-${tick.value}`);
+    }) : null, _jsx(AxisTitle, {
       title: options.title,
       x: titleX,
       y: titleY(options, plot),

package/core/Chart/Chart.js

@@ -33,32 +33,47 @@ const toCssSize = (value, fallback) => {
   }
   return typeof value === 'number' ? `${value}px` : value;
 };
-function tooltipHeader(ctx, headerFormat, formatX) {
+const templateContext = (point, x) => ({
+  x,
+  y: point?.y ?? null,
+  value: point?.value ?? null,
+  seriesName: point?.seriesName ?? ''
+});
+function tooltipHeader(ctx, headerFormat, formatX, numberFormat) {
   if (headerFormat === undefined) {
     return formatX(ctx.x);
   }
-  return applyTooltipTemplate(headerFormat, {
-    x: ctx.x,
-    y: ctx.points[0]?.y ?? null,
-    seriesName: ctx.points[0]?.seriesName ?? ''
-  });
+  return applyTooltipTemplate(headerFormat, templateContext(ctx.points[0], ctx.x), numberFormat);
 }
-function defaultTooltip(ctx, tooltip, formatX, formatValue) {
-  const header = tooltipHeader(ctx, tooltip?.headerFormat, formatX);
+function pointRow(point, tooltip, formatValue, numberFormat) {
   const pointFormatter = tooltip?.pointFormatter;
+  if (pointFormatter) {
+    return pointFormatter(point);
+  }
+  if (tooltip?.pointFormat !== undefined) {
+    return _jsxs(_Fragment, {
+      children: [_jsx(TooltipSwatch, {
+        "$color": point.color
+      }), applyTooltipTemplate(tooltip.pointFormat, templateContext(point, point.x), numberFormat)]
+    });
+  }
+  return _jsxs(_Fragment, {
+    children: [_jsx(TooltipSwatch, {
+      "$color": point.color
+    }), _jsx(TooltipName, {
+      children: point.seriesName
+    }), _jsx(TooltipValue, {
+      children: formatValue(point.value ?? point.y)
+    })]
+  });
+}
+function defaultTooltip(ctx, tooltip, formatX, formatValue, numberFormat) {
+  const header = tooltipHeader(ctx, tooltip?.headerFormat, formatX, numberFormat);
   return _jsxs("div", {
     children: [header ? _jsx(TooltipTitle, {
       children: header
     }) : null, ctx.points.map(point => _jsx(TooltipRow, {
-      children: pointFormatter ? pointFormatter(point) : _jsxs(_Fragment, {
-        children: [_jsx(TooltipSwatch, {
-          "$color": point.color
-        }), _jsx(TooltipName, {
-          children: point.seriesName
-        }), _jsx(TooltipValue, {
-          children: formatValue(point.value ?? point.y)
-        })]
-      })
+      children: pointRow(point, tooltip, formatValue, numberFormat)
     }, `${point.seriesIndex}-${point.index}`))]
   });
 }
@@ -450,7 +465,7 @@ function ChartBody({
       return formatter(ctx);
     }
     const table = options.tooltip?.table;
-    return table ? tableTooltip(ctx, table, formatX) : defaultTooltip(ctx, options.tooltip, formatX, formatValue);
+    return table ? tableTooltip(ctx, table, formatX) : defaultTooltip(ctx, options.tooltip, formatX, formatValue, model.numberFormat);
   }, [hover, model, options.title?.text, options.meta, options.tooltip, formatX, formatValue]);
   const hasData = model?.series.some(series => series.points.some(point => point.y !== null)) ?? false;
   const plotBorderWidth = options.chart?.plotBorderWidth ?? 0;

package/core/format/template.d.ts

@@ -1,10 +1,12 @@
+import { type NumberFormatter } from '../types/renderer';
 export interface TemplateContext {
     x: number | string;
     y: number | null;
+    value: number | null;
     seriesName: string;
 }
 /**
- * Fills a Highcharts header template. Markup in it is dropped rather than rendered:
- * the chrome around a tooltip is the library's, and a `<span>` in a config is styling.
+ * Fills a Highcharts header or point template. Markup in it is dropped rather than
+ * rendered: the chrome around a tooltip is the library's, and a `<span>` is styling.
  */
-export declare function applyTooltipTemplate(format: string, ctx: TemplateContext): string;
+export declare function applyTooltipTemplate(format: string, ctx: TemplateContext, numberFormat?: NumberFormatter): string;

package/core/format/template.js

@@ -1,12 +1,14 @@
 import { formatTime } from './time';
 import { fillTokens } from './tokens';
-const substitute = (name, ctx) => {
+const substitute = (name, ctx, numberFormat) => {
   switch (name) {
     case 'point.key':
     case 'point.x':
       return String(ctx.x);
     case 'point.y':
-      return ctx.y === null ? '' : String(ctx.y);
+      return ctx.y === null ? '' : numberFormat(ctx.y);
+    case 'point.value':
+      return ctx.value === null ? '' : numberFormat(ctx.value);
     case 'series.name':
       return ctx.seriesName;
     default:
@@ -14,13 +16,13 @@ const substitute = (name, ctx) => {
   }
 };
 /**
- * Fills a Highcharts header template. Markup in it is dropped rather than rendered:
- * the chrome around a tooltip is the library's, and a `<span>` in a config is styling.
+ * Fills a Highcharts header or point template. Markup in it is dropped rather than
+ * rendered: the chrome around a tooltip is the library's, and a `<span>` is styling.
  */
-export function applyTooltipTemplate(format, ctx) {
+export function applyTooltipTemplate(format, ctx, numberFormat = String) {
   const stripped = format.replace(/<br\s*\/?>/gi, ' ').replace(/<[^>]*>/g, '');
   return fillTokens(stripped, (name, pattern) => {
-    const value = substitute(name, ctx);
+    const value = substitute(name, ctx, numberFormat);
     if (value === undefined) {
       return undefined;
     }

package/core/format/tokens.d.ts

@@ -1,3 +1,3 @@
 export type TokenResolver = (name: string, pattern: string | undefined) => string | undefined;
-/** Fills `{name}` and `{name:pattern}` placeholders; an unresolved one is left as it stands. */
+/** Fills `{name}` and `{name:pattern}`; an unresolved token is left as it stands. */
 export declare function fillTokens(format: string, resolve: TokenResolver): string;

package/core/format/tokens.js

@@ -1,5 +1,5 @@
 const TOKEN = /\{([a-z][a-z.]*)(?::([^}]*))?\}/gi;
-/** Fills `{name}` and `{name:pattern}` placeholders; an unresolved one is left as it stands. */
+/** Fills `{name}` and `{name:pattern}`; an unresolved token is left as it stands. */
 export function fillTokens(format, resolve) {
-  return format.replace(TOKEN, (match, name, pattern) => resolve(name, pattern) ?? match);
+  return format.replace(TOKEN, (match, name, pattern) => resolve(name, pattern?.trim() || undefined) ?? match);
 }

package/core/layout/node-text.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from 'react';
+/** The text a node prints, for the layout that has to measure it. */
+export declare function nodeText(node: ReactNode): string;

package/core/layout/node-text.js

@@ -0,0 +1,14 @@
+import { isValidElement } from 'react';
+/** The text a node prints, for the layout that has to measure it. */
+export function nodeText(node) {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(child => nodeText(child)).join('');
+  }
+  if (isValidElement(node)) {
+    return nodeText(node.props.children);
+  }
+  return '';
+}

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

@@ -1,3 +1,4 @@
+import { type ReactNode } from 'react';
 import { type NormalizedPoint } from '../data/points';
 import { type TitleEntry } from '../layout/title-layout';
 import { type Rect, type Size, type SlotGeometry, type Spacing } from '../types/geometry';
@@ -24,6 +25,8 @@ export interface AxisTick {
     value: number | string;
     position: number;
     label: string;
+    /** What the axis draws where a formatter returned something other than text. */
+    node?: ReactNode;
     anchor: TickAnchor;
     /** Sentence this tick explains itself with, opened from the label on hover. */
     hint?: string;

package/core/model/build-model.js

@@ -4,6 +4,7 @@ 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 { nodeText } from '../layout/node-text';
 import { computeSlots } from '../layout/point-width';
 import { layoutTitles } from '../layout/title-layout';
 import { resolveAxes, resolveSeries, isSeriesVisible } from '../options/normalize';
@@ -17,6 +18,10 @@ export const hiddenKey = (seriesIndex, pointIndex) => pointIndex === undefined ?
 const DEFAULT_SPACING = [10, 10, 15, 10];
 const isBand = scale => scale.kind === 'band';
 const isContinuous = scale => scale.kind === 'linear' || scale.kind === 'time';
+const asText = label => ({
+  label,
+  node: undefined
+});
 function tickLabel(value, axis, timePattern, index, count, kind, numberFormat) {
   const formatter = axis.labels?.formatter;
   if (formatter) {
@@ -32,17 +37,20 @@ function tickLabel(value, axis, timePattern, index, count, kind, numberFormat) {
       }
     });
     if (typeof node === 'string' || typeof node === 'number') {
-      return String(node);
+      return asText(String(node));
     }
-    return '';
+    return {
+      label: nodeText(node),
+      node
+    };
   }
   if (axis.labels?.format) {
-    return applyValueFormat(axis.labels.format, value);
+    return asText(applyValueFormat(axis.labels.format, value));
   }
   if (typeof value === 'number') {
-    return timePattern ? formatTime(timePattern, value) : numberFormat(value);
+    return asText(timePattern ? formatTime(timePattern, value) : numberFormat(value));
   }
-  return String(value);
+  return asText(String(value));
 }
 function collectCategories(axis, series, numeric = false) {
   if (axis.categories?.length) {
@@ -177,14 +185,17 @@ function dropOverlapping(ticks, axis, along) {
   // rather than order keeps one rule for both directions.
   let kept = null;
   return ticks.map(tick => {
-    if (!tick.label) {
+    if (!tick.label && tick.node === undefined) {
       return tick;
     }
-    const half = (along === 'x' ? measureText(tick.label, style) : textHeight(style)) / 2;
-    if (kept && Math.abs(tick.position - kept.position) < half + kept.half + AXIS_LABEL_GAP) {
+    // A node with no text to read measures as a point rather than dropping out of
+    // the walk: it is always drawn, so a label after it still has to clear it.
+    const half = tick.label ? (along === 'x' ? measureText(tick.label, style) : textHeight(style)) / 2 : 0;
+    if (tick.label && kept && Math.abs(tick.position - kept.position) < half + kept.half + AXIS_LABEL_GAP) {
       return {
         ...tick,
-        label: ''
+        label: '',
+        node: undefined
       };
     }
     kept = {
@@ -212,11 +223,15 @@ function axisTicks(axis, scale, hint, timePattern, along, numberFormat, bounds)
   const offset = isBand(scale) ? scale.bandwidth() / 2 : 0;
   const built = values.map((value, index) => {
     const position = (isBand(scale) ? scale.map(String(value)) : scale.map(Number(value))) + offset;
-    const label = tickLabel(value, axis, timePattern, index, values.length, scale.kind, numberFormat);
+    const {
+      label,
+      node
+    } = tickLabel(value, axis, timePattern, index, values.length, scale.kind, numberFormat);
     return {
       value,
       position,
       label,
+      node,
       anchor: tickAnchor(label, position, axis, bounds),
       hint: axis.labels?.hint?.({
         value,

package/core/types/options.d.ts

@@ -207,6 +207,8 @@ export interface TooltipOptions<TChartMeta = unknown, TSeriesMeta = unknown, TPo
     formatter?: TooltipFormatter<TChartMeta, TSeriesMeta, TPointMeta>;
     /** Highcharts' header template: `''` drops the header, `{point.key}` and friends fill. */
     headerFormat?: string;
+    /** Highcharts' per-point template, drawn after the swatch; `pointFormatter` wins. */
+    pointFormat?: string;
     /** One row per point, in place of the default swatch, name and value. */
     pointFormatter?: TooltipCellFormatter<TSeriesMeta, TPointMeta>;
     dateFormat?: string;

package/package.json

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