@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/charts/core/distribution/brush.ts

@@ -0,0 +1,151 @@
+// Framework-free math of the rectangular brush: drag corners to a rectangle in data units, the
+// rectangle to one range filter per axis (and back), and the keyboard moves and resizes.
+
+export interface BrushPoint {
+  x: number;
+  y: number;
+}
+
+/** Normalized rectangle in data units (x0 <= x1, y0 <= y1). An infinite edge means "unbounded". */
+export interface BrushRect {
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+}
+
+export type BrushRange = readonly [number, number];
+
+export interface BrushRanges {
+  x: BrushRange | null;
+  y: BrushRange | null;
+}
+
+export type BrushKey = "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown";
+
+/** Rectangle spanned by two corners, whatever the drag direction. */
+export function rectFromCorners(a: BrushPoint, b: BrushPoint): BrushRect {
+  return {
+    x0: Math.min(a.x, b.x),
+    x1: Math.max(a.x, b.x),
+    y0: Math.min(a.y, b.y),
+    y1: Math.max(a.y, b.y),
+  };
+}
+
+const clamp = (value: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, value));
+
+/** Keeps the rectangle inside the plot domains; an unbounded edge becomes the domain edge. */
+export function clampRect(rect: BrushRect, xDomain: BrushRange, yDomain: BrushRange): BrushRect {
+  const [xLo, xHi] = [Math.min(...xDomain), Math.max(...xDomain)];
+  const [yLo, yHi] = [Math.min(...yDomain), Math.max(...yDomain)];
+  return {
+    x0: clamp(rect.x0, xLo, xHi),
+    x1: clamp(rect.x1, xLo, xHi),
+    y0: clamp(rect.y0, yLo, yHi),
+    y1: clamp(rect.y1, yLo, yHi),
+  };
+}
+
+/** One range filter per axis; an unbounded axis gives `null` and is not filtered. */
+export function rectToRanges(rect: BrushRect): BrushRanges {
+  const bounded = (lo: number, hi: number): BrushRange | null =>
+    Number.isFinite(lo) && Number.isFinite(hi) ? [Math.min(lo, hi), Math.max(lo, hi)] : null;
+  return { x: bounded(rect.x0, rect.x1), y: bounded(rect.y0, rect.y1) };
+}
+
+/** Rectangle of the active range filters; an axis nobody filters stays unbounded. */
+export function rangesToRect(x: BrushRange | null, y: BrushRange | null): BrushRect | null {
+  if (!x && !y) return null;
+  return {
+    x0: x ? Math.min(...x) : Number.NEGATIVE_INFINITY,
+    x1: x ? Math.max(...x) : Number.POSITIVE_INFINITY,
+    y0: y ? Math.min(...y) : Number.NEGATIVE_INFINITY,
+    y1: y ? Math.max(...y) : Number.POSITIVE_INFINITY,
+  };
+}
+
+export function rectContains(rect: BrushRect, x: number, y: number): boolean {
+  return x >= rect.x0 && x <= rect.x1 && y >= rect.y0 && y <= rect.y1;
+}
+
+/** True when the drag moved less than `min` pixels in both axes: it was a click. */
+export function isClick(a: BrushPoint, b: BrushPoint, min = 4): boolean {
+  return Math.abs(a.x - b.x) < min && Math.abs(a.y - b.y) < min;
+}
+
+/** Brush that keyboard users start from: the middle half of both domains. */
+export function defaultBrush(xDomain: BrushRange, yDomain: BrushRange): BrushRect {
+  const middle = (domain: BrushRange): [number, number] => {
+    const lo = Math.min(...domain);
+    const span = Math.max(...domain) - lo;
+    return [lo + span * 0.25, lo + span * 0.75];
+  };
+  const [x0, x1] = middle(xDomain);
+  const [y0, y1] = middle(yDomain);
+  return { x0, x1, y0, y1 };
+}
+
+const STEP = 0.05;
+
+function shift(lo: number, hi: number, delta: number, dLo: number, dHi: number): [number, number] {
+  const size = hi - lo;
+  const start = clamp(lo + delta, dLo, dHi - size);
+  return [start, start + size];
+}
+
+function resize(lo: number, hi: number, delta: number, min: number, dHi: number): [number, number] {
+  return [lo, clamp(hi + delta, Math.min(dHi, lo + min), dHi)];
+}
+
+/**
+ * Keyboard step. Arrows move the rectangle by 5 % of the domain; with `grow` they resize it instead
+ * (right and up make it larger, left and down smaller). It never leaves the domains and never
+ * collapses below one step.
+ */
+export function stepBrush(
+  rect: BrushRect,
+  key: BrushKey,
+  grow: boolean,
+  xDomain: BrushRange,
+  yDomain: BrushRange,
+  fraction = STEP,
+): BrushRect {
+  const [xLo, xHi] = [Math.min(...xDomain), Math.max(...xDomain)];
+  const [yLo, yHi] = [Math.min(...yDomain), Math.max(...yDomain)];
+  const dx = (xHi - xLo) * fraction;
+  const dy = (yHi - yLo) * fraction;
+  const horizontal = key === "ArrowLeft" || key === "ArrowRight";
+  const sign = key === "ArrowRight" || key === "ArrowUp" ? 1 : -1;
+  if (horizontal) {
+    const [x0, x1] = grow
+      ? resize(rect.x0, rect.x1, sign * dx, dx, xHi)
+      : shift(rect.x0, rect.x1, sign * dx, xLo, xHi);
+    return { ...rect, x0, x1 };
+  }
+  const [y0, y1] = grow
+    ? resize(rect.y0, rect.y1, sign * dy, dy, yHi)
+    : shift(rect.y0, rect.y1, sign * dy, yLo, yHi);
+  return { ...rect, y0, y1 };
+}
+
+export const TOUCH_BRUSH_DELAY = 350;
+const TOUCH_SLOP = 10;
+
+export type TouchIntent = "wait" | "brush" | "scroll";
+
+/**
+ * What a touch that went down at `from` means once it is at `to` after `elapsed` ms. Moving more than
+ * a few pixels before the long-press delay is a scroll (the brush never starts); holding still past
+ * the delay arms the brush, and from then on every move is part of it.
+ */
+export function touchIntent(
+  from: BrushPoint,
+  to: BrushPoint,
+  elapsed: number,
+  delay = TOUCH_BRUSH_DELAY,
+  slop = TOUCH_SLOP,
+): TouchIntent {
+  if (elapsed >= delay) return "brush";
+  return Math.hypot(to.x - from.x, to.y - from.y) > slop ? "scroll" : "wait";
+}

