@pushwoosh/kit-charts 0.0.4 → 0.0.6

package/ai-documentation.md

@@ -339,6 +339,16 @@ 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`, `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
 `onPointClick` reports. `meta` beside it stays the series'. A bar whose height is a
@@ -367,10 +377,22 @@ 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.
 
+`states.hover.color` swaps the fill on hover instead of lightening it, for a body
+too pale for `brightness` to show on; it also wins over a per-point colour, since
+one colour on hover is the point of asking. `column` and `heatmap` read it.
+Golden case: `column/hover-color`.
+
 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.
 
+## Series opacity
+
+`series.opacity` fades a whole series layer — body, border and data labels — where
+`fillOpacity` reaches only the fill a renderer paints. A hover's
+`states.inactive.opacity` overrides it while it lasts. Golden case:
+`column/series-opacity`.
+
 ## Areas
 
 `fillColor` paints the body under the line, where the fill is a token of its own

package/core/Chart/Chart.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+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 { Canvas, Centred, Container, PinnedAxes, ResetZoom, ScrollBox, SeriesLayer, TooltipCell, TooltipDivider, TooltipHeadCell, TooltipName, TooltipRow, TooltipSeriesCell, TooltipSeriesInner, TooltipSwatch, TooltipTable, TooltipTitle, TooltipValue, ZoomBand } from './Chart.styles';
@@ -10,6 +10,7 @@ import { Titles } from './Titles';
 import { Tooltip } from './Tooltip';
 import { useSize } from './useSize';
 import { MOTION_MS } from '../animation/motion';
+import { applyTooltipTemplate } from '../format/template';
 import { formatTime } from '../format/time';
 import { DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE } from '../layout/measure-text';
 import { buildChartModel, hiddenKey, isContinuous } from '../model/build-model';
@@ -32,18 +33,47 @@ const toCssSize = (value, fallback) => {
   }
   return typeof value === 'number' ? `${value}px` : value;
 };
-function defaultTooltip(ctx, formatX, formatValue) {
-  return _jsxs("div", {
-    children: [_jsx(TooltipTitle, {
-      children: formatX(ctx.x)
-    }), ctx.points.map(point => _jsxs(TooltipRow, {
+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, templateContext(ctx.points[0], ctx.x), numberFormat);
+}
+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
-      }), _jsx(TooltipName, {
-        children: point.seriesName
-      }), _jsx(TooltipValue, {
-        children: formatValue(point.value ?? point.y)
-      })]
+      }), 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: pointRow(point, tooltip, formatValue, numberFormat)
     }, `${point.seriesIndex}-${point.index}`))]
   });
 }
