@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/core/distribution/marks.js

@@ -0,0 +1,269 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { memo } from "react";
+import { AxisBottom, AxisLeft, GridLines } from "../axes.js";
+import { ChartDataTable } from "../data-table.js";
+const TITLE = "fill-ink-3 font-bold text-[10.5px]";
+const CategoryAxes = memo(function CategoryAxes2({
+  layout,
+  title,
+  grid = true
+}) {
+  const { horizontal, innerWidth, innerHeight, valueTicks, categoryTicks } = layout;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    grid ? /* @__PURE__ */ jsx(
+      GridLines,
+      {
+        ticks: valueTicks,
+        direction: horizontal ? "vertical" : "horizontal",
+        length: horizontal ? innerHeight : innerWidth
+      }
+    ) : null,
+    horizontal ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("g", { transform: "translate(0,0)", children: categoryTicks.map((tick) => /* @__PURE__ */ jsx(
+        "text",
+        {
+          x: -12,
+          y: tick.position,
+          dy: "0.34em",
+          textAnchor: "end",
+          className: "fill-ink-2 font-semibold text-[12px]",
+          children: tick.label
+        },
+        tick.key
+      )) }),
+      /* @__PURE__ */ jsx(AxisBottom, { ticks: valueTicks, offset: innerHeight }),
+      title ? /* @__PURE__ */ jsx("text", { x: innerWidth, y: -10, textAnchor: "end", className: TITLE, children: title }) : null
+    ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(AxisLeft, { ticks: valueTicks, offset: 0, title }),
+      /* @__PURE__ */ jsx(AxisBottom, { ticks: categoryTicks, offset: innerHeight })
+    ] }),
+    /* @__PURE__ */ jsx(
+      "line",
+      {
+        x1: 0,
+        x2: horizontal ? 0 : innerWidth,
+        y1: horizontal ? 0 : innerHeight,
+        y2: innerHeight,
+        shapeRendering: "crispEdges",
+        style: { stroke: "var(--line-strong)" }
+      }
+    )
+  ] });
+});
+const XYAxes = memo(function XYAxes2({
+  layout,
+  xTitle,
+  yTitle,
+  grid = true
+}) {
+  const { innerWidth, innerHeight, xTicks, yTicks } = layout;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    grid ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(GridLines, { ticks: yTicks, direction: "horizontal", length: innerWidth }),
+      /* @__PURE__ */ jsx("g", { opacity: 0.6, children: /* @__PURE__ */ jsx(GridLines, { ticks: xTicks, direction: "vertical", length: innerHeight }) })
+    ] }) : null,
+    /* @__PURE__ */ jsx(
+      "line",
+      {
+        x1: 0,
+        x2: innerWidth,
+        y1: innerHeight,
+        y2: innerHeight,
+        shapeRendering: "crispEdges",
+        style: { stroke: "var(--line-strong)" }
+      }
+    ),
+    /* @__PURE__ */ jsx(AxisLeft, { ticks: yTicks, offset: 0, title: yTitle }),
+    /* @__PURE__ */ jsx(AxisBottom, { ticks: xTicks, offset: innerHeight }),
+    xTitle ? /* @__PURE__ */ jsx("text", { x: innerWidth, y: innerHeight + 40, textAnchor: "end", className: TITLE, children: xTitle }) : null
+  ] });
+});
+const BoxGlyph = memo(function BoxGlyph2({
+  stats,
+  map,
+  center,
+  size,
+  horizontal,
+  color,
+  variant = "box",
+  showMean = true,
+  showOutliers = true,
+  activeOutlier,
+  dimmed,
+  active
+}) {
+  const inner = variant === "inner";
+  const half = size / 2;
+  const q1 = map(stats.q1);
+  const q3 = map(stats.q3);
+  const lo = map(stats.lowerWhisker);
+  const hi = map(stats.upperWhisker);
+  const median = map(stats.median);
+  const start = Math.min(q1, q3);
+  const length = Math.max(1, Math.abs(q3 - q1));
+  const cap = inner ? 0 : Math.min(half * 0.55, 14);
+  const line = (v0, c0, v1, c1) => horizontal ? { x1: v0, y1: c0, x2: v1, y2: c1 } : { x1: c0, y1: v0, x2: c1, y2: v1 };
+  const ink = inner ? "var(--ink-2)" : color;
+  const mean = map(stats.mean);
+  const diamond = inner ? 0 : Math.max(3.5, Math.min(5, half * 0.3));
+  return /* @__PURE__ */ jsxs(
+    "g",
+    {
+      className: "transition-opacity duration-150",
+      style: { opacity: dimmed ? 0.3 : 1 },
+      "data-box": "",
+      children: [
+        /* @__PURE__ */ jsx(
+          "line",
+          {
+            ...line(lo, center, start, center),
+            strokeWidth: inner ? 1.5 : 1.5,
+            style: { stroke: ink }
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "line",
+          {
+            ...line(start + length, center, hi, center),
+            strokeWidth: 1.5,
+            style: { stroke: ink }
+          }
+        ),
+        cap > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(
+            "line",
+            {
+              ...line(lo, center - cap, lo, center + cap),
+              strokeWidth: 1.5,
+              strokeLinecap: "round",
+              style: { stroke: ink }
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "line",
+            {
+              ...line(hi, center - cap, hi, center + cap),
+              strokeWidth: 1.5,
+              strokeLinecap: "round",
+              style: { stroke: ink }
+            }
+          )
+        ] }) : null,
+        /* @__PURE__ */ jsx(
+          "rect",
+          {
+            x: horizontal ? start : center - half,
+            y: horizontal ? center - half : start,
+            width: horizontal ? length : size,
+            height: horizontal ? size : length,
+            rx: inner ? Math.min(2, half) : Math.min(6, half / 2),
+            strokeWidth: inner ? 0 : active ? 2.25 : 1.5,
+            style: inner ? { fill: "var(--ink-2)" } : { fill: color, fillOpacity: active ? 0.3 : 0.18, stroke: color }
+          }
+        ),
+        inner ? /* @__PURE__ */ jsx(
+          "circle",
+          {
+            cx: horizontal ? median : center,
+            cy: horizontal ? center : median,
+            r: Math.max(2, Math.min(3.2, half * 0.9)),
+            style: { fill: "var(--surface)" }
+          }
+        ) : /* @__PURE__ */ jsx(
+          "line",
+          {
+            ...line(median, center - half, median, center + half),
+            strokeWidth: 2.5,
+            strokeLinecap: "round",
+            style: { stroke: color }
+          }
+        ),
+        showMean && diamond > 0 ? /* @__PURE__ */ jsx(
+          "path",
+          {
+            d: horizontal ? `M${mean},${center - diamond}L${mean + diamond},${center}L${mean},${center + diamond}L${mean - diamond},${center}Z` : `M${center},${mean - diamond}L${center + diamond},${mean}L${center},${mean + diamond}L${center - diamond},${mean}Z`,
+            strokeWidth: 1.5,
+            style: { fill: "var(--surface)", stroke: color }
+          }
+        ) : null,
+        showOutliers ? stats.outliers.map((value, index) => {
+          const at = map(value);
+          const highlighted = activeOutlier === value;
+          return /* @__PURE__ */ jsx(
+            "circle",
+            {
+              cx: horizontal ? at : center,
+              cy: horizontal ? center : at,
+              r: highlighted ? 4.5 : 3.25,
+              strokeWidth: 1.5,
+              style: {
+                fill: highlighted ? color : "var(--surface)",
+                stroke: inner ? "var(--ink-2)" : color
+              }
+            },
+            index
+          );
+        }) : null
+      ]
+    }
+  );
+});
+function boxTooltipRows(stats, labels, format, color, showMean = true) {
+  const row = (id, name, value, emphasis = false) => ({
+    id,
+    name,
+    value,
+    color,
+    shape: "square",
+    emphasis
+  });
+  const rows = [
+    row("max", labels.max, format(stats.max)),
+    row("q3", labels.q3, format(stats.q3)),
+    row("median", labels.median, format(stats.median)),
+    row("q1", labels.q1, format(stats.q1)),
+    row("min", labels.min, format(stats.min))
+  ];
+  if (showMean) rows.push(row("mean", labels.mean, format(stats.mean)));
+  rows.push(row("count", labels.count, String(stats.count), true));
+  if (stats.outliers.length) {
+    rows.push(row("outliers", labels.outliers, String(stats.outliers.length)));
+  }
+  return rows;
+}
+function boxValueText(name, stats, labels, format) {
+  return `${name}: ${labels.median} ${format(stats.median)}, ${labels.q1} ${format(stats.q1)}, ${labels.q3} ${format(
+    stats.q3
+  )}, ${labels.min} ${format(stats.min)}, ${labels.max} ${format(stats.max)}, ${labels.mean} ${format(
+    stats.mean
+  )}, ${labels.count} ${stats.count}${stats.outliers.length ? `, ${labels.outliers} ${stats.outliers.length}` : ""}`;
+}
+function BoxStatsTable({ caption, labels, rows }) {
+  const keys = ["count", "min", "q1", "median", "q3", "max", "mean", "outliers"];
+  return /* @__PURE__ */ jsx(
+    ChartDataTable,
+    {
+      caption,
+      categoryHeader: labels.category,
+      categories: rows.map((row) => row.name),
+      columns: keys.map((key) => ({
+        id: key,
+        name: labels[key],
+        values: rows.map(({ stats, format }) => {
+          if (!stats) return "";
+          if (key === "count") return String(stats.count);
+          if (key === "outliers") return stats.outliers.map(format).join(", ");
+          return format(stats[key]);
+        })
+      }))
+    }
+  );
+}
+export {
+  BoxGlyph,
+  BoxStatsTable,
+  CategoryAxes,
+  XYAxes,
+  boxTooltipRows,
+  boxValueText
+};

