@jarenjs/charts 0.34.0

package/src/core/domain.js

@@ -0,0 +1,123 @@
+//@ts-check
+/**
+ * @file Domain-stability policies for the streaming chart types. A
+ * unit-space AST stores every position as a fraction of its domain, so
+ * a tick that moves the domain legitimately changes every mark — a
+ * wholesale re-render is then correct. These policies exist so that
+ * most streaming ticks do NOT move the domain, which is what makes
+ * incremental re-render (the chart session) possible:
+ *
+ * - `x: { window, slide? }` — sliding x window of fixed span `window`,
+ *   whose END is quantized to multiples of `slide` (default a quarter
+ *   window). The domain therefore moves once per `slide` of x
+ *   progress, not once per sample; samples older than the window are
+ *   dropped from the plot.
+ * - `y: { min?, max? }` — pinned value bounds; samples beyond them
+ *   clamp to the plot edge (the render's clamp01 already does this).
+ * - `y: 'step'` — hysteresis by quantization: the value domain snaps
+ *   outward to nice-number multiples (decades under a log axis), so it
+ *   changes only when a sample crosses a step boundary.
+ *
+ * All resolution is pure — policies are declared in the config and
+ * resolved from the data extremes on every build; stability comes from
+ * quantization, not hidden state.
+ */
+
+import { niceStep } from './axis.js';
+
+/**
+ * @typedef {object} DomainPolicy
+ * @property {number|null} window sliding x span (null = none)
+ * @property {number|null} slide window end quantum (null = window/4)
+ * @property {{min: number|null, max: number|null}|null} pin pinned y bounds
+ * @property {boolean} step quantized y domain
+ */
+
+/**
+ * Normalize a config `domain` member into a policy object; hostile or
+ * absent input yields the all-null policy (today's behavior).
+ * @param {any} domain the config `domain` member
+ * @returns {DomainPolicy}
+ */
+export function normalizeDomainPolicy(domain) {
+  const none = { window: null, slide: null, pin: null, step: false };
+  if (domain === null || typeof domain !== 'object') return none;
+  const policy = { ...none };
+  const x = domain.x;
+  if (x !== null && typeof x === 'object'
+    && typeof x.window === 'number' && Number.isFinite(x.window) && x.window > 0) {
+    policy.window = x.window;
+    if (typeof x.slide === 'number' && Number.isFinite(x.slide) && x.slide > 0)
+      policy.slide = x.slide;
+  }
+  const y = domain.y;
+  if (y === 'step') {
+    policy.step = true;
+  }
+  else if (y !== null && typeof y === 'object') {
+    const min = typeof y.min === 'number' && Number.isFinite(y.min) ? y.min : null;
+    const max = typeof y.max === 'number' && Number.isFinite(y.max) ? y.max : null;
+    if (min !== null || max !== null) policy.pin = { min, max };
+  }
+  return policy;
+}
+
+/**
+ * Resolve the windowed x domain `[end - window, end]`: the end is the
+ * smallest multiple of the slide quantum at or above the newest sample,
+ * so it moves once per quantum, not once per sample.
+ * @param {number} xMax newest x in the data (non-finite = empty data)
+ * @param {number} window the window span (> 0)
+ * @param {number|null} slide the end quantum (null = window / 4)
+ * @returns {[number, number]}
+ */
+export function resolveWindowX(xMax, window, slide) {
+  const quantum = slide ?? window / 4;
+  const end = Number.isFinite(xMax) ? quantum * Math.ceil(xMax / quantum) : window;
+  return [end - window, end];
+}
+
+/**
+ * Resolve the quantized (`'step'`) y domain: extremes snapped outward
+ * to multiples of a nice step of the span, so small new extremes
+ * usually land inside the current domain.
+ * @param {number} yMin @param {number} yMax data extremes (finite)
+ * @returns {[number, number]}
+ */
+export function resolveStepY(yMin, yMax) {
+  const span = yMax - yMin;
+  const step = niceStep(span > 0 ? span : Math.abs(yMax) || 1, 4);
+  let lo = step * Math.floor(yMin / step);
+  let hi = step * Math.ceil(yMax / step);
+  if (hi === lo) hi = lo + step;
+  return [lo, hi];
+}
+
+/**
+ * Resolve the quantized y domain under a log axis: decade bounds
+ * (`10^floor` / `10^ceil`), the log counterpart of {@link resolveStepY}.
+ * @param {number} yMin @param {number} yMax data extremes (> 0)
+ * @returns {[number, number]}
+ */
+export function resolveStepYLog(yMin, yMax) {
+  const lo = Math.pow(10, Math.floor(Math.log10(yMin)));
+  let hi = Math.pow(10, Math.ceil(Math.log10(yMax)));
+  if (hi === lo) hi = lo * 10;
+  return [lo, hi];
+}
+
+/**
+ * Resolve pinned y bounds over the data extremes. Under a log axis a
+ * non-positive pin is ignored (a hostile pin never breaks the scale);
+ * a pin pair that closes the domain falls back to the data extremes.
+ * @param {number} yMin @param {number} yMax data extremes
+ * @param {{min: number|null, max: number|null}} pin
+ * @param {boolean} log
+ * @returns {[number, number]}
+ */
+export function resolvePinnedY(yMin, yMax, pin, log) {
+  let lo = pin.min !== null && (!log || pin.min > 0) ? pin.min : yMin;
+  let hi = pin.max !== null && (!log || pin.max > 0) ? pin.max : yMax;
+  if (hi <= lo) { lo = yMin; hi = yMax; }
+  return [lo, hi];
+}

