@jcsoftdev/ui 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,281 @@
+import { clean, tickStep } from "../scales/linear.js";
+function sortedFinite(values) {
+  const out = [];
+  for (const value of values) if (value != null && Number.isFinite(value)) out.push(value);
+  return out.sort((a, b) => a - b);
+}
+function quantileSorted(sorted, p) {
+  const n = sorted.length;
+  if (n === 0) return Number.NaN;
+  if (n === 1 || p <= 0) return sorted[0];
+  if (p >= 1) return sorted[n - 1];
+  const rank = (n - 1) * p;
+  const below = Math.floor(rank);
+  const lo = sorted[below];
+  const hi = sorted[below + 1];
+  return lo + (hi - lo) * (rank - below);
+}
+function quantile(values, p) {
+  return quantileSorted(sortedFinite(values), p);
+}
+function mean(values) {
+  if (values.length === 0) return Number.NaN;
+  let sum = 0;
+  for (const value of values) sum += value;
+  return sum / values.length;
+}
+function standardDeviation(values) {
+  const n = values.length;
+  if (n < 2) return 0;
+  const m = mean(values);
+  let squares = 0;
+  for (const value of values) squares += (value - m) ** 2;
+  return Math.sqrt(squares / (n - 1));
+}
+function boxStats(values, whisker = 1.5) {
+  const sorted = sortedFinite(values);
+  const n = sorted.length;
+  if (n === 0) return null;
+  const q1 = quantileSorted(sorted, 0.25);
+  const median = quantileSorted(sorted, 0.5);
+  const q3 = quantileSorted(sorted, 0.75);
+  const iqr = q3 - q1;
+  const lowFence = q1 - whisker * iqr;
+  const highFence = q3 + whisker * iqr;
+  let lowerWhisker = q1;
+  let upperWhisker = q3;
+  const outliers = [];
+  for (const value of sorted) {
+    if (value < lowFence || value > highFence) outliers.push(value);
+    else {
+      if (value < lowerWhisker) lowerWhisker = value;
+      if (value > upperWhisker) upperWhisker = value;
+    }
+  }
+  return {
+    count: n,
+    min: sorted[0],
+    max: sorted[n - 1],
+    q1,
+    median,
+    q3,
+    iqr,
+    mean: mean(sorted),
+    lowerWhisker,
+    upperWhisker,
+    outliers
+  };
+}
+function normalPdf(x, m = 0, sd = 1) {
+  if (sd <= 0) return 0;
+  const z = (x - m) / sd;
+  return Math.exp(-0.5 * z * z) / (sd * Math.sqrt(2 * Math.PI));
+}
+function silvermanBandwidth(values) {
+  const sorted = sortedFinite(values);
+  const n = sorted.length;
+  if (n < 2) return 1;
+  const sd = standardDeviation(sorted);
+  const iqr = (quantileSorted(sorted, 0.75) - quantileSorted(sorted, 0.25)) / 1.34;
+  const spread = sd > 0 && iqr > 0 ? Math.min(sd, iqr) : Math.max(sd, iqr);
+  if (spread <= 0) return Math.abs(sorted[0]) * 0.1 || 1;
+  return 0.9 * spread * n ** -0.2;
+}
+function gaussianKde(values, options = {}) {
+  const sorted = sortedFinite(values);
+  const n = sorted.length;
+  if (n === 0) return [];
+  const h = options.bandwidth && options.bandwidth > 0 ? options.bandwidth : silvermanBandwidth(sorted);
+  const cut = options.cut ?? 2;
+  const [lo, hi] = options.extent ?? [
+    sorted[0] - cut * h,
+    sorted[n - 1] + cut * h
+  ];
+  const count = Math.max(2, Math.round(options.points ?? 64));
+  const step = (hi - lo) / (count - 1);
+  const norm = 1 / (n * h * Math.sqrt(2 * Math.PI));
+  const out = [];
+  for (let i = 0; i < count; i += 1) {
+    const x = lo + i * step;
+    let sum = 0;
+    for (const value of sorted) {
+      const z = (x - value) / h;
+      if (z > -8 && z < 8) sum += Math.exp(-0.5 * z * z);
+    }
+    out.push({ value: x, density: sum * norm });
+  }
+  return out;
+}
+function sturgesBinCount(count) {
+  return count < 2 ? 1 : Math.ceil(Math.log2(count)) + 1;
+}
+function freedmanDiaconisWidth(values) {
+  const sorted = sortedFinite(values);
+  const n = sorted.length;
+  if (n < 2) return 0;
+  const iqr = quantileSorted(sorted, 0.75) - quantileSorted(sorted, 0.25);
+  return 2 * iqr / Math.cbrt(n);
+}
+function binEdges(values, options = {}) {
+  const sorted = sortedFinite(values);
+  if (sorted.length === 0 && !options.domain) return [];
+  const lo = options.domain?.[0] ?? sorted[0];
+  const hi = options.domain?.[1] ?? sorted[sorted.length - 1];
+  let width;
+  if (options.binWidth && options.binWidth > 0) {
+    width = options.binWidth;
+  } else {
+    const rule = options.bins ?? "auto";
+    let count;
+    if (typeof rule === "number") count = Math.max(1, Math.round(rule));
+    else if (rule === "sturges") count = sturgesBinCount(sorted.length);
+    else {
+      const fd = freedmanDiaconisWidth(sorted);
+      count = fd > 0 ? Math.ceil((hi - lo) / fd) : sturgesBinCount(sorted.length);
+    }
+    count = Math.min(200, Math.max(1, count));
+    width = hi > lo ? (hi - lo) / count : 1;
+    if (options.nice !== false && hi > lo) width = tickStep(lo, hi, count);
+  }
+  const start = clean(Math.floor(lo / width) * width);
+  const edges = [start];
+  let edge = start;
+  while (edge < hi || edges.length < 2) {
+    edge = clean(edge + width);
+    edges.push(edge);
+    if (edges.length > 1001) break;
+  }
+  return edges;
+}
+function binCounts(values, edges) {
+  const bins = [];
+  for (let i = 0; i < edges.length - 1; i += 1) {
+    bins.push({ x0: edges[i], x1: edges[i + 1], count: 0 });
+  }
+  if (bins.length === 0) return bins;
+  const first = edges[0];
+  const last = edges[edges.length - 1];
+  for (const value of values) {
+    if (value == null || !Number.isFinite(value) || value < first || value > last) continue;
+    let lo = 0;
+    let hi = bins.length - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (value >= bins[mid].x0) lo = mid;
+      else hi = mid - 1;
+    }
+    bins[lo].count += 1;
+  }
+  return bins;
+}
+function histogram(values, options = {}) {
+  const sorted = sortedFinite(values);
+  const edges = binEdges(sorted, options);
+  const bins = binCounts(sorted, edges);
+  const total = bins.reduce((sum, bin) => sum + bin.count, 0);
+  const width = bins.length ? bins[0].x1 - bins[0].x0 : 0;
+  return { bins, width, total };
+}
+function linearRegression(points) {
+  const finite = points.filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y));
+  const n = finite.length;
+  if (n < 2) return null;
+  let sx = 0;
+  let sy = 0;
+  for (const point of finite) {
+    sx += point.x;
+    sy += point.y;
+  }
+  const mx = sx / n;
+  const my = sy / n;
+  let sxx = 0;
+  let sxy = 0;
+  let syy = 0;
+  for (const point of finite) {
+    sxx += (point.x - mx) ** 2;
+    sxy += (point.x - mx) * (point.y - my);
+    syy += (point.y - my) ** 2;
+  }
+  if (sxx === 0) return null;
+  const slope = sxy / sxx;
+  const intercept = my - slope * mx;
+  const r2 = syy === 0 ? 1 : sxy * sxy / (sxx * syy);
+  return { slope, intercept, r2, predict: (x) => slope * x + intercept };
+}
+function seededRandom(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function beeswarm(items, options = {}) {
+  const gap = options.gap ?? 1;
+  const both = (options.side ?? "both") === "both";
+  const order = items.map((_, index) => index).sort((a, b) => {
+    const pa = items[a].position;
+    const pb = items[b].position;
+    return pa - pb || a - b;
+  });
+  const offsets = new Array(items.length).fill(0);
+  const placed = [];
+  let maxRadius = 0;
+  for (const index of order) {
+    const item = items[index];
+    maxRadius = Math.max(maxRadius, item.radius);
+    const reach = item.radius + maxRadius + gap;
+    const near = [];
+    for (let k = placed.length - 1; k >= 0; k -= 1) {
+      const other = placed[k];
+      if (item.position - items[other].position > reach) break;
+      near.push(other);
+    }
+    const collides = (offset) => near.some((other) => {
+      const o = items[other];
+      const min = item.radius + o.radius + gap;
+      const dx = item.position - o.position;
+      const dy = offset - offsets[other];
+      return dx * dx + dy * dy < min * min - 1e-6;
+    });
+    const candidates = [0];
+    for (const other of near) {
+      const o = items[other];
+      const min = item.radius + o.radius + gap;
+      const dx = item.position - o.position;
+      if (Math.abs(dx) >= min) continue;
+      const dy = Math.sqrt(min * min - dx * dx);
+      const base = offsets[other];
+      candidates.push(base + dy, base - dy);
+    }
+    let best = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+      if (!both && candidate < 0) continue;
+      if (Math.abs(candidate) < Math.abs(best) && !collides(candidate)) best = candidate;
+    }
+    offsets[index] = Number.isFinite(best) ? best : 0;
+    placed.push(index);
+  }
+  return offsets;
+}
+export {
+  beeswarm,
+  binCounts,
+  binEdges,
+  boxStats,
+  freedmanDiaconisWidth,
+  gaussianKde,
+  histogram,
+  linearRegression,
+  mean,
+  normalPdf,
+  quantile,
+  quantileSorted,
+  seededRandom,
+  silvermanBandwidth,
+  sortedFinite,
+  standardDeviation,
+  sturgesBinCount
+};