package/dist/charts/core/distribution/observations.d.ts

@@ -0,0 +1,19 @@
+export interface ObservationDotsProps {
+    points: ReadonlyArray<{
+        value: number;
+        offset: number;
+    }>;
+    /** Value to pixel along the value axis. */
+    map: (value: number) => number;
+    /** Pixel of the group axis on the cross axis. */
+    center: number;
+    horizontal: boolean;
+    color: string;
+    /** "value" grades the fill from a pale tint of `color` to `color` across `range`. */
+    coloring?: "series" | "value";
+    range?: readonly [number, number];
+    radius?: number;
+    dimmed?: boolean;
+}
+/** Raw observations of a box or violin as small dots (jitter already applied). */
+export declare const ObservationDots: import("react").NamedExoticComponent<ObservationDotsProps>;

package/dist/charts/core/distribution/observations.js

@@ -0,0 +1,46 @@
+import { jsx } from "react/jsx-runtime";
+import { memo } from "react";
+import { sequentialColor } from "../color-scale.js";
+const ObservationDots = memo(function ObservationDots2({
+  points,
+  map,
+  center,
+  horizontal,
+  color,
+  coloring = "series",
+  range,
+  radius = 2.6,
+  dimmed
+}) {
+  const graded = coloring === "value" && range != null;
+  return /* @__PURE__ */ jsx(
+    "g",
+    {
+      "data-observations": "",
+      className: "pointer-events-none transition-opacity duration-150",
+      style: { opacity: dimmed ? 0.2 : 1 },
+      children: points.map((point, index) => {
+        const at = map(point.value);
+        const fill = graded ? sequentialColor(point.value, range, { mid: "var(--surface)", high: color }).color : color;
+        return /* @__PURE__ */ jsx(
+          "circle",
+          {
+            cx: horizontal ? at : center + point.offset,
+            cy: horizontal ? center + point.offset : at,
+            r: radius,
+            strokeWidth: graded ? 0.75 : 0.5,
+            style: {
+              fill,
+              fillOpacity: graded ? 0.95 : 0.6,
+              stroke: graded ? color : "var(--surface)"
+            }
+          },
+          index
+        );
+      })
+    }
+  );
+});
+export {
+  ObservationDots
+};

