@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/crossfilter/crossfilter.js

@@ -0,0 +1,333 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useMemo, useState } from "react";
+import { cn } from "../../utils/cn.js";
+import { BarChart } from "../bar-chart/bar-chart.js";
+import { rangesToRect, rectToRanges } from "../core/distribution/brush.js";
+import { resolveFormat } from "../core/format.js";
+import { ScatterChart } from "../scatter-chart/scatter-chart.js";
+import {
+  activeFilterCount,
+  binRecords,
+  binsInRange,
+  clearFilters,
+  evenEdges,
+  filterRecords,
+  groupRecords,
+  isSelected,
+  NO_FILTERS,
+  rangeOfBins,
+  setRangeFilter,
+  toggleValue
+} from "./crossfilter-engine.js";
+const Context = createContext(null);
+function CrossfilterProvider({
+  data,
+  dimensions,
+  initialFilters = NO_FILTERS,
+  children
+}) {
+  const [filters, setFilters] = useState(initialFilters);
+  const filtered = useMemo(
+    () => filterRecords(data, dimensions, filters),
+    [data, dimensions, filters]
+  );
+  const toggle = useCallback(
+    (dimension, value) => setFilters((current) => toggleValue(current, dimension, value)),
+    []
+  );
+  const setRange = useCallback(
+    (dimension, range) => setFilters((current) => setRangeFilter(current, dimension, range)),
+    []
+  );
+  const clear = useCallback(
+    (dimension) => setFilters((current) => clearFilters(current, dimension)),
+    []
+  );
+  const api = useMemo(
+    () => ({
+      records: data,
+      filtered,
+      total: data.length,
+      filters,
+      activeCount: activeFilterCount(filters),
+      toggle,
+      setRange,
+      clear,
+      group: (dimension, options) => groupRecords(data, dimensions, filters, dimension, options),
+      groupAll: (dimension, options) => groupRecords(data, dimensions, NO_FILTERS, dimension, options),
+      bins: (dimension, edges) => binRecords(data, dimensions, filters, dimension, edges),
+      binsAll: (dimension, edges) => binRecords(data, dimensions, NO_FILTERS, dimension, edges),
+      inContext: (dimension) => filterRecords(data, dimensions, filters, dimension),
+      accessors: dimensions
+    }),
+    [data, dimensions, filtered, filters, toggle, setRange, clear]
+  );
+  return /* @__PURE__ */ jsx(Context.Provider, { value: api, children });
+}
+function useCrossfilter() {
+  const api = useContext(Context);
+  if (!api) throw new Error("useCrossfilter must be used inside a CrossfilterProvider");
+  return api;
+}
+const DEFAULT_CROSSFILTER_LABELS = {
+  total: "Total",
+  filtered: "Filtered",
+  count: (filtered, total) => `${filtered} of ${total}`,
+  clear: "Clear",
+  clearAll: "Clear all filters",
+  excluded: "Filtered out",
+  brush: "Select a rectangle: arrows move it, Shift and arrows resize it, Enter applies, Escape clears",
+  selection: (x, y) => `${x}; ${y}`
+};
+const DIMMED = "color-mix(in oklab, var(--accent) 30%, transparent)";
+function ChartHeader({
+  title,
+  dimension,
+  records,
+  labels
+}) {
+  const xf = useCrossfilter();
+  const owned = typeof dimension === "string" ? [dimension] : dimension;
+  const own = owned.some((id) => xf.filters[id] != null);
+  return /* @__PURE__ */ jsxs("div", { className: "mb-1 flex min-w-0 flex-wrap items-baseline justify-between gap-x-3 gap-y-1", children: [
+    /* @__PURE__ */ jsx("h3", { className: "m-0 min-w-0 truncate font-bold text-[13px] text-ink", children: title }),
+    /* @__PURE__ */ jsxs("div", { className: "flex shrink-0 items-center gap-2 font-semibold text-[12px] text-ink-3 tabular-nums", children: [
+      /* @__PURE__ */ jsx("span", { "aria-live": "polite", children: labels.count(records, xf.total) }),
+      own ? /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          onClick: () => {
+            for (const id of owned) xf.clear(id);
+          },
+          className: "cursor-pointer rounded-button border-0 bg-surface-2 px-2 py-0.5 font-semibold text-[11px] text-ink-2 hover:text-ink",
+          children: labels.clear
+        }
+      ) : null
+    ] })
+  ] });
+}
+function CrossfilterBarChart({
+  title,
+  dimension,
+  keys,
+  keyLabel = String,
+  measure,
+  orientation = "vertical",
+  labels: labelsProp,
+  className,
+  ...chart
+}) {
+  const xf = useCrossfilter();
+  const labels = { ...DEFAULT_CROSSFILTER_LABELS, ...labelsProp };
+  const options = { keys, value: measure };
+  const all = xf.groupAll(dimension, options);
+  const inContext = xf.group(dimension, {
+    ...options,
+    keys: keys ?? all.map((group) => group.key)
+  });
+  const read = (group) => measure ? group.sum : group.count;
+  const own = xf.filters[dimension];
+  const shown = inContext.reduce((sum, group) => sum + group.count, 0);
+  const selected = own ? xf.filtered.length : shown;
+  return /* @__PURE__ */ jsxs("figure", { className: cn("m-0 min-w-0", className), children: [
+    /* @__PURE__ */ jsx(ChartHeader, { title, dimension, records: selected, labels }),
+    /* @__PURE__ */ jsx(
+      BarChart,
+      {
+        title,
+        categories: inContext.map((group) => keyLabel(group.key)),
+        orientation,
+        series: [
+          {
+            id: "total",
+            name: labels.total,
+            color: "var(--line-strong)",
+            data: inContext.map(
+              (group) => read(all.find((item) => item.key === group.key) ?? group)
+            )
+          },
+          {
+            id: "filtered",
+            name: labels.filtered,
+            color: "var(--accent)",
+            data: inContext.map(read),
+            colors: inContext.map(
+              (group) => isSelected(xf.filters, dimension, group.key) ? void 0 : DIMMED
+            )
+          }
+        ],
+        onCategoryClick: (index) => {
+          const group = inContext[index];
+          if (group) xf.toggle(dimension, group.key);
+        },
+        ...chart
+      }
+    )
+  ] });
+}
+function CrossfilterHistogram({
+  title,
+  dimension,
+  edges: edgesProp,
+  domain = [0, 100],
+  bins = 10,
+  edgeFormat,
+  labels: labelsProp,
+  className,
+  ...chart
+}) {
+  const xf = useCrossfilter();
+  const labels = { ...DEFAULT_CROSSFILTER_LABELS, ...labelsProp };
+  const edges = useMemo(
+    () => edgesProp ?? evenEdges(domain[0], domain[1], bins),
+    [edgesProp, domain, bins]
+  );
+  const format = resolveFormat(edgeFormat);
+  const all = xf.binsAll(dimension, edges);
+  const inContext = xf.bins(dimension, edges);
+  const own = xf.filters[dimension];
+  const band = own?.kind === "range" ? binsInRange(edges, own.min, own.max) : null;
+  const inRange = band ? inContext.slice(band[0], band[1] + 1).reduce((sum, value) => sum + value, 0) : inContext.reduce((sum, value) => sum + value, 0);
+  const records = own ? xf.filtered.length : inRange;
+  return /* @__PURE__ */ jsxs("figure", { className: cn("m-0 min-w-0", className), children: [
+    /* @__PURE__ */ jsx(ChartHeader, { title, dimension, records, labels }),
+    /* @__PURE__ */ jsx(
+      BarChart,
+      {
+        title,
+        categories: inContext.map((_, index) => format(edges[index])),
+        series: [
+          { id: "total", name: labels.total, color: "var(--line-strong)", data: all },
+          { id: "filtered", name: labels.filtered, color: "var(--accent)", data: inContext }
+        ],
+        rangeSelect: {
+          value: band,
+          onChange: (range) => xf.setRange(dimension, range ? rangeOfBins(edges, range[0], range[1]) : null)
+        },
+        ...chart
+      }
+    )
+  ] });
+}
+function CrossfilterScatter({
+  title,
+  x,
+  y,
+  xFormat,
+  yFormat,
+  pointLabel,
+  xLabel,
+  yLabel,
+  brush = true,
+  touchDelay,
+  labels: labelsProp,
+  className,
+  ...chart
+}) {
+  const xf = useCrossfilter();
+  const labels = { ...DEFAULT_CROSSFILTER_LABELS, ...labelsProp };
+  const accessX = xf.accessors[x];
+  const accessY = xf.accessors[y];
+  const kept = useMemo(() => new Set(xf.filtered), [xf.filtered]);
+  const series = useMemo(() => {
+    if (!accessX || !accessY) return [];
+    const point = (record) => ({
+      x: Number(accessX(record)),
+      y: Number(accessY(record)),
+      label: pointLabel ? pointLabel(record) : void 0
+    });
+    return [
+      {
+        id: "out",
+        name: labels.excluded,
+        color: "var(--line-strong)",
+        points: xf.records.filter((record) => !kept.has(record)).map(point)
+      },
+      {
+        id: "in",
+        name: labels.filtered,
+        color: "var(--accent)",
+        points: xf.filtered.map(point)
+      }
+    ];
+  }, [
+    xf.records,
+    xf.filtered,
+    kept,
+    accessX,
+    accessY,
+    pointLabel,
+    labels.excluded,
+    labels.filtered
+  ]);
+  const fx = resolveFormat(xFormat);
+  const fy = resolveFormat(yFormat);
+  const rangeOf = (id) => {
+    const filter = xf.filters[id];
+    return filter?.kind === "range" ? [filter.min, filter.max] : null;
+  };
+  const brushProp = brush ? {
+    value: rangesToRect(rangeOf(x), rangeOf(y)),
+    onChange: (rect) => {
+      const ranges = rect ? rectToRanges(rect) : { x: null, y: null };
+      xf.setRange(x, ranges.x);
+      xf.setRange(y, ranges.y);
+    },
+    label: labels.brush,
+    touchDelay,
+    describe: (rect) => labels.selection(
+      `${xLabel ?? x} ${fx(rect.x0)} \u2013 ${fx(rect.x1)}`,
+      `${yLabel ?? y} ${fy(rect.y0)} \u2013 ${fy(rect.y1)}`
+    )
+  } : void 0;
+  return /* @__PURE__ */ jsxs("figure", { className: cn("m-0 min-w-0", className), children: [
+    /* @__PURE__ */ jsx(ChartHeader, { title, dimension: [x, y], records: xf.filtered.length, labels }),
+    /* @__PURE__ */ jsx(
+      ScatterChart,
+      {
+        title,
+        series,
+        brush: brushProp,
+        xFormat,
+        yFormat,
+        radius: 3.5,
+        ...chart
+      }
+    )
+  ] });
+}
+function CrossfilterSummary({
+  noun,
+  labels: labelsProp,
+  className
+}) {
+  const xf = useCrossfilter();
+  const labels = { ...DEFAULT_CROSSFILTER_LABELS, ...labelsProp };
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-wrap items-center gap-x-3 gap-y-1", className), children: [
+    /* @__PURE__ */ jsxs("p", { className: "m-0 font-bold text-ink text-sm tabular-nums", "aria-live": "polite", children: [
+      labels.count(xf.filtered.length, xf.total),
+      " ",
+      noun
+    ] }),
+    xf.activeCount > 0 ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        onClick: () => xf.clear(),
+        className: "cursor-pointer rounded-button border-0 bg-surface-2 px-3 py-1 font-semibold text-[12px] text-ink-2 hover:text-ink",
+        children: labels.clearAll
+      }
+    ) : null
+  ] });
+}
+export {
+  CrossfilterBarChart,
+  CrossfilterHistogram,
+  CrossfilterProvider,
+  CrossfilterScatter,
+  CrossfilterSummary,
+  DEFAULT_CROSSFILTER_LABELS,
+  useCrossfilter
+};