package/src/core/marks.js

@@ -0,0 +1,110 @@
+//@ts-check
+/**
+ * @file Value marks — the two things every value-carrying mark carries.
+ *
+ * 1. A `<title>` child holding the mark's hover text. Native SSR-safe
+ *    hover: it works in a static `toSvgString()` document with no
+ *    script, no CSS and no app, which is why it is unconditional.
+ * 2. Opt-in pointer **bindings** (`on`, VIEW-FORMAT §4) for a host that
+ *    wants a positioned floating tooltip instead. Bindings are plain
+ *    JSON built at render time, so the engine stays pure — it names an
+ *    action, it never calls one — and `renderToString` drops `on`
+ *    entirely, so the SSR bytes are the same either way.
+ *
+ * The binding's `with` payload is the mark descriptor: its `text` (the
+ * same string the `<title>` carries, so a host needs nothing else to
+ * draw a box) plus whatever identifies the mark for a richer host.
+ */
+
+/**
+ * @typedef {object} ChartTooltipSpec
+ * @property {string} action action dispatched when the pointer enters a mark
+ * @property {string} [leaveAction] action dispatched when it leaves
+ * @property {string} [enter] enter event name (default `'pointerenter'`)
+ * @property {string} [leave] leave event name (default `'pointerleave'`)
+ * @property {string[]} [event] `$event` fields to request (default
+ *  `['clientX', 'clientY']` — what a floating box needs to position itself)
+ */
+/**
+ * @typedef {object} ChartTooltip resolved spec
+ * @property {string} action
+ * @property {string|null} leaveAction
+ * @property {string} enter @property {string} leave
+ * @property {string[]} event
+ */
+
+/** The pointer coordinates a floating tooltip positions itself from. */
+const POINTER_FIELDS = ['clientX', 'clientY'];
+
+/**
+ * Resolve a tooltip spec. Anything that does not name an action
+ * resolves to `null` — bindings off, `<title>` hover only — so a
+ * hostile or half-written spec degrades to the static rendering rather
+ * than emitting a binding no action answers.
+ * @param {ChartTooltipSpec|null|undefined|any} spec
+ * @returns {ChartTooltip|null}
+ */
+export function normalizeTooltip(spec) {
+  if (spec === null || typeof spec !== 'object') return null;
+  if (typeof spec.action !== 'string' || spec.action === '') return null;
+  const name = (v, fallback) => typeof v === 'string' && v !== '' ? v : fallback;
+  return {
+    action: spec.action,
+    leaveAction: name(spec.leaveAction, null),
+    enter: name(spec.enter, 'pointerenter'),
+    leave: name(spec.leave, 'pointerleave'),
+    event: Array.isArray(spec.event)
+      ? spec.event.filter((f) => typeof f === 'string')
+      : POINTER_FIELDS,
+  };
+}
+
+/**
+ * The `on` binding object for one mark, or `undefined` when tooltips
+ * are off (so callers can keep passing their props object through
+ * untouched — an unbound chart allocates nothing extra).
+ * @param {ChartTooltip|null} tooltip
+ * @param {string} text the mark's hover text
+ * @param {Record<string, any>} [descriptor] extra `with` members
+ * @returns {Record<string, any>|undefined}
+ */
+export function markBinding(tooltip, text, descriptor) {
+  if (tooltip === null) return undefined;
+  const on = {
+    [tooltip.enter]: {
+      action: tooltip.action,
+      with: descriptor === undefined ? { text } : { text, ...descriptor },
+      event: tooltip.event,
+    },
+  };
+  if (tooltip.leaveAction !== null) on[tooltip.leave] = { action: tooltip.leaveAction };
+  return on;
+}
+
+/**
+ * Mark props with the tooltip bindings folded in — for a mark whose
+ * `<title>` sits among other children (a series or candle `<g>`).
+ * @param {Record<string, any>} props
+ * @param {ChartTooltip|null} tooltip
+ * @param {string} text
+ * @param {Record<string, any>} [descriptor]
+ * @returns {Record<string, any>}
+ */
+export function markProps(props, tooltip, text, descriptor) {
+  const on = markBinding(tooltip, text, descriptor);
+  return on === undefined ? props : { ...props, on };
+}
+
+/**
+ * A leaf value mark: its element, its hover `<title>`, and the tooltip
+ * bindings when a host asked for them.
+ * @param {string} tag
+ * @param {Record<string, any>} props
+ * @param {ChartTooltip|null} tooltip
+ * @param {string} text hover text
+ * @param {Record<string, any>} [descriptor] extra `with` members
+ * @returns {any} the mark vnode
+ */
+export function valueMark(tag, props, tooltip, text, descriptor) {
+  return [tag, markProps(props, tooltip, text, descriptor), ['title', {}, text]];
+}