package/dist/charts/core/distribution/point-index.d.ts

@@ -0,0 +1,20 @@
+export interface IndexedPoint {
+    x: number;
+    y: number;
+    /** Mark radius in pixels (0 for plain points). */
+    r?: number;
+}
+export interface PointIndex {
+    /**
+     * Index of the mark closest to `(x, y)` within `radius` pixels of its edge
+     * (a pointer inside a mark counts as distance 0), or null. Ties go to the
+     * smaller mark, so a small bubble inside a big one stays reachable.
+     */
+    nearest(x: number, y: number, radius?: number): number | null;
+}
+/**
+ * Uniform-grid spatial index for high-density scatter plots. Building is
+ * O(n), a lookup only visits the few buckets around the pointer, so hit
+ * testing 50 000 points costs microseconds instead of a full scan.
+ */
+export declare function createPointIndex(points: ReadonlyArray<IndexedPoint | null>, cellSize?: number): PointIndex;

package/dist/charts/core/distribution/point-index.js

@@ -0,0 +1,47 @@
+function createPointIndex(points, cellSize = 24) {
+  const cell = Math.max(4, cellSize);
+  const buckets = /* @__PURE__ */ new Map();
+  let maxRadius = 0;
+  const key = (cx, cy) => cx * 73856093 + cy * 19349663;
+  points.forEach((point, index) => {
+    if (!point || !Number.isFinite(point.x) || !Number.isFinite(point.y)) return;
+    maxRadius = Math.max(maxRadius, point.r ?? 0);
+    const id = key(Math.floor(point.x / cell), Math.floor(point.y / cell));
+    const bucket = buckets.get(id);
+    if (bucket) bucket.push(index);
+    else buckets.set(id, [index]);
+  });
+  return {
+    nearest(x, y, radius = 16) {
+      const reach = radius + maxRadius;
+      const x0 = Math.floor((x - reach) / cell);
+      const x1 = Math.floor((x + reach) / cell);
+      const y0 = Math.floor((y - reach) / cell);
+      const y1 = Math.floor((y + reach) / cell);
+      let best = null;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      let bestRadius = Number.POSITIVE_INFINITY;
+      for (let cx = x0; cx <= x1; cx += 1) {
+        for (let cy = y0; cy <= y1; cy += 1) {
+          const bucket = buckets.get(key(cx, cy));
+          if (!bucket) continue;
+          for (const index of bucket) {
+            const point = points[index];
+            const r = point.r ?? 0;
+            const distance = Math.max(0, Math.hypot(point.x - x, point.y - y) - r);
+            if (distance > radius) continue;
+            if (distance < bestDistance || distance === bestDistance && r < bestRadius) {
+              best = index;
+              bestDistance = distance;
+              bestRadius = r;
+            }
+          }
+        }
+      }
+      return best;
+    }
+  };
+}
+export {
+  createPointIndex
+};