package/dist/charts/crossfilter/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./crossfilter.js";
+export * from "./crossfilter-engine.js";

package/dist/charts/crossfilter/index.js

@@ -0,0 +1,2 @@
+export * from "./crossfilter.js";
+export * from "./crossfilter-engine.js";

package/dist/charts/donut-chart/center-fit.d.ts

@@ -0,0 +1,14 @@
+export interface CenterFit {
+    valueSize: number;
+    captionSize: number;
+    /** Characters of the caption that fit the hole; 0 hides it. */
+    captionChars: number;
+    /** Height of the whole text block, for vertical centring. */
+    block: number;
+}
+/**
+ * Sizes the centre text of a donut so both lines sit inside the hole: the font shrinks from
+ * `maxSize` until the value fits the chord at the block's outer edge, and the caption drops
+ * characters (or disappears) when only the value fits.
+ */
+export declare function fitCenterText(inner: number, valueChars: number, captionChars: number, semi?: boolean, maxSize?: number): CenterFit;

package/dist/charts/donut-chart/center-fit.js

@@ -0,0 +1,29 @@
+const VALUE_WIDTH_EM = 0.62;
+const CAPTION_WIDTH_EM = 0.58;
+const LINE_GAP = 4;
+const HOLE_MARGIN = 0.92;
+function chordWidth(radius, dy) {
+  return 2 * Math.sqrt(Math.max(0, radius * radius - dy * dy));
+}
+function fitCenterText(inner, valueChars, captionChars, semi = false, maxSize = 34) {
+  const room = inner * HOLE_MARGIN;
+  const captionSize = inner > 54 ? 12 : 10.5;
+  const start = Math.min(maxSize, Math.max(15, Math.round(inner * 0.34)));
+  for (let valueSize = start; valueSize >= 9; valueSize--) {
+    const block = valueSize + LINE_GAP + captionSize;
+    const width = chordWidth(room, semi ? block + 6 : block / 2);
+    const chars = Math.floor(width / (captionSize * CAPTION_WIDTH_EM));
+    if (valueChars * VALUE_WIDTH_EM * valueSize <= width && chars >= 6) {
+      return { valueSize, captionSize, captionChars: Math.min(captionChars, chars), block };
+    }
+  }
+  for (let valueSize = Math.min(maxSize, Math.round(inner * 0.5)); valueSize >= 8; valueSize--) {
+    if (valueChars * VALUE_WIDTH_EM * valueSize <= chordWidth(room, semi ? valueSize + 6 : valueSize / 2)) {
+      return { valueSize, captionSize, captionChars: 0, block: valueSize };
+    }
+  }
+  return { valueSize: 8, captionSize, captionChars: 0, block: 8 };
+}
+export {
+  fitCenterText
+};

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

