@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/dist/charts/bar-chart/drilldown-bar-chart.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo } from "react";
+import { cn } from "../../utils/cn.js";
+import { ChartBreadcrumb } from "../core/breadcrumb.js";
+import { seriesColor } from "../core/palette.js";
+import { useDrill } from "../core/use-drill.js";
+import { BarChart } from "./bar-chart.js";
+function DrilldownBarChart({
+  data,
+  seriesName = "Value",
+  breadcrumbLabel = "Drill-down path",
+  sort = true,
+  height,
+  className,
+  ...rest
+}) {
+  const { focus, path, drill } = useDrill(data, sort);
+  const items = focus.children;
+  const categories = useMemo(() => items.map((node) => node.name), [items]);
+  const series = useMemo(
+    () => [
+      {
+        id: focus.id,
+        name: seriesName,
+        data: items.map((node) => node.value),
+        colors: items.map((node, index) => node.color ?? seriesColor(index))
+      }
+    ],
+    [focus.id, items, seriesName]
+  );
+  const drillable = useMemo(
+    () => new Set(items.filter((node) => node.children.length > 0).map((node) => node.name)),
+    [items]
+  );
+  const label = useCallback(
+    (value) => drillable.has(String(value)) ? `${value} \u203A` : String(value),
+    [drillable]
+  );
+  const fill = height === "fill";
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex w-full min-w-0 flex-col gap-2", fill && "h-full", className), children: [
+    /* @__PURE__ */ jsx(
+      ChartBreadcrumb,
+      {
+        items: path.map((node) => ({ id: node.id, name: node.name })),
+        onSelect: drill,
+        label: breadcrumbLabel
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { className: cn("min-w-0", fill && "min-h-0 flex-1"), children: /* @__PURE__ */ jsx(
+      BarChart,
+      {
+        ...rest,
+        height,
+        legend: false,
+        categories,
+        series,
+        xFormat: label,
+        onCategoryClick: (index) => {
+          const node = items[index];
+          if (node) drill(node.id);
+        }
+      }
+    ) })
+  ] });
+}
+export {
+  DrilldownBarChart
+};

package/dist/charts/bar-chart/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./bar-chart.js";
+export * from "./bar-race.js";
+export * from "./bar-race-chart.js";
+export * from "./drilldown-bar-chart.js";

package/dist/charts/bar-chart/index.js

@@ -0,0 +1,4 @@
+export * from "./bar-chart.js";
+export * from "./bar-race.js";
+export * from "./bar-race-chart.js";
+export * from "./drilldown-bar-chart.js";

package/dist/charts/beeswarm-chart/beeswarm-chart.d.ts

@@ -0,0 +1,53 @@
+import { type DistributionLabels } from "../core/distribution/labels.js";
+import { type DistributionAxisOptions } from "../core/distribution/layout.js";
+import { type ValueFormat } from "../core/format.js";
+export interface BeeswarmPoint {
+    value: number;
+    /** Row (or column) of the point; all points share one row when omitted. */
+    category?: string;
+    /** Drives the radius (area-proportional) when the chart has sizes. */
+    size?: number;
+    /** Name shown in the tooltip and data table, e.g. the client. */
+    label?: string;
+}
+export interface BeeswarmSeries {
+    id: string;
+    name: string;
+    points: readonly BeeswarmPoint[];
+    color?: string;
+}
+export interface BeeswarmChartProps {
+    title: string;
+    /** Colors and legend; points of every series share the rows. */
+    series: readonly BeeswarmSeries[];
+    /** Row order; derived from the points (first seen first) when omitted. */
+    categories?: readonly string[];
+    /** "horizontal": values along x, one row per category. "vertical": one column per category. */
+    orientation?: "horizontal" | "vertical";
+    valueFormat?: ValueFormat;
+    valueAxis?: DistributionAxisOptions;
+    /** Radius of every point when there are no sizes (pixels). */
+    radius?: number;
+    /** Radius range for sized points: the largest size gets `max`, area-proportional. */
+    sizeRange?: readonly [number, number];
+    sizeFormat?: ValueFormat;
+    /** Space between points (pixels). */
+    gap?: number;
+    /** Height of the drawing; grows with the number of rows by default. */
+    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;
+}
+/**
+ * Beeswarm: every observation is a dot on the value axis, nudged sideways
+ * just enough that no two overlap, so clusters read as density while each
+ * point stays individually explorable.
+ */
+export declare function BeeswarmChart({ title, series, categories: categoriesProp, orientation, valueFormat, valueAxis, radius, sizeRange, sizeFormat, gap, height: heightProp, aspectRatio, legend, grid, tooltip, loading, animate, labels: labelsProp, className, }: BeeswarmChartProps): import("react").JSX.Element;