package/dist/charts/core/distribution/use-legend.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+import { type LegendShape } from "../legend.js";
+export interface LegendSource {
+    id: string;
+    name: string;
+    color?: string;
+}
+export interface ColoredSeries<T extends LegendSource> {
+    /** The original series. */
+    source: T;
+    id: string;
+    name: string;
+    color: string;
+    /** Position in the original list (palette slot). */
+    index: number;
+}
+export interface DistributionLegend<T extends LegendSource> {
+    all: ColoredSeries<T>[];
+    visible: ColoredSeries<T>[];
+    highlighted: string | null;
+    isDimmed: (id: string) => boolean;
+    node: ReactNode;
+    position: "top" | "bottom";
+}
+/**
+ * Colors, legend toggling and highlight for a list of series. The legend shows
+ * by default when there is more than one series; `legend` forces it on/off or
+ * picks its position. A top legend moves below the plot in frames narrower
+ * than `@md` (the chart root must be an `@container`).
+ */
+export declare function useDistributionLegend<T extends LegendSource>(series: readonly T[], legend: boolean | "top" | "bottom" | undefined, shape?: LegendShape): DistributionLegend<T>;

package/dist/charts/core/distribution/use-legend.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { ChartLegend } from "../legend.js";
+import { seriesColor } from "../palette.js";
+import { useSeriesState } from "../use-series-state.js";
+function useDistributionLegend(series, legend, shape = "square") {
+  const state = useSeriesState();
+  const all = series.map((item, index) => ({
+    source: item,
+    id: item.id,
+    name: item.name,
+    color: seriesColor(index, item.color),
+    index
+  }));
+  const visible = all.filter((item) => !state.isHidden(item.id));
+  const show = legend === void 0 ? series.length > 1 : legend !== false;
+  const node = show ? /* @__PURE__ */ jsx(
+    ChartLegend,
+    {
+      items: all.map((item) => ({
+        id: item.id,
+        name: item.name,
+        color: item.color,
+        shape,
+        hidden: state.isHidden(item.id)
+      })),
+      onToggle: series.length > 1 ? state.toggle : void 0,
+      onHighlight: state.setHighlighted,
+      className: legend === "bottom" ? void 0 : "order-last @md:order-none"
+    }
+  ) : null;
+  return {
+    all,
+    visible,
+    highlighted: state.highlighted,
+    isDimmed: state.isDimmed,
+    node,
+    position: legend === "bottom" ? "bottom" : "top"
+  };
+}
+export {
+  useDistributionLegend
+};

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