@@ -0,0 +1,73 @@
+import { type ValueFormat } from "../core/format.js";
+import { type ChartLabels } from "../core/types.js";
+export interface DonutDatum {
+    /** Stable identity, used for keys and legend toggling. */
+    id: string;
+    name: string;
+    value: number;
+    /** CSS color; defaults to the palette slot of the datum. */
+    color?: string;
+    /** Overrides the chart `valueFormat` for this slice. */
+    format?: ValueFormat;
+    /** Sub-slices. Clicking the slice opens them in the same ring (see `drilldown`). */
+    children?: readonly DonutDatum[];
+}
+/** How slices are painted: flat color, a radial gradient, or a texture over the color. */
+export type DonutFill = "solid" | "gradient" | "pattern";
+export type DonutOutsideLabels = boolean | "name" | "percent" | "both";
+export interface DonutChartProps {
+    /** Accessible name of the drawing. */
+    title: string;
+    description?: string;
+    data: readonly DonutDatum[];
+    /** `pie` fills the centre (no centre label). */
+    variant?: "donut" | "pie";
+    /** Half circle opening upwards, like a gauge. */
+    semi?: boolean;
+    /** Hole size as a fraction of the outer radius (donut only). */
+    innerRadius?: number;
+    /** Radius of the rounded slice corners, in pixels. 0 = sharp. */
+    cornerRadius?: number;
+    /** Visible gap between slices, in pixels. */
+    gap?: number;
+    /** Pixels a hovered or focused slice moves outwards. */
+    explode?: number;
+    /** Where the first slice starts, in degrees from 12 o'clock (full circle only). */
+    startAngle?: number;
+    /** One hue in shades, darkest on the largest slice. `true` uses the accent; a string sets the base color. */
+    monochrome?: boolean | string;
+    /** `gradient` fades each slice towards the hole; `pattern` adds a texture per slice, so color is not the only cue. */
+    fill?: DonutFill;
+    /** Slices with `children` open on click (or Enter) with a breadcrumb to go back. */
+    drilldown?: boolean;
+    /** First breadcrumb item; defaults to the chart title. */
+    rootLabel?: string;
+    /** Accessible name of the breadcrumb. */
+    breadcrumbLabel?: string;
+    height?: number | "fill";
+    /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
+    aspectRatio?: number;
+    valueFormat?: ValueFormat;
+    /** Caption under the centre value when nothing is hovered. Defaults to the "Total" label. */
+    centerLabel?: string;
+    /** Replaces the total shown in the centre while nothing is hovered. */
+    centerValue?: string;
+    /** Names / percentages on leader lines around the ring. `true` shows both. */
+    outsideLabels?: DonutOutsideLabels;
+    legend?: boolean | "top" | "bottom";
+    tooltip?: boolean;
+    loading?: boolean;
+    animate?: boolean;
+    /** Ids hidden at first. */
+    initialHidden?: readonly string[];
+    onSliceClick?: (datum: DonutDatum) => void;
+    labels?: Partial<ChartLabels>;
+    className?: string;
+}
+/**
+ * Donut, pie and semi-donut. Rounded slice corners and a pixel gap between
+ * slices, a centre total that follows the hovered slice, slices that step out
+ * on hover or keyboard focus, optional outside labels on leader lines (with
+ * collision avoidance) and a legend that toggles slices.
+ */
+export declare function DonutChart({ title, description, data, variant, semi, innerRadius, cornerRadius, gap, explode, startAngle, monochrome, fill, drilldown, rootLabel, breadcrumbLabel, height, aspectRatio, valueFormat, centerLabel, centerValue, outsideLabels, legend, tooltip, loading, animate, initialHidden, onSliceClick, labels: labelsProp, className, }: DonutChartProps): import("react").JSX.Element;