@pushwoosh/kit-charts 0.0.1 → 0.0.2

package/ai-documentation.md

@@ -103,6 +103,25 @@ 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.
 
+A label's `align` is horizontal and its `verticalAlign` vertical whichever way
+the decoration runs, as in Highcharts: a line on a y axis takes its label to the
+left edge of the plot (`align: 'left'`, the default there) and sits it on the
+rule (`verticalAlign: 'middle'`). `x`/`y` shift it from there — a negative `x`
+hangs it in the axis gutter.
+
+`label.backgroundColor` draws the label on a pill instead of leaving it as loose
+text, with `borderRadius` and `padding` to tune it. The text takes whichever of
+white and `BRAND_BLACK` reads better on that fill — the greys a threshold is
+painted in carry white at under 3:1 — and `style.color` overrides the choice.
+That is what a threshold needs: a number sitting on a rule has no
+ground of its own to read against. Highcharts has no such option — it takes
+`useHTML` and a styled span, which this library has no equivalent of — so this is
+an addition rather than a divergence: a Highcharts config still renders.
+
+Whether a threshold is breached is the application's decision, not the chart's:
+it passes the colour. Golden cases `area/threshold` and `area/threshold-breached`
+are the same options with one colour changed.
+
 ## Interaction
 
 `onPointClick(point, event)` reports the point nearest a click inside the plot,