package/dist/charts/core/distribution/points.d.ts

@@ -0,0 +1,15 @@
+export type PointColoring = "series" | "value";
+export interface JitteredValue {
+    value: number;
+    /** Signed pixel offset from the category axis. */
+    offset: number;
+}
+/**
+ * Deterministic jitter for raw observations. `reach(value)` is the largest
+ * absolute offset in pixels at that value (a violin passes its density
+ * profile, a box a constant), so the dots follow the shape they sit in.
+ * Non-finite values are dropped. The same seed always yields the same layout.
+ */
+export declare function jitterValues(values: Iterable<number | null | undefined>, seed: number, reach: number | ((value: number) => number)): JitteredValue[];
+/** Seed of one box or violin, so every group gets its own stable jitter. */
+export declare function groupSeed(seed: number, category: number, series: number): number;

package/dist/charts/core/distribution/points.js

@@ -0,0 +1,18 @@
+import { seededRandom } from "./stats.js";
+function jitterValues(values, seed, reach) {
+  const random = seededRandom(seed);
+  const out = [];
+  for (const value of values) {
+    if (value == null || !Number.isFinite(value)) continue;
+    const limit = typeof reach === "function" ? reach(value) : reach;
+    out.push({ value, offset: (random() * 2 - 1) * Math.max(0, limit) });
+  }
+  return out;
+}
+function groupSeed(seed, category, series) {
+  return seed + category * 977 + series * 131;
+}
+export {
+  groupSeed,
+  jitterValues
+};