package/src/charts/core/distribution/dot-stack.ts

@@ -0,0 +1,78 @@
+export interface DotPosition {
+  /** Pixels from the left edge of the lane to the dot centre. */
+  x: number;
+  /** Pixels above the baseline to the dot centre. */
+  y: number;
+}
+
+export interface DotStack {
+  radius: number;
+  dots: DotPosition[];
+}
+
+export interface DotStackInput {
+  /** Observations in the bin. */
+  count: number;
+  /** Lane width in pixels. */
+  width: number;
+  /** Height in pixels the stack should fit (the bar it replaces). */
+  height: number;
+}
+
+export interface DotStackOptions {
+  maxRadius?: number;
+  minRadius?: number;
+  /** Space between neighbours in pixels (default 1). */
+  gap?: number;
+}
+
+const grid = (count: number, width: number, radius: number, gap: number) => {
+  const cell = radius * 2 + gap;
+  const columns = Math.max(1, Math.floor(width / cell));
+  return { cell, columns, rows: Math.ceil(count / columns) };
+};
+
+/** Largest radius at which `count` dots fit a `width` x `height` box, or the minimum radius. */
+export function fitRadius(input: DotStackInput, options: DotStackOptions = {}): number {
+  const { maxRadius = 6, minRadius = 1.5, gap = 1 } = options;
+  if (input.count <= 0) return maxRadius;
+  for (let r = maxRadius; r > minRadius; r -= 0.25) {
+    const { cell, rows } = grid(input.count, input.width, r, gap);
+    if (rows * cell <= input.height) return r;
+  }
+  return minRadius;
+}
+
+/**
+ * Dot-plot stack for one bin: dots fill rows from the baseline up, each row
+ * centred in the lane. A row never exceeds the lane width.
+ */
+export function packDots(count: number, width: number, radius: number, gap = 1): DotPosition[] {
+  const { cell, columns } = grid(count, width, radius, gap);
+  const out: DotPosition[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const row = Math.floor(index / columns);
+    const inRow = Math.min(columns, count - row * columns);
+    const column = index - row * columns;
+    out.push({
+      x: width / 2 + (column - (inRow - 1) / 2) * cell,
+      y: radius + row * cell,
+    });
+  }
+  return out;
+}
+
+/**
+ * Stacks for every bin with one shared radius (the smallest that makes the
+ * fullest bin fit), so all the dots of a histogram look alike.
+ */
+export function explodeBins(
+  bins: readonly DotStackInput[],
+  options: DotStackOptions = {},
+): { radius: number; stacks: DotPosition[][] } {
+  const gap = options.gap ?? 1;
+  let radius = options.maxRadius ?? 6;
+  for (const bin of bins)
+    radius = Math.min(radius, fitRadius(bin, { ...options, maxRadius: radius }));
+  return { radius, stacks: bins.map((bin) => packDots(bin.count, bin.width, radius, gap)) };
+}