package/core/Chart/PlotDecorations.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DEFAULT_FONT_SIZE, textHeight } from '../layout/measure-text';
-import { crisp, PLOT_LABEL_GAP } from '../layout/metrics';
-import { DEFAULT_AXIS_COLOR, DEFAULT_MUTED_TEXT_COLOR, DEFAULT_SURFACE_COLOR } from '../model/palette';
+import { DEFAULT_FONT_SIZE, measureText, textAscent, textHeight } from '../layout/measure-text';
+import { crisp, PLOT_BADGE_PADDING_X, PLOT_BADGE_PADDING_Y, PLOT_BADGE_RADIUS, PLOT_LABEL_GAP } from '../layout/metrics';
+import { DEFAULT_AXIS_COLOR, DEFAULT_MUTED_TEXT_COLOR, DEFAULT_SURFACE_COLOR, textColorOn } from '../model/palette';
 import { ABOVE_SERIES_Z_INDEX } from '../types/options';
 const DASH = {
   solid: undefined,
@@ -28,8 +28,8 @@ function project(scale, value, edge) {
   const at = scale.map(numeric);
   return typeof at === 'number' ? at : null;
 }
-const textProps = style => ({
-  fill: (style === null || style === void 0 ? void 0 : style.color) ?? DEFAULT_MUTED_TEXT_COLOR,
+const textProps = (style, onFill) => ({
+  fill: (style === null || style === void 0 ? void 0 : style.color) ?? (onFill ? textColorOn(onFill) : 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
@@ -39,40 +39,59 @@ const ANCHOR = {
   center: 'middle',
   right: 'end'
 };
+/**
+ * `align` is horizontal and `verticalAlign` vertical whichever way the
+ * decoration runs, as in Highcharts — a horizontal line takes its label to the
+ * left edge of the plot and sits it on the rule.
+ */
 function PlotLabel({
   label,
-  plot,
-  span,
+  box,
   along
 }) {
   if (!(label !== null && label !== void 0 && label.text)) {
     return null;
   }
-  const [low, high] = span[0] <= span[1] ? span : [span[1], span[0]];
   const align = label.align ?? (along === 'x' ? 'center' : 'left');
   const verticalAlign = label.verticalAlign ?? (along === 'x' ? 'top' : 'middle');
-  const acrossLow = along === 'x' ? plot.y : plot.x;
-  const acrossHigh = along === 'x' ? plot.y + plot.height : plot.x + plot.width;
-  const alongAt = {
-    left: low,
-    center: (low + high) / 2,
-    right: high
-  }[align];
-  const acrossAt = {
-    top: acrossLow + PLOT_LABEL_GAP + textHeight(label.style),
-    middle: (acrossLow + acrossHigh) / 2,
-    bottom: acrossHigh - PLOT_LABEL_GAP
-  }[verticalAlign];
-  const x = (along === 'x' ? alongAt : acrossAt) + (label.x ?? 0);
-  const y = (along === 'x' ? acrossAt : alongAt) + (label.y ?? 0);
+  const line = textHeight(label.style);
+  const ascent = textAscent(label.style);
+  const x = {
+    left: box.x + PLOT_LABEL_GAP,
+    center: box.x + box.width / 2,
+    right: box.x + box.width - PLOT_LABEL_GAP
+  }[align] + (label.x ?? 0);
+  const y = {
+    top: box.y + PLOT_LABEL_GAP + ascent,
+    middle: box.y + box.height / 2 + ascent - line / 2,
+    bottom: box.y + box.height - PLOT_LABEL_GAP - (line - ascent)
+  }[verticalAlign] + (label.y ?? 0);
   const rotation = label.rotation ?? 0;
-  return _jsx("text", {
-    x: x,
-    y: y,
-    textAnchor: along === 'x' ? ANCHOR[align] : 'start',
+  const fill = label.backgroundColor;
+  const padX = label.padding ?? PLOT_BADGE_PADDING_X;
+  const padY = label.padding ?? PLOT_BADGE_PADDING_Y;
+  const width = measureText(label.text, label.style) + padX * 2;
+  const height = line + padY * 2;
+  return _jsxs("g", {
     transform: rotation === 0 ? undefined : `rotate(${rotation} ${x} ${y})`,
-    ...textProps(label.style),
-    children: label.text
+    children: [fill && _jsx("rect", {
+      x: {
+        left: x - padX,
+        center: x - width / 2,
+        right: x - width + padX
+      }[align],
+      y: y - ascent - padY,
+      width: width,
+      height: height,
+      rx: label.borderRadius ?? PLOT_BADGE_RADIUS,
+      fill: fill
+    }), _jsx("text", {
+      x: x,
+      y: y,
+      textAnchor: ANCHOR[align],
+      ...textProps(label.style, fill),
+      children: label.text
+    })]
   });
 }
 /**
@@ -124,8 +143,7 @@ export function PlotDecorations({
         strokeWidth: options_.borderWidth ?? 0
       }), _jsx(PlotLabel, {
         label: options_.label,
-        plot: plot,
-        span: [low, high],
+        box: box,
         along: along
       })]
     }, `band-${index}`);
@@ -159,8 +177,17 @@ export function PlotDecorations({
         strokeDasharray: DASH[options_.dashStyle ?? 'solid']
       }), _jsx(PlotLabel, {
         label: options_.label,
-        plot: plot,
-        span: [at, at],
+        box: along === 'x' ? {
+          x: on,
+          y: plot.y,
+          width: 0,
+          height: plot.height
+        } : {
+          x: plot.x,
+          y: on,
+          width: plot.width,
+          height: 0
+        },
         along: along
       })]
     }, `line-${index}`);

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

@@ -6,4 +6,9 @@ export declare const DEFAULT_SUBTITLE_FONT_SIZE: string;
 export declare const toCssFont: (style?: TextStyle) => string;
 export declare function measureText(text: string, style?: TextStyle): number;
 export declare const textHeight: (style?: TextStyle) => number;
+/**
+ * How much of a line box stands above the baseline. Drawing a box around text
+ * needs the split, not just the height: SVG places text by its baseline.
+ */
+export declare const textAscent: (style?: TextStyle) => number;
 export declare function clearTextMeasurementCache(): void;

package/core/layout/measure-text.js

@@ -51,6 +51,11 @@ export function measureText(text, style) {
   return width;
 }
 export const textHeight = style => Math.ceil(parseFontSize(toCssFont(style)) * 1.2);
+/**
+ * How much of a line box stands above the baseline. Drawing a box around text
+ * needs the split, not just the height: SVG places text by its baseline.
+ */
+export const textAscent = style => Math.round(textHeight(style) * 0.8);
 export function clearTextMeasurementCache() {
   cache.clear();
   context = undefined;

package/core/layout/metrics.d.ts

@@ -48,6 +48,13 @@ export declare const TOOLTIP_PADDING = 8;
 export declare const TOOLTIP_RADIUS = 6;
 /** Distance from a plot band or plot line to its own label. */
 export declare const PLOT_LABEL_GAP = 6;
+/**
+ * A plot label drawn on a fill: its padding and corner radius. Wider than it is
+ * tall, because a pill reads as a pill only when the text has room either side.
+ */
+export declare const PLOT_BADGE_PADDING_X = 6;
+export declare const PLOT_BADGE_PADDING_Y = 2;
+export declare const PLOT_BADGE_RADIUS = 4;
 /**
  * Puts a stroke where the device can draw it in one row of pixels: half a stroke
  * either side of the position has to land on a pixel boundary, so an odd stroke

package/core/layout/metrics.js

@@ -48,6 +48,13 @@ export const TOOLTIP_PADDING = 8;
 export const TOOLTIP_RADIUS = 6;
 /** Distance from a plot band or plot line to its own label. */
 export const PLOT_LABEL_GAP = 6;
+/**
+ * A plot label drawn on a fill: its padding and corner radius. Wider than it is
+ * tall, because a pill reads as a pill only when the text has room either side.
+ */
+export const PLOT_BADGE_PADDING_X = 6;
+export const PLOT_BADGE_PADDING_Y = 2;
+export const PLOT_BADGE_RADIUS = 4;
 /**
  * Puts a stroke where the device can draw it in one row of pixels: half a stroke
  * either side of the position has to land on a pixel boundary, so an odd stroke

package/core/model/palette.d.ts

@@ -10,6 +10,14 @@ export declare const DEFAULT_AXIS_COLOR: string;
 export declare const DEFAULT_TEXT_COLOR: string;
 export declare const DEFAULT_MUTED_TEXT_COLOR: string;
 export declare const DEFAULT_SURFACE_COLOR: string;
+/**
+ * Text drawn on a colour the caller chose — a plot label badge, and nothing else
+ * yet. Two neutrals, not one: white on the mid greys a threshold is painted in
+ * reads at 2.8:1, far under the 4.5:1 small text needs.
+ */
+export declare const DEFAULT_ON_FILL_TEXT_COLOR: string;
+/** Whichever of the two neutrals reads better on a fill. */
+export declare function textColorOn(fill: string): string;
 export declare const DEFAULT_TOOLTIP_SURFACE_COLOR: string;
 export declare const DEFAULT_TOOLTIP_TEXT_COLOR: string;
 export declare const colorAt: (colors: readonly string[], index: number) => string;

package/core/model/palette.js

@@ -1,4 +1,5 @@
 import { Color } from '@pushwoosh/kit-constants';
+import { parseColor } from '../scale/color';
 /**
  * Series palette, in the order series are drawn. These are the design system's
  * service and brand colours rather than a set invented here, so a chart matches
@@ -11,6 +12,36 @@ export const DEFAULT_AXIS_COLOR = Color.FORM;
 export const DEFAULT_TEXT_COLOR = Color.MAIN;
 export const DEFAULT_MUTED_TEXT_COLOR = Color.LOCKED;
 export const DEFAULT_SURFACE_COLOR = Color.CLEAR;
+/**
+ * Text drawn on a colour the caller chose — a plot label badge, and nothing else
+ * yet. Two neutrals, not one: white on the mid greys a threshold is painted in
+ * reads at 2.8:1, far under the 4.5:1 small text needs.
+ */
+export const DEFAULT_ON_FILL_TEXT_COLOR = Color.CLEAR;
+const ON_FILL_DARK_TEXT_COLOR = Color.BRAND_BLACK;
+const linearChannel = value => {
+  const unit = value / 255;
+  return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+};
+/** WCAG relative luminance, or null for a colour that cannot be read. */
+const luminance = color => {
+  const rgba = parseColor(color);
+  if (!rgba) {
+    return null;
+  }
+  return 0.2126 * linearChannel(rgba[0]) + 0.7152 * linearChannel(rgba[1]) + 0.0722 * linearChannel(rgba[2]);
+};
+const contrast = (one, other) => (Math.max(one, other) + 0.05) / (Math.min(one, other) + 0.05);
+const LIGHT_TEXT_LUMINANCE = luminance(DEFAULT_ON_FILL_TEXT_COLOR) ?? 1;
+const DARK_TEXT_LUMINANCE = luminance(ON_FILL_DARK_TEXT_COLOR) ?? 0;
+/** Whichever of the two neutrals reads better on a fill. */
+export function textColorOn(fill) {
+  const behind = luminance(fill);
+  if (behind === null) {
+    return DEFAULT_ON_FILL_TEXT_COLOR;
+  }
+  return contrast(behind, LIGHT_TEXT_LUMINANCE) >= contrast(behind, DARK_TEXT_LUMINANCE) ? DEFAULT_ON_FILL_TEXT_COLOR : ON_FILL_DARK_TEXT_COLOR;
+}
 // Chart tooltips follow the product hint style: dark bubble, light text.
 export const DEFAULT_TOOLTIP_SURFACE_COLOR = Color.BRAND_BLACK;
 export const DEFAULT_TOOLTIP_TEXT_COLOR = Color.CLEAR;

package/core/types/options.d.ts

@@ -113,6 +113,10 @@ export interface PlotLabelOptions {
     x?: number;
     y?: number;
     rotation?: number;
+    /** Draws the label on a filled pill, the way a threshold states its value. */
+    backgroundColor?: string;
+    borderRadius?: number;
+    padding?: number;
     style?: TextStyle;
 }
 export interface StackLabelsOptions {

package/package.json

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