@@ -435,8 +465,8 @@ function ChartBody({
       return formatter(ctx);
     }
     const table = options.tooltip?.table;
-    return table ? tableTooltip(ctx, table, formatX) : defaultTooltip(ctx, formatX, formatValue);
-  }, [hover, model, options.title?.text, options.meta, options.tooltip?.formatter, options.tooltip?.table, 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;
   const scrolls = canvas.width > size.width || canvas.height > size.height;
@@ -537,6 +567,7 @@ function ChartBody({
             "$collapse": series.renderer.exit === 'collapse',
             "$selfAnimated": series.renderer.animatesGeometry === true,
             "$inactive": inactiveOpacity(series),
+            "$opacity": series.options.opacity,
             "$motionMs": motionOf(series),
             "$cursor": series.options.cursor ?? 'default',
             "aria-hidden": series.hidden,

package/core/Chart/Chart.styles.d.ts

@@ -33,6 +33,8 @@ export declare const SeriesLayer: import("styled-components").StyledComponent<"g
     $selfAnimated: boolean;
     /** Opacity while another series is hovered, from `states.inactive`. */
     $inactive?: number;
+    /** `series.opacity`: the whole series faded, border and labels included. */
+    $opacity?: number;
     /** `series.animation`; the chart clock unless this series asked for its own. */
     $motionMs: number;
     $cursor: string;

package/core/Chart/Chart.styles.js

@@ -56,12 +56,13 @@ export const SeriesLayer = styled.g.withConfig({
   componentId: "sc-1pit1b9-4"
 })(["opacity:", ";pointer-events:", ";cursor:", ";transition:opacity ", "ms ", ";", " @media (prefers-reduced-motion:reduce){transition:none;path,rect,circle,text{transition:none;}}"], ({
   $hidden,
-  $inactive
+  $inactive,
+  $opacity
 }) => {
   if ($hidden) {
     return 0;
   }
-  return $inactive ?? 1;
+  return $inactive ?? $opacity ?? 1;
 }, ({
   $hidden
 }) => $hidden ? 'none' : 'auto', ({

package/core/format/template.d.ts

@@ -0,0 +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 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, numberFormat?: NumberFormatter): string;

package/core/format/template.js

@@ -0,0 +1,32 @@
+import { formatTime } from './time';
+import { fillTokens } from './tokens';
+const substitute = (name, ctx, numberFormat) => {
+  switch (name) {
+    case 'point.key':
+    case 'point.x':
+      return String(ctx.x);
+    case 'point.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:
+      return undefined;
+  }
+};
+/**
+ * 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, numberFormat = String) {
+  const stripped = format.replace(/<br\s*\/?>/gi, ' ').replace(/<[^>]*>/g, '');
+  return fillTokens(stripped, (name, pattern) => {
+    const value = substitute(name, ctx, numberFormat);
+    if (value === undefined) {
+      return undefined;
+    }
+    const dates = name === 'point.key' || name === 'point.x';
+    return pattern && dates && typeof ctx.x === 'number' ? formatTime(pattern, ctx.x) : value;
+  }).trim();
+}

package/core/format/time.js

@@ -1,3 +1,4 @@
+import { fillTokens } from './tokens';
 const MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const MONTHS_LONG = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
 const DAYS_SHORT = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
@@ -29,10 +30,10 @@ export function formatTime(pattern, timestamp) {
   });
 }
 export function applyValueFormat(format, value) {
-  return format.replace(/\{value(?::([^}]*))?\}/g, (_match, pattern) => {
-    if (pattern && typeof value === 'number') {
-      return formatTime(pattern, value);
+  return fillTokens(format, (name, pattern) => {
+    if (name !== 'value') {
+      return undefined;
     }
-    return String(value);
+    return pattern && typeof value === 'number' ? formatTime(pattern, value) : String(value);
   });
 }

package/core/format/tokens.d.ts

@@ -0,0 +1,3 @@
+export type TokenResolver = (name: string, pattern: string | undefined) => string | undefined;
+/** 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

@@ -0,0 +1,5 @@
+const TOKEN = /\{([a-z][a-z.]*)(?::([^}]*))?\}/gi;
+/** 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?.trim() || undefined) ?? match);
+}

package/core/types/options.d.ts

@@ -205,6 +205,12 @@ export interface TooltipOptions<TChartMeta = unknown, TSeriesMeta = unknown, TPo
     shape?: 'callout' | 'box';
     followPointer?: boolean;
     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;
     valuePrefix?: string;
     valueSuffix?: string;
@@ -255,6 +261,8 @@ export interface SeriesStatesOptions {
         brightness?: number;
         /** Deepens a translucent body on hover, where brightening a pale fill does nothing. */
         fillOpacity?: number;
+        /** The colour to swap to, for a hover that is not a brighter shade of the same one. */
+        color?: string;
     };
     inactive?: {
         opacity?: number;
@@ -300,6 +308,8 @@ export interface SeriesOptionsBase<TSeriesMeta = unknown, TPointMeta = unknown>
     fillOpacity?: number;
     /** The body's own colour, where the fill is not a wash of the series colour. */
     fillColor?: string;
+    /** Fades the whole series — body, border and labels — unlike `fillOpacity`. */
+    opacity?: number;
     pointPadding?: number;
     groupPadding?: number;
     minPointLength?: number;

package/package.json

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

package/series/column/column.js

@@ -2,11 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { pointKey } from '../../core/data/points';
 import { drawable, projectSeries } from '../../core/geometry/path';
 import { TEXT_BASELINE_SHIFT, VALUE_LABEL_GAP } from '../../core/layout/metrics';
-import { brighten } from '../shared/color';
+import { resolveHoverFill } from '../shared/color';
 import { DataLabels } from '../shared/DataLabels';
 import { includeZero } from '../shared/domain';
 import { seriesLegend } from '../shared/legend';
-const DEFAULT_HOVER_BRIGHTNESS = 0.1;
 const SLOT_FALLBACK = {
   width: 10,
   offset: 0
@@ -46,7 +45,7 @@ const fillOf = (ctx, bar, hovered) => {
   if (!hovered) {
     return base;
   }
-  return brighten(base, ctx.series.states?.hover?.brightness ?? DEFAULT_HOVER_BRIGHTNESS);
+  return resolveHoverFill(base, ctx.series.states);
 };
 /**
  * A translucent body under a solid rule is the funnel look: the series keeps its

package/series/heatmap/heatmap.js

@@ -1,9 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { pointKey } from '../../core/data/points';
 import { TEXT_BASELINE_SHIFT, VALUE_LABEL_GAP } from '../../core/layout/metrics';
-import { brighten } from '../shared/color';
+import { resolveHoverFill } from '../shared/color';
 import { DataLabels } from '../shared/DataLabels';
-const DEFAULT_HOVER_BRIGHTNESS = 0.1;
 /** Width of one column: a unit step on the x axis, or the whole plot if there is none. */
 function columnWidth(ctx) {
   const scale = ctx.scales.x;
@@ -79,7 +78,7 @@ const fillOf = (ctx, cell, hovered) => {
   if (!hovered) {
     return base;
   }
-  return brighten(base, ctx.series.states?.hover?.brightness ?? DEFAULT_HOVER_BRIGHTNESS);
+  return resolveHoverFill(base, ctx.series.states);
 };
 const labelX = (ctx, cell) => {
   const padding = ctx.series.dataLabels?.padding ?? VALUE_LABEL_GAP;

package/series/shared/color.d.ts

@@ -1 +1,7 @@
+import { type SeriesStatesOptions } from '../../core/types/options';
 export declare function brighten(color: string, amount: number): string;
+/**
+ * An explicit hover colour wins over brightening, and over a per-point colour:
+ * asking for one colour on hover means one colour, not one per point.
+ */
+export declare function resolveHoverFill(base: string, states: SeriesStatesOptions | undefined): string;

package/series/shared/color.js

@@ -1,3 +1,4 @@
+const DEFAULT_HOVER_BRIGHTNESS = 0.1;
 const clamp = value => Math.min(255, Math.max(0, Math.round(value)));
 const parseHex = color => {
   const match = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
@@ -16,4 +17,12 @@ export function brighten(color, amount) {
   const ratio = Math.abs(amount);
   const [r, g, b] = rgb.map(channel => clamp(channel + (target - channel) * ratio));
   return `#${[r, g, b].map(channel => channel.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * An explicit hover colour wins over brightening, and over a per-point colour:
+ * asking for one colour on hover means one colour, not one per point.
+ */
+export function resolveHoverFill(base, states) {
+  const hover = states?.hover;
+  return hover?.color ?? brighten(base, hover?.brightness ?? DEFAULT_HOVER_BRIGHTNESS);
 }