package/src/charts/core/distribution/explorer.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { type KeyboardEvent, type PointerEvent, useRef } from "react";
+import { cn } from "../../../utils/cn.js";
+import type { PlotMargin } from "./layout.js";
+
+export interface PlotExplorerProps {
+  /** Number of explorable items (boxes, bins, points), in reading order. */
+  count: number;
+  active: number | null;
+  onActiveChange: (index: number | null) => void;
+  /** Item under a plot-relative pixel, or null. */
+  pick: (x: number, y: number) => number | null;
+  /** Accessible name, e.g. `labels.explore`. */
+  label: string;
+  /** What a screen reader announces for the active item. */
+  valueText: string;
+  margin: PlotMargin;
+  width: number;
+  height: number;
+  className?: string;
+}
+
+/**
+ * Transparent overlay that owns pointer and keyboard exploration of a plot:
+ * a focusable `role="slider"` (arrows move, Home/End jump, Escape clears),
+ * the same contract as the cartesian charts.
+ */
+export function PlotExplorer({
+  count,
+  active,
+  onActiveChange,
+  pick,
+  label,
+  valueText,
+  margin,
+  width,
+  height,
+  className,
+}: PlotExplorerProps) {
+  // Fast key repeats can arrive before the next render: read the latest index from a ref.
+  const latest = useRef(active);
+  latest.current = active;
+  const change = (index: number | null) => {
+    latest.current = index;
+    onActiveChange(index);
+  };
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (count === 0) return;
+    const last = count - 1;
+    const current = latest.current ?? -1;
+    let next: number;
+    if (event.key === "ArrowRight" || event.key === "ArrowDown") next = Math.min(last, current + 1);
+    else if (event.key === "ArrowLeft" || event.key === "ArrowUp") next = Math.max(0, current - 1);
+    else if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = last;
+    else if (event.key === "PageDown") next = Math.min(last, current + 10);
+    else if (event.key === "PageUp") next = Math.max(0, current - 10);
+    else if (event.key === "Escape") {
+      change(null);
+      return;
+    } else return;
+    event.preventDefault();
+    change(next);
+  };
+
+  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    change(pick(event.clientX - rect.left, event.clientY - rect.top));
+  };
+
+  return (
+    <div
+      role="slider"
+      tabIndex={count > 0 ? 0 : -1}
+      aria-label={label}
+      aria-valuemin={1}
+      aria-valuemax={Math.max(1, count)}
+      aria-valuenow={(active ?? 0) + 1}
+      aria-valuetext={valueText}
+      onKeyDown={onKeyDown}
+      onFocus={() => {
+        if (latest.current == null && count > 0) change(0);
+      }}
+      onBlur={() => change(null)}
+      onPointerMove={onPointerMove}
+      onPointerDown={onPointerMove}
+      onPointerLeave={() => change(null)}
+      className={cn(
+        "absolute cursor-default rounded-xs outline-none focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-4",
+        className,
+      )}
+      style={{ left: margin.left, top: margin.top, width, height }}
+    />
+  );
+}

package/src/charts/core/distribution/geometry.ts