package/dist/charts/core/distribution/stats.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Descriptive statistics for the distribution charts. Pure functions over
+ * plain numbers: non-finite values are ignored everywhere.
+ */
+/** Finite values, sorted ascending (a new array). */
+export declare function sortedFinite(values: Iterable<number | null | undefined>): number[];
+/**
+ * Quantile `p` (0-1) of an ascending array, interpolating linearly between the
+ * two closest ranks (the "type 7" definition used by most spreadsheets).
+ */
+export declare function quantileSorted(sorted: readonly number[], p: number): number;
+/** Quantile `p` of unsorted values. */
+export declare function quantile(values: Iterable<number | null | undefined>, p: number): number;
+export declare function mean(values: readonly number[]): number;
+/** Sample standard deviation (n - 1 in the denominator); 0 below two values. */
+export declare function standardDeviation(values: readonly number[]): number;
+export interface BoxStats {
+    count: number;
+    min: number;
+    max: number;
+    q1: number;
+    median: number;
+    q3: number;
+    iqr: number;
+    mean: number;
+    /** Most extreme values inside the Tukey fences (`q1 - k·IQR`, `q3 + k·IQR`). */
+    lowerWhisker: number;
+    upperWhisker: number;
+    /** Values outside the fences, ascending. */
+    outliers: number[];
+}
+/**
+ * Five-number summary plus mean and Tukey outliers. `whisker` is the fence
+ * multiplier `k` (1.5 by default); `Infinity` makes the whiskers reach min and max.
+ */
+export declare function boxStats(values: Iterable<number | null | undefined>, whisker?: number): BoxStats | null;
+/** Standard normal density scaled to `mean` and `sd`. */
+export declare function normalPdf(x: number, m?: number, sd?: number): number;
+/**
+ * Silverman's rule of thumb for a Gaussian kernel:
+ * `0.9 · min(sd, IQR / 1.34) · n^(-1/5)`. Falls back to the other spread
+ * measure when one of them is zero, and to 1 for constant data.
+ */
+export declare function silvermanBandwidth(values: Iterable<number | null | undefined>): number;
+export interface DensityPoint {
+    /** Position on the value axis. */
+    value: number;
+    density: number;
+}
+export interface KdeOptions {
+    /** Kernel bandwidth; Silverman's rule by default. */
+    bandwidth?: number;
+    /** Number of evaluation points (default 64). */
+    points?: number;
+    /** Evaluation range; by default the data range widened by `cut` bandwidths. */
+    extent?: readonly [number, number];
+    /** Bandwidths added past the data on each side when `extent` is omitted (default 2). */
+    cut?: number;
+}
+/**
+ * Gaussian kernel density estimate, evaluated on an even grid. The curve
+ * integrates to ~1 over the real line, so it can share an axis with a
+ * histogram drawn as a density.
+ */
+export declare function gaussianKde(values: Iterable<number | null | undefined>, options?: KdeOptions): DensityPoint[];
+/** Sturges' rule: `ceil(log2 n) + 1` bins. */
+export declare function sturgesBinCount(count: number): number;
+/** Freedman–Diaconis bin width: `2 · IQR · n^(-1/3)`; 0 when the IQR is 0. */
+export declare function freedmanDiaconisWidth(values: Iterable<number | null | undefined>): number;
+export type BinRule = "auto" | "sturges" | "freedman-diaconis";
+export interface BinOptions {
+    /** A rule or an approximate bin count. `auto` uses Freedman–Diaconis, or Sturges when the IQR is 0. */
+    bins?: BinRule | number;
+    /** Exact bin width; wins over `bins`. Edges are multiples of it. */
+    binWidth?: number;
+    /** Range to cover; the data range by default. */
+    domain?: readonly [number, number];
+    /** Snap the width to 1, 2 or 5 times a power of ten (default true, ignored with `binWidth`). */
+    nice?: boolean;
+}
+export interface Bin {
+    /** Inclusive lower edge. */
+    x0: number;
+    /** Exclusive upper edge (inclusive for the last bin). */
+    x1: number;
+    count: number;
+}
+export interface BinnedHistogram {
+    bins: Bin[];
+    width: number;
+    /** Values that fell inside the bins. */
+    total: number;
+}
+/** Bin edges for `values`: a width and a start aligned to it. */
+export declare function binEdges(values: Iterable<number | null | undefined>, options?: BinOptions): number[];
+/** Counts `values` into the bins delimited by ascending `edges`. */
+export declare function binCounts(values: Iterable<number | null | undefined>, edges: readonly number[]): Bin[];
+/** Bins `values` with the chosen rule. */
+export declare function histogram(values: Iterable<number | null | undefined>, options?: BinOptions): BinnedHistogram;
+export interface Regression {
+    slope: number;
+    intercept: number;
+    /** Coefficient of determination, 0-1. */
+    r2: number;
+    predict(x: number): number;
+}
+/** Ordinary least squares fit `y = slope · x + intercept`; null below two distinct x. */
+export declare function linearRegression(points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>): Regression | null;
+/** Deterministic pseudo-random numbers in [0, 1) (mulberry32), so jitter is stable across renders. */
+export declare function seededRandom(seed: number): () => number;
+export interface SwarmItem {
+    /** Pixel position along the value axis. */
+    position: number;
+    radius: number;
+}
+export interface SwarmOptions {
+    /** Extra space between circles in pixels (default 1). */
+    gap?: number;
+    /** "both" grows the swarm on both sides of the axis; "positive" only to one side. */
+    side?: "both" | "positive";
+}
+/**
+ * Beeswarm layout: offsets perpendicular to the value axis so that no two
+ * circles overlap. Circles are placed in value order; each one takes the free
+ * offset closest to the axis, tested against the circles already placed that
+ * are close enough along the axis to touch it. Returns one offset per item,
+ * in the input order.
+ */
+export declare function beeswarm(items: readonly SwarmItem[], options?: SwarmOptions): number[];