@@ -0,0 +1,109 @@
+import { type ValueFormat } from "../format.js";
+import { type ChartTone } from "../palette.js";
+import { type BrushRect } from "./brush.js";
+import { type DistributionLabels } from "./labels.js";
+import { type DistributionAxisOptions } from "./layout.js";
+export interface XYPoint {
+    x: number;
+    y: number;
+    /** Bubble size (bubble charts): drives the area of the circle. */
+    size?: number;
+    /** Name in the tooltip, the data table and bubble labels, e.g. a barber. */
+    label?: string;
+    /** Image drawn inside the marker instead of a plain dot (URL or data URI), e.g. an avatar. */
+    image?: string;
+}
+export interface XYSeries {
+    id: string;
+    name: string;
+    points: readonly XYPoint[];
+    color?: string;
+}
+export type QuadrantCorner = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+export interface QuadrantOptions {
+    /** Vertical divider; the mean of the visible x values by default. */
+    x?: number;
+    /** Horizontal divider; the mean of the visible y values by default. */
+    y?: number;
+    /** Corner captions, e.g. "Rápidos y caros". */
+    labels?: Partial<Record<QuadrantCorner, string>>;
+    /** Soft background per corner. */
+    tones?: Partial<Record<QuadrantCorner, ChartTone>>;
+}
+/** Rectangular selection drawn over the plot: drag with the pointer or use the keyboard. */
+export interface XYBrush {
+    /** Applied rectangle in data units (an infinite edge covers the whole axis); `null` for none. */
+    value: BrushRect | null;
+    /** Called with the finished rectangle (drag released, Enter) or `null` (click, Escape). */
+    onChange: (rect: BrushRect | null) => void;
+    /** Accessible name of the keyboard brush, e.g. "Seleccionar un rectángulo". */
+    label: string;
+    /** Text a screen reader announces for a rectangle while it is moved or applied. */
+    describe?: (rect: BrushRect, applied: boolean) => string;
+    /**
+     * Touch only: the finger must rest this many milliseconds before a drag draws the rectangle, so a
+     * swipe still scrolls the page (350 by default). `0` brushes at once and blocks page scroll on the
+     * plot. Mouse and pen drag immediately either way.
+     */
+    touchDelay?: number;
+}
+export interface XYPointChartProps {
+    title: string;
+    series: readonly XYSeries[];
+    xFormat?: ValueFormat;
+    yFormat?: ValueFormat;
+    sizeFormat?: ValueFormat;
+    xAxis?: DistributionAxisOptions;
+    yAxis?: DistributionAxisOptions;
+    /** Least-squares line per series, drawn over its x range. */
+    trendLine?: boolean;
+    quadrants?: QuadrantOptions;
+    /** Point radius when there are no sizes (pixels). */
+    radius?: number;
+    /** Bubble mode: radius from `size`, area-proportional, the largest gets `sizeRange[1]`. */
+    sized?: boolean;
+    sizeRange?: readonly [number, number];
+    /** "time": `x` is epoch milliseconds and the axis shows calendar ticks. */
+    xType?: "linear" | "time";
+    /**
+     * Deterministic displacement in pixels that separates overlapping points
+     * (a number applies to both axes). Tooltips still show the true values.
+     */
+    jitter?: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Seed of the jitter, so points are stable between renders. */
+    seed?: number;
+    /**
+     * "canvas" paints the marks on a canvas for tens of thousands of points;
+     * axes, tooltip and keyboard stay SVG/HTML. Falls back to SVG when points
+     * carry images or `shading` is "shaded".
+     */
+    renderer?: "svg" | "canvas";
+    /** Rectangular brush over the plot (pointer drag plus keyboard). */
+    brush?: XYBrush;
+    /** "shaded" fills bubbles with an off-centre radial gradient so they read as spheres. */
+    shading?: "flat" | "shaded";
+    /** Text labels next to (or inside) the points that have a `label`. */
+    showLabels?: boolean;
+    /** Reference circles explaining the bubble sizes, under the plot. */
+    sizeLegend?: boolean;
+    height?: number | "fill";
+    /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
+    aspectRatio?: number;
+    legend?: boolean | "top" | "bottom";
+    grid?: boolean;
+    tooltip?: boolean;
+    loading?: boolean;
+    animate?: boolean;
+    labels?: Partial<DistributionLabels>;
+    className?: string;
+}
+/** Bubbles shrink in narrow frames (down to 55%) so they keep some separation. */
+export declare function bubbleRadiusScale(width: number): number;
+/**
+ * Shared engine of `ScatterChart` and `BubbleChart`: two continuous axes,
+ * multi-series points, optional bubbles, trend lines and quadrants.
+ */
+export declare function XYPointChart({ title, series, xFormat, yFormat, sizeFormat, xAxis, yAxis, trendLine, quadrants, radius, sized, sizeRange, showLabels, sizeLegend, xType, jitter, seed, renderer, brush, shading, height, aspectRatio, legend, grid, tooltip, loading, animate, labels: labelsProp, className, }: XYPointChartProps): import("react").JSX.Element;