package/src/core/palette.js

@@ -0,0 +1,126 @@
+//@ts-check
+/**
+ * @file Colors: the categorical palette and the theme token tables.
+ *
+ * The categorical palette is a concrete constant, not a set of theme
+ * tokens (docs/DESIGN.md §8), in the suite's anchor order — blue first,
+ * amber second, teal third, then green/red/navy/olive/slate — with no
+ * pink and no purple anywhere. It is the same palette the mermaid pie
+ * used before it delegated here, so a pie renders byte-identically
+ * through either package.
+ *
+ * The semantic tokens (text/grid/axis, the win/loss pair) resolve
+ * through the shared `resolveTheme` kernel with the `chart` prefix; the
+ * `'host'` theme links them to the site token vocabulary (docs/DESIGN.md §2,
+ * §7) so charts follow the host's light/dark flip live with no
+ * re-render. Sync invariant: the `default`/`dark` values below must
+ * match the `--chart-*` fallbacks in `styles/charts.css`.
+ */
+
+import { resolveTheme } from '@jarenjs/view/helpers';
+import { inkFor, lerpColor } from '@jarenjs/core/color';
+
+// Re-exported: chart modules have always imported it from here.
+export { inkFor };
+import { clamp01 } from '@jarenjs/core/math';
+
+/**
+ * The categorical series palette (docs/DESIGN.md §8 anchor order).
+ * @type {readonly string[]}
+ */
+export const CATEGORICAL = ['#2563eb', '#f59e0b', '#0d9488', '#dc2626', '#16a34a', '#0369a1', '#ca8a04', '#64748b', '#93c5fd', '#78350f'];
+
+/**
+ * Ordinal color assignment: series `i` gets the `i`-th palette entry,
+ * wrapping.
+ * @param {number} i - Series index
+ * @param {readonly string[]} [palette] - Palette to draw from
+ * @returns {string}
+ */
+export function seriesColor(i, palette = CATEGORICAL) {
+  return palette[i % palette.length];
+}
+
+/**
+ * The sequential magnitude ramp: one hue (the brand blue family),
+ * light→dark, for value-carrying fills (heatmap cells). A concrete
+ * constant like {@link CATEGORICAL}, not a theme token. The stops keep
+ * monotone perceptual lightness with visible step gaps, and both ends
+ * stay legible against the light and the dark site surface (the ramp
+ * does not flip with the theme).
+ * @type {readonly string[]}
+ */
+export const SEQUENTIAL = ['#60a5fa', '#3b82f6', '#2563eb', '#1e40af'];
+
+/**
+ * Continuous color for a normalized magnitude: `t` in [0,1] maps onto
+ * the ramp by piecewise-linear interpolation between its stops
+ * (clamped; non-finite `t` reads as 0).
+ * @param {number} t - Normalized magnitude (0 = low, 1 = high)
+ * @param {readonly string[]} [ramp] - Ramp stops, light→dark
+ * @returns {string} a `#rrggbb` color
+ */
+export function sequentialColor(t, ramp = SEQUENTIAL) {
+  // The finite guard is this ramp's own policy: a NaN magnitude reads as the
+  // low end rather than propagating, which `clamp01` deliberately does not do.
+  t = Number.isFinite(t) ? clamp01(t) : 0;
+  const spans = ramp.length - 1;
+  if (spans <= 0) return ramp[0];
+  const at = t * spans;
+  const i = Math.min(spans - 1, Math.floor(at));
+  return lerpColor(ramp[i], ramp[i + 1], at - i);
+}
+
+/** @type {Record<string, Record<string, string>>} */
+const THEMES = {
+  default: {
+    background: 'transparent',
+    text: '#1f2020',
+    muted: '#64748b',
+    grid: '#e2e8f0',
+    axis: '#94a3b8',
+    win: '#16a34a',
+    loss: '#dc2626',
+    sliceStroke: '#ffffff',
+    fontFamily: 'Inter, "Helvetica Neue", Arial, sans-serif',
+  },
+  dark: {
+    background: 'transparent',
+    text: '#f4f4f4',
+    muted: '#94a3b8',
+    grid: '#334155',
+    axis: '#64748b',
+    win: '#4ade80',
+    loss: '#f87171',
+    sliceStroke: '#11141c',
+    fontFamily: 'Inter, "Helvetica Neue", Arial, sans-serif',
+  },
+};
+
+/**
+ * Host custom-property links for the `'host'` theme: token key → the
+ * site token it follows (docs/DESIGN.md §2). Concrete defaults remain as
+ * `var()` fallbacks, so the same SVG stays standalone-valid.
+ * @type {Record<string, string>}
+ */
+export const HOST_VARS = {
+  text: '--fg',
+  muted: '--muted',
+  grid: '--border',
+  axis: '--muted',
+  win: '--ok',
+  loss: '--fail',
+  sliceStroke: '--bg',
+};
+
+/**
+ * Resolve a chart theme. The name `'host'` resolves the default tokens
+ * linked to the host token vocabulary via {@link HOST_VARS}.
+ * @param {string | Record<string, any>} [nameOrOverrides]
+ * @returns {{ name: string, tokens: Record<string, string>, cssVars: Record<string, string> }}
+ */
+export function createTheme(nameOrOverrides = 'default') {
+  return resolveTheme(THEMES, 'chart', nameOrOverrides, HOST_VARS);
+}
+
+export { THEMES };