package/dist/charts/beeswarm-chart/beeswarm-chart.js

@@ -0,0 +1,356 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useMemo, useRef, useState } from "react";
+import { cn } from "../../utils/cn.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { PlotExplorer } from "../core/distribution/explorer.js";
+import { resolveDistributionLabels } from "../core/distribution/labels.js";
+import {
+  categoryLayout,
+  nearestPoint,
+  tooltipFit
+} from "../core/distribution/layout.js";
+import { CategoryAxes } from "../core/distribution/marks.js";
+import { beeswarm } from "../core/distribution/stats.js";
+import { useDistributionLegend } from "../core/distribution/use-legend.js";
+import { resolveFormat } from "../core/format.js";
+import { useEntryAnimation } from "../core/motion.js";
+import { ChartTooltip } from "../core/tooltip.js";
+function BeeswarmChart({
+  title,
+  series,
+  categories: categoriesProp,
+  orientation = "horizontal",
+  valueFormat,
+  valueAxis,
+  radius = 4.5,
+  sizeRange = [3, 14],
+  sizeFormat,
+  gap = 1.25,
+  height: heightProp,
+  aspectRatio,
+  legend,
+  grid = true,
+  tooltip = true,
+  loading,
+  animate = true,
+  labels: labelsProp,
+  className
+}) {
+  const labels = resolveDistributionLabels(labelsProp);
+  const legendState = useDistributionLegend(series, legend, "dot");
+  const categories = useMemo(() => {
+    if (categoriesProp) return categoriesProp;
+    const seen = [];
+    for (const item of series) {
+      for (const point of item.points) {
+        const name = point.category ?? "";
+        if (!seen.includes(name)) seen.push(name);
+      }
+    }
+    return seen.length ? seen : [""];
+  }, [categoriesProp, series]);
+  const height = heightProp ?? (orientation === "horizontal" ? Math.max(200, categories.length * 96 + 48) : 340);
+  const format = resolveFormat(valueFormat);
+  const formatSize = resolveFormat(sizeFormat);
+  const sized = series.some((item) => item.points.some((point) => point.size != null));
+  const empty = !series.some((item) => item.points.some((point) => Number.isFinite(point.value)));
+  const tableRows = legendState.all.flatMap(
+    (item) => item.source.points.filter((point) => Number.isFinite(point.value)).map((point, index) => ({ item, point, index }))
+  );
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height,
+      aspectRatio,
+      labels,
+      loading,
+      empty,
+      skeleton: "line",
+      className: cn("@container", className),
+      legend: legendState.node,
+      legendPosition: legendState.position,
+      table: /* @__PURE__ */ jsx(
+        ChartDataTable,
+        {
+          caption: title,
+          categoryHeader: labels.point,
+          categories: tableRows.map(
+            ({ item, point, index }) => point.label ?? `${point.category ?? item.name} ${index + 1}`
+          ),
+          columns: [
+            { id: "series", name: labels.series, values: tableRows.map(({ item }) => item.name) },
+            {
+              id: "row",
+              name: labels.category,
+              values: tableRows.map(({ point }) => point.category ?? "")
+            },
+            {
+              id: "value",
+              name: labels.value,
+              values: tableRows.map(({ point }) => format(point.value))
+            },
+            ...sized ? [
+              {
+                id: "size",
+                name: labels.size,
+                values: tableRows.map(
+                  ({ point }) => point.size != null ? formatSize(point.size) : ""
+                )
+              }
+            ] : []
+          ]
+        }
+      ),
+      children: (width, measuredHeight) => /* @__PURE__ */ jsx(
+        BeeswarmPlot,
+        {
+          width,
+          height: measuredHeight,
+          title,
+          categories,
+          visible: legendState.visible,
+          orientation,
+          valueFormat,
+          valueAxis,
+          radius,
+          sizeRange: sized ? sizeRange : null,
+          sizeFormat,
+          gap,
+          grid,
+          tooltip,
+          animate,
+          labels,
+          isDimmed: legendState.isDimmed
+        }
+      )
+    }
+  );
+}
+const Dots = memo(function Dots2({
+  points,
+  isDimmed
+}) {
+  return /* @__PURE__ */ jsx("g", { children: points.map((point) => /* @__PURE__ */ jsx(
+    "circle",
+    {
+      "data-dot": "",
+      cx: point.x,
+      cy: point.y,
+      r: point.r,
+      strokeWidth: 1,
+      className: "transition-opacity duration-150",
+      style: {
+        fill: point.series.color,
+        fillOpacity: 0.82,
+        stroke: "var(--surface)",
+        opacity: isDimmed(point.series.id) ? 0.2 : 1
+      }
+    },
+    point.key
+  )) });
+});
+function BeeswarmPlot({
+  width,
+  height,
+  title,
+  categories,
+  visible,
+  orientation,
+  valueFormat,
+  valueAxis,
+  radius,
+  sizeRange,
+  sizeFormat,
+  gap,
+  grid,
+  tooltip,
+  animate,
+  labels,
+  isDimmed
+}) {
+  const svgRef = useRef(null);
+  const [active, setActive] = useState(null);
+  const { layout, points } = useMemo(() => {
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    let maxSize = 0;
+    for (const item of visible) {
+      for (const point of item.source.points) {
+        if (!Number.isFinite(point.value)) continue;
+        lo = Math.min(lo, point.value);
+        hi = Math.max(hi, point.value);
+        if (point.size != null && point.size > maxSize) maxSize = point.size;
+      }
+    }
+    const layout2 = categoryLayout({
+      width,
+      height,
+      orientation,
+      categories,
+      seriesCount: 1,
+      extent: Number.isFinite(lo) ? [lo, hi] : null,
+      valueFormat,
+      axis: valueAxis,
+      padding: 0.1
+    });
+    const horizontal = layout2.horizontal;
+    const radiusOf = (point) => sizeRange ? Math.max(
+      sizeRange[0],
+      sizeRange[1] * Math.sqrt(Math.max(0, point.size ?? 0) / (maxSize || 1))
+    ) : radius;
+    const placed = [];
+    categories.forEach((category, row) => {
+      const members = [];
+      for (const item of visible) {
+        item.source.points.forEach((point, index) => {
+          if (Number.isFinite(point.value) && (point.category ?? categories[0]) === category) {
+            members.push({ item, point, index });
+          }
+        });
+      }
+      if (members.length === 0) return;
+      const slot = layout2.slot(row, 0);
+      const limit = slot.size / 2;
+      let scale = 1;
+      let offsets = [];
+      for (let pass = 0; pass < 4; pass += 1) {
+        const swarm = members.map(({ point }) => ({
+          position: layout2.valueScale.map(point.value),
+          radius: radiusOf(point) * scale
+        }));
+        offsets = beeswarm(swarm, { gap });
+        const reach = Math.max(
+          ...offsets.map((offset, i) => Math.abs(offset) + (swarm[i]?.radius ?? 0))
+        );
+        if (reach <= limit) break;
+        scale *= Math.max(0.35, limit / reach * 0.98);
+      }
+      members.forEach(({ item, point, index }, i) => {
+        const along = layout2.valueScale.map(point.value);
+        const cross = slot.center + Math.max(-limit, Math.min(limit, offsets[i] ?? 0));
+        placed.push({
+          key: `${item.id}-${index}`,
+          series: item,
+          point,
+          category: row,
+          x: horizontal ? along : cross,
+          y: horizontal ? cross : along,
+          r: Math.max(1.25, radiusOf(point) * scale)
+        });
+      });
+    });
+    placed.sort((a, b) => a.category - b.category || a.point.value - b.point.value);
+    return { layout: layout2, points: placed };
+  }, [
+    width,
+    height,
+    orientation,
+    categories,
+    visible,
+    valueFormat,
+    valueAxis,
+    radius,
+    sizeRange,
+    gap
+  ]);
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      root.querySelectorAll("[data-dot]").forEach((dot, index) => {
+        dot.animate(
+          [
+            { opacity: 0, transform: "scale(0.2)" },
+            { opacity: 1, transform: "none" }
+          ],
+          {
+            duration: 420,
+            delay: Math.min(900, index * 6),
+            easing: "cubic-bezier(.34,1.56,.64,1)",
+            fill: "backwards"
+          }
+        );
+      });
+    },
+    { disabled: !animate, replayKey: points.length }
+  );
+  const { margin, innerWidth, innerHeight } = layout;
+  const format = resolveFormat(valueFormat);
+  const formatSize = resolveFormat(sizeFormat);
+  const current = active != null ? points[active] : void 0;
+  const titleOf = (point) => point.point.label ?? (categories[point.category] || point.series.name);
+  const rows = current ? [
+    {
+      id: "value",
+      name: visible.length > 1 ? current.series.name : labels.value,
+      value: format(current.point.value),
+      color: current.series.color,
+      shape: "dot"
+    },
+    ...current.point.size != null && sizeRange ? [
+      {
+        id: "size",
+        name: labels.size,
+        value: formatSize(current.point.size),
+        color: "transparent"
+      }
+    ] : []
+  ] : [];
+  const valueText = current ? `${titleOf(current)}${current.point.label && categories[current.category] ? `, ${categories[current.category]}` : ""}: ${rows.map((row) => `${row.name} ${row.value}`).join(", ")}` : title;
+  return /* @__PURE__ */ jsxs("div", { className: "relative h-full w-full", children: [
+    /* @__PURE__ */ jsx(
+      "svg",
+      {
+        ref: svgRef,
+        role: "img",
+        "aria-label": title,
+        width,
+        height,
+        className: "block overflow-visible",
+        children: /* @__PURE__ */ jsxs("g", { transform: `translate(${margin.left},${margin.top})`, children: [
+          /* @__PURE__ */ jsx(CategoryAxes, { layout, title: valueAxis?.title, grid }),
+          /* @__PURE__ */ jsx(Dots, { points, isDimmed }),
+          current ? /* @__PURE__ */ jsx(
+            "circle",
+            {
+              cx: current.x,
+              cy: current.y,
+              r: current.r + 3,
+              strokeWidth: 2,
+              fill: "none",
+              style: { stroke: current.series.color }
+            }
+          ) : null
+        ] })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      PlotExplorer,
+      {
+        count: points.length,
+        active,
+        onActiveChange: setActive,
+        pick: (x, y) => nearestPoint(points, x, y, 14),
+        label: labels.explore,
+        valueText,
+        margin,
+        width: innerWidth,
+        height: innerHeight
+      }
+    ),
+    tooltip && current ? /* @__PURE__ */ jsx(
+      ChartTooltip,
+      {
+        x: margin.left + current.x + current.r,
+        y: margin.top + current.y,
+        ...tooltipFit(width),
+        title: current.point.label && categories[current.category] ? `${current.point.label} \xB7 ${categories[current.category]}` : titleOf(current),
+        rows
+      }
+    ) : null
+  ] });
+}
+export {
+  BeeswarmChart
+};