@@ -0,0 +1,76 @@
+import type { ValueFormat } from "../format.js";
+import type { DensityPoint } from "./stats.js";
+
+/**
+ * Samples per category for one series: `data[i]` holds the raw values of
+ * `categories[i]` (e.g. every service duration of one barber).
+ */
+export interface DistributionSeries {
+  id: string;
+  name: string;
+  data: ReadonlyArray<ReadonlyArray<number | null>>;
+  /** CSS color; defaults to the palette slot of the series. */
+  color?: string;
+  /** Overrides the chart `valueFormat` for this series. */
+  format?: ValueFormat;
+}
+
+const round = (value: number) => Math.round(value * 100) / 100;
+
+/** `[value, cross]` to screen `x,y`, swapping axes for horizontal charts. */
+export function toXY(horizontal: boolean, value: number, cross: number): string {
+  return horizontal ? `${round(value)},${round(cross)}` : `${round(cross)},${round(value)}`;
+}
+
+export type ViolinSide = "both" | "start" | "end";
+
+export interface ViolinPathInput {
+  density: readonly DensityPoint[];
+  /** Value to pixel along the value axis. */
+  map: (value: number) => number;
+  /** Pixel of the violin axis on the cross axis. */
+  center: number;
+  /** Pixel half-width given to `maxDensity`. */
+  halfWidth: number;
+  maxDensity: number;
+  horizontal: boolean;
+  /**
+   * "both" mirrors the curve; "start" draws only the side toward smaller cross
+   * pixels (left, or up when horizontal); "end" only the other side.
+   */
+  side?: ViolinSide;
+  /** Value range to keep (the axis domain): the curve is cut there instead of spilling out. */
+  domain?: readonly [number, number];
+}
+
+/** Closed outline of a (half) violin from a density curve. */
+export function violinPath({
+  density: curve,
+  map,
+  center,
+  halfWidth,
+  maxDensity,
+  horizontal,
+  side = "both",
+  domain,
+}: ViolinPathInput): string {
+  let density = curve;
+  if (domain) {
+    const [lo, hi] = domain[0] <= domain[1] ? domain : [domain[1], domain[0]];
+    density = density.filter((point) => point.value >= lo && point.value <= hi);
+  }
+  if (density.length < 2 || maxDensity <= 0) return "";
+  const at = (point: DensityPoint, sign: number) =>
+    toXY(horizontal, map(point.value), center + sign * (point.density / maxDensity) * halfWidth);
+  const axisAt = (point: DensityPoint) => toXY(horizontal, map(point.value), center);
+  const first = density[0] as DensityPoint;
+  const last = density[density.length - 1] as DensityPoint;
+  let points: string[];
+  if (side === "both") {
+    points = [...density.map((p) => at(p, -1)), ...[...density].reverse().map((p) => at(p, 1))];
+  } else {
+    const sign = side === "start" ? -1 : 1;
+    points = [axisAt(first), ...density.map((p) => at(p, sign)), axisAt(last)];
+  }
+  return `M${points.join("L")}Z`;
+}

package/src/charts/core/distribution/index.ts

@@ -0,0 +1,11 @@
+export * from "./dot-stack.js";
+export * from "./explorer.js";
+export * from "./geometry.js";
+export * from "./labels.js";
+export * from "./layout.js";
+export * from "./marks.js";
+export * from "./observations.js";
+export * from "./points.js";
+export * from "./stats.js";
+export * from "./use-legend.js";
+export * from "./xy-points.js";

package/src/charts/core/distribution/labels.ts

@@ -0,0 +1,56 @@
+import { type ChartLabels, DEFAULT_LABELS } from "../types.js";
+
+/** Statistic names shown in tooltips and data tables. English defaults. */
+export interface StatLabels {
+  count: string;
+  min: string;
+  q1: string;
+  median: string;
+  q3: string;
+  max: string;
+  mean: string;
+  outliers: string;
+  outlier: string;
+  density: string;
+  frequency: string;
+  range: string;
+  trend: string;
+  size: string;
+  value: string;
+  series: string;
+  point: string;
+  /** Toggle that explodes histogram bins into dots. */
+  explode: string;
+  /** Same toggle while exploded: back to bars. */
+  bars: string;
+}
+
+export const DEFAULT_STAT_LABELS: StatLabels = {
+  count: "n",
+  min: "Min",
+  q1: "Q1",
+  median: "Median",
+  q3: "Q3",
+  max: "Max",
+  mean: "Mean",
+  outliers: "Outliers",
+  outlier: "Outlier",
+  density: "Density",
+  frequency: "Count",
+  range: "Range",
+  trend: "Trend",
+  size: "Size",
+  value: "Value",
+  series: "Series",
+  point: "Point",
+  explode: "Show each observation",
+  bars: "Show bars",
+};
+
+export type DistributionLabels = ChartLabels & StatLabels;
+
+export function resolveDistributionLabels(
+  labels?: Partial<DistributionLabels>,
+): DistributionLabels {
+  return { ...DEFAULT_LABELS, ...DEFAULT_STAT_LABELS, ...labels };
+}