package/src/core/scale.js

@@ -0,0 +1,106 @@
+//@ts-check
+/**
+ * @file Scales: pure `domain -> (value) => [0,1]` closures. All pixel
+ * mapping happens in the render pass; the AST and these scales stay in
+ * abstract unit space (the geometry-free contract). Construction may
+ * allocate (lookup maps); the returned functions never do.
+ *
+ * Out-of-domain inputs map outside [0,1] (linear/log/time) or to `NaN`
+ * (unknown ordinal/band categories); `polylinePath` and `num` in
+ * `@jarenjs/view/helpers` are the render-side guards that keep a NaN
+ * from ever reaching an emitted string.
+ */
+
+/**
+ * @typedef {(value: number) => number} UnitScale
+ */
+
+/**
+ * Linear scale. A zero-span domain maps every value to 0.5.
+ * @param {number} min - Domain minimum
+ * @param {number} max - Domain maximum
+ * @returns {UnitScale}
+ */
+export function scaleLinear(min, max) {
+  const span = max - min;
+  if (span === 0)
+    return () => 0.5;
+  return (v) => (v - min) / span;
+}
+
+/**
+ * Logarithmic scale (base 10). The domain must be strictly positive —
+ * that is checked once here, not per call; a non-positive *value* maps
+ * to NaN (log of a non-positive number), which the render guards drop.
+ * @param {number} min - Domain minimum (> 0)
+ * @param {number} max - Domain maximum (> 0)
+ * @returns {UnitScale}
+ */
+export function scaleLog(min, max) {
+  if (!(min > 0) || !(max > 0))
+    throw new RangeError(`scaleLog domain must be positive, got [${min}, ${max}]`);
+  const logMin = Math.log10(min);
+  const span = Math.log10(max) - logMin;
+  if (span === 0)
+    return () => 0.5;
+  return (v) => (Math.log10(v) - logMin) / span;
+}
+
+/**
+ * Ordinal scale: each category maps to the center of its equal slot,
+ * `(i + 0.5) / n`. Unknown categories map to NaN.
+ * @param {readonly string[]} categories - Domain, in display order
+ * @returns {(category: string) => number}
+ */
+export function scaleOrdinal(categories) {
+  const n = categories.length;
+  const index = new Map();
+  for (let i = 0; i < n; ++i)
+    index.set(categories[i], i);
+  return (category) => {
+    const i = index.get(category);
+    return i === undefined ? NaN : (i + 0.5) / n;
+  };
+}
+
+/**
+ * Band scale: each category owns an equal band with inner padding. The
+ * returned function gives the band's start; `bandwidth` and `step` are
+ * exposed as properties. Unknown categories map to NaN.
+ * @param {readonly string[]} categories - Domain, in display order
+ * @param {number} [padding] - Fraction of each step left empty (0..1)
+ * @returns {((category: string) => number) & {bandwidth: number, step: number}}
+ */
+export function scaleBand(categories, padding = 0.2) {
+  const n = categories.length;
+  const step = n === 0 ? 1 : 1 / n;
+  const bandwidth = step * (1 - padding);
+  const inset = (step - bandwidth) / 2;
+  const index = new Map();
+  for (let i = 0; i < n; ++i)
+    index.set(categories[i], i);
+  const scale = (category) => {
+    const i = index.get(category);
+    return i === undefined ? NaN : i * step + inset;
+  };
+  scale.bandwidth = bandwidth;
+  scale.step = step;
+  return scale;
+}
+
+/**
+ * Time scale: a linear scale over epoch milliseconds that also accepts
+ * `Date` instances (converted once per call via `getTime`, no
+ * allocation).
+ * @param {number|Date} min - Domain minimum
+ * @param {number|Date} max - Domain maximum
+ * @returns {(value: number|Date) => number}
+ */
+export function scaleTime(min, max) {
+  const t0 = typeof min === 'number' ? min : min.getTime();
+  const t1 = typeof max === 'number' ? max : max.getTime();
+  const span = t1 - t0;
+  if (span === 0)
+    return () => 0.5;
+  return (v) => ((typeof v === 'number' ? v : v.getTime()) - t0) / span;
+}