package/dist/charts/beeswarm-chart/index.d.ts

@@ -0,0 +1 @@
+export * from "./beeswarm-chart.js";

package/dist/charts/beeswarm-chart/index.js

@@ -0,0 +1 @@
+export * from "./beeswarm-chart.js";

package/dist/charts/box-plot/box-plot.d.ts

@@ -0,0 +1,48 @@
+import type { DistributionSeries } from "../core/distribution/geometry.js";
+import { type DistributionLabels } from "../core/distribution/labels.js";
+import { type DistributionAxisOptions } from "../core/distribution/layout.js";
+import { type PointColoring } from "../core/distribution/points.js";
+import { type ValueFormat } from "../core/format.js";
+export interface BoxPlotProps {
+    /** Accessible name of the chart and caption of its data table. */
+    title: string;
+    /** One box (per series) for each category, e.g. the barbers. */
+    categories: readonly string[];
+    /** `data[i]` holds the raw samples of `categories[i]`. Several series are drawn side by side. */
+    series: readonly DistributionSeries[];
+    /** "vertical": boxes stand on the x axis. "horizontal": one row per category. */
+    orientation?: "vertical" | "horizontal";
+    valueFormat?: ValueFormat;
+    valueAxis?: DistributionAxisOptions;
+    /** Tukey fence multiplier; `Infinity` stretches the whiskers to min and max. */
+    whisker?: number;
+    /** Diamond on the mean. */
+    showMean?: boolean;
+    /** Dots for values outside the whiskers. */
+    showOutliers?: boolean;
+    /** Every raw observation as a dot over the box, with deterministic jitter. */
+    showPoints?: boolean;
+    /** Share (0-1) of the box width the dots spread over. */
+    jitter?: number;
+    /** "value" grades each dot from pale to full colour across the value range. */
+    pointColor?: PointColoring;
+    /** Seed of the jitter, so the dots are stable between renders. */
+    seed?: number;
+    /** Height of the drawing in pixels. */
+    height?: number | "fill";
+    /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
+    aspectRatio?: number;
+    /** Shown automatically with more than one series. */
+    legend?: boolean | "top" | "bottom";
+    grid?: boolean;
+    tooltip?: boolean;
+    loading?: boolean;
+    animate?: boolean;
+    labels?: Partial<DistributionLabels>;
+    className?: string;
+}
+/**
+ * Box-and-whisker plot: median, quartiles, Tukey whiskers, outliers and the
+ * mean for every category, optionally grouped by series.
+ */
+export declare function BoxPlot({ title, categories, series, orientation, valueFormat, valueAxis, whisker, showMean, showOutliers, showPoints, jitter, pointColor, seed, height, aspectRatio, legend, grid, tooltip, loading, animate, labels: labelsProp, className, }: BoxPlotProps): import("react").JSX.Element;