@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/src/charts/core/use-canvas.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { type RefObject, useEffect, useState } from "react";
+
+/**
+ * Bumps whenever the theme or accent changes (`data-theme` / `data-accent` on
+ * `<html>`), so canvas layers that bake token colors into pixels repaint.
+ */
+export function useThemeVersion(): number {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    if (typeof document === "undefined" || typeof MutationObserver === "undefined") return;
+    const observer = new MutationObserver(() => setVersion((value) => value + 1));
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme", "data-accent", "class"],
+    });
+    return () => observer.disconnect();
+  }, []);
+  return version;
+}
+
+/**
+ * Resolves CSS colors (`var(--token)`, `color-mix(...)`) to a string a canvas
+ * understands, using the cascade of `host`. Unresolvable values are returned
+ * unchanged.
+ */
+export function resolveCssColors(host: Element, colors: readonly string[]): string[] {
+  if (typeof document === "undefined") return [...colors];
+  const probe = document.createElement("span");
+  probe.style.cssText = "position:absolute;visibility:hidden;pointer-events:none";
+  host.appendChild(probe);
+  try {
+    return colors.map((color) => {
+      probe.style.color = "";
+      probe.style.color = color;
+      return probe.style.color ? getComputedStyle(probe).color : color;
+    });
+  } finally {
+    host.removeChild(probe);
+  }
+}
+
+export interface CanvasPaint {
+  ctx: CanvasRenderingContext2D;
+  width: number;
+  height: number;
+  /** Resolve a CSS color once per paint (cached by the caller if needed). */
+  resolve: (colors: readonly string[]) => string[];
+}
+
+/**
+ * Sizes a canvas for the device pixel ratio and repaints it whenever `deps`
+ * or the theme change. `paint` draws in CSS pixels.
+ */
+export function useCanvasPaint(
+  ref: RefObject<HTMLCanvasElement | null>,
+  width: number,
+  height: number,
+  paint: (frame: CanvasPaint) => void,
+  deps: readonly unknown[],
+): void {
+  const theme = useThemeVersion();
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `deps` is the caller's dependency list.
+  useEffect(() => {
+    const canvas = ref.current;
+    if (!canvas || width <= 0 || height <= 0) return;
+    const ratio = typeof window === "undefined" ? 1 : Math.min(3, window.devicePixelRatio || 1);
+    canvas.width = Math.max(1, Math.round(width * ratio));
+    canvas.height = Math.max(1, Math.round(height * ratio));
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    ctx.setTransform(ratio, 0, 0, ratio, 0, 0);
+    ctx.clearRect(0, 0, width, height);
+    paint({ ctx, width, height, resolve: (colors) => resolveCssColors(canvas, colors) });
+  }, [ref, width, height, theme, ...deps]);
+}

package/src/charts/core/use-chart-size.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import { type RefObject, useEffect, useLayoutEffect, useRef, useState } from "react";
+
+/** Layout effect in the browser, plain effect on the server (no SSR warning). */
+export const useIsomorphicLayoutEffect =
+  typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/** Width used for the server render and the first client paint before measuring. */
+export const FALLBACK_WIDTH = 640;
+
+/** Height used before the first measurement when a chart fills its parent. */
+export const FALLBACK_HEIGHT = 300;
+
+export interface ChartSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Tracks the content box of an element with a ResizeObserver. Renders with
+ * the fallback size on the server and until the first measurement.
+ */
+export function useChartSize<T extends HTMLElement>(
+  fallback: ChartSize = { width: FALLBACK_WIDTH, height: FALLBACK_HEIGHT },
+): [RefObject<T | null>, ChartSize] {
+  const ref = useRef<T | null>(null);
+  const [size, setSize] = useState<ChartSize>(fallback);
+
+  useIsomorphicLayoutEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    const apply = (width: number, height: number) => {
+      setSize((current) => {
+        const nextWidth = width > 0 ? width : current.width;
+        const nextHeight = height > 0 ? height : current.height;
+        return Math.abs(current.width - nextWidth) < 0.5 &&
+          Math.abs(current.height - nextHeight) < 0.5
+          ? current
+          : { width: nextWidth, height: nextHeight };
+      });
+    };
+    const rect = element.getBoundingClientRect();
+    apply(rect.width, rect.height);
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry) apply(entry.contentRect.width, entry.contentRect.height);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+
+  return [ref, { width: Math.floor(size.width), height: Math.floor(size.height) }];
+}
+
+/** Width only (kept for charts that do not need the height). */
+export function useChartWidth<T extends HTMLElement>(
+  fallbackWidth = FALLBACK_WIDTH,
+): [RefObject<T | null>, number] {
+  const [ref, size] = useChartSize<T>({ width: fallbackWidth, height: FALLBACK_HEIGHT });
+  return [ref, size.width];
+}
+
+export { type ResolveHeightInput, resolveDrawingHeight } from "./drawing-height.js";

package/src/charts/core/use-drill.ts

@@ -0,0 +1,100 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  ancestors,
+  buildHierarchy,
+  findNode,
+  type HierarchyDatum,
+  type HierarchyNode,
+  interpolateView,
+  type PartitionView,
+} from "./hierarchy.js";
+import { useReducedMotion } from "./motion.js";
+
+export interface DrillState {
+  root: HierarchyNode;
+  /** Node filling the view. */
+  focus: HierarchyNode;
+  /** Root first, focus last. */
+  path: HierarchyNode[];
+  /** Zooms into a node with children; any ancestor id zooms back out. */
+  drill: (id: string) => void;
+  /** One level up; returns false at the root. */
+  up: () => boolean;
+}
+
+/**
+ * Builds the hierarchy once per data set and keeps the focused (zoomed) node.
+ * Drilling into a leaf does nothing; a stale focus falls back to the root.
+ */
+export function useDrill(
+  data: HierarchyDatum,
+  sort = true,
+  onFocusChange?: (node: HierarchyNode) => void,
+): DrillState {
+  const root = useMemo(() => buildHierarchy(data, { sort }), [data, sort]);
+  const [focusId, setFocusId] = useState(root.id);
+  const focus = findNode(root, focusId) ?? root;
+  const path = useMemo(() => ancestors(focus), [focus]);
+  const change = (node: HierarchyNode) => {
+    setFocusId(node.id);
+    onFocusChange?.(node);
+  };
+  return {
+    root,
+    focus,
+    path,
+    drill: (id) => {
+      const node = findNode(root, id);
+      if (node && node.children.length > 0 && node.id !== focus.id) change(node);
+    },
+    up: () => {
+      if (!focus.parent) return false;
+      change(focus.parent);
+      return true;
+    },
+  };
+}
+
+function easeOutCubic(t: number): number {
+  return 1 - (1 - t) ** 3;
+}
+
+/**
+ * Animates a partition view (the zoom window of a sunburst or icicle) towards
+ * `target` with `requestAnimationFrame`. Jumps straight there when disabled,
+ * under `prefers-reduced-motion`, or on the server.
+ */
+export function useAnimatedView(
+  target: PartitionView,
+  { disabled = false, duration = 650 }: { disabled?: boolean; duration?: number } = {},
+): PartitionView {
+  const reduced = useReducedMotion();
+  const [view, setView] = useState(target);
+  const current = useRef(target);
+  const { x0, x1, depth } = target;
+
+  useEffect(() => {
+    const to = { x0, x1, depth };
+    const from = current.current;
+    if (disabled || reduced || typeof requestAnimationFrame !== "function") {
+      current.current = to;
+      setView(to);
+      return;
+    }
+    let frame = 0;
+    const start = performance.now();
+    const step = (now: number) => {
+      const t = Math.min(1, (now - start) / duration);
+      const next = interpolateView(from, to, easeOutCubic(t));
+      current.current = next;
+      setView(next);
+      if (t < 1) frame = requestAnimationFrame(step);
+    };
+    frame = requestAnimationFrame(step);
+    return () => cancelAnimationFrame(frame);
+  }, [x0, x1, depth, disabled, reduced, duration]);
+
+  return view;
+}

package/src/charts/core/use-index-navigation.ts

@@ -0,0 +1,68 @@
+"use client";
+
+import { type KeyboardEvent, useCallback, useEffect, useRef, useState } from "react";
+
+export interface IndexNavigationOptions {
+  /** Arrow keys wrap around the ends (circular charts). */
+  wrap?: boolean;
+}
+
+/**
+ * Active-item state for charts made of discrete items (slices, axes, stages).
+ * One source of truth for pointer hover and keyboard focus, so the tooltip,
+ * the highlight and `aria-valuetext` always agree. `ref` goes on the
+ * positioned container: `hover` stores the pointer relative to it.
+ */
+export function useIndexNavigation<T extends HTMLElement = HTMLDivElement>(
+  count: number,
+  { wrap = false }: IndexNavigationOptions = {},
+) {
+  const ref = useRef<T>(null);
+  const [active, setActive] = useState<number | null>(null);
+  const [pointer, setPointer] = useState<{ x: number; y: number } | null>(null);
+
+  useEffect(() => {
+    setActive((current) => (current != null && current >= count ? null : current));
+  }, [count]);
+
+  const hover = useCallback((index: number, event: { clientX: number; clientY: number }) => {
+    const box = ref.current?.getBoundingClientRect();
+    if (!box) return;
+    setActive(index);
+    setPointer({ x: event.clientX - box.left, y: event.clientY - box.top });
+  }, []);
+
+  const leave = useCallback(() => {
+    setActive(null);
+    setPointer(null);
+  }, []);
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if (count === 0) return;
+    const last = count - 1;
+    let move: (current: number | null) => number;
+    if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+      move = (current) =>
+        current == null ? 0 : wrap ? (current + 1) % count : Math.min(last, current + 1);
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+      move = (current) =>
+        current == null ? last : wrap ? (current - 1 + count) % count : Math.max(0, current - 1);
+    } else if (event.key === "Home") move = () => 0;
+    else if (event.key === "End") move = () => last;
+    else if (event.key === "Escape") {
+      leave();
+      return;
+    } else return;
+    event.preventDefault();
+    setPointer(null);
+    setActive(move);
+  };
+
+  const sliderProps = {
+    onKeyDown,
+    onFocus: () => setActive((current) => current ?? 0),
+    onBlur: leave,
+  };
+
+  return { ref, active, pointer, setActive, hover, leave, sliderProps };
+}

package/src/charts/core/use-pan-zoom.ts

@@ -0,0 +1,219 @@
+"use client";
+
+import { type PointerEvent, useCallback, useEffect, useRef, useState } from "react";
+
+/** Scale `k` and translation of a pannable stage: screen = content * k + (x, y). */
+export interface PanZoomView {
+  k: number;
+  x: number;
+  y: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Scales `view` by `factor` keeping the screen point `px, py` fixed. */
+export function zoomAround(
+  view: PanZoomView,
+  factor: number,
+  px: number,
+  py: number,
+  minZoom: number,
+  maxZoom: number,
+): PanZoomView {
+  const k = clamp(view.k * factor, minZoom, maxZoom);
+  const ratio = k / view.k;
+  return { k, x: px - (px - view.x) * ratio, y: py - (py - view.y) * ratio };
+}
+
+/**
+ * View that shows a `contentWidth` x `contentHeight` drawing centred in a
+ * `width` x `height` viewport, `padding` from the edges, never enlarged past `maxFit`.
+ */
+export function fitView(
+  contentWidth: number,
+  contentHeight: number,
+  width: number,
+  height: number,
+  { padding = 16, minZoom = 0.05, maxFit = 1 } = {},
+): PanZoomView {
+  const k = clamp(
+    Math.min(
+      (width - padding * 2) / Math.max(1, contentWidth),
+      (height - padding * 2) / Math.max(1, contentHeight),
+      maxFit,
+    ),
+    minZoom,
+    Number.POSITIVE_INFINITY,
+  );
+  return { k, x: (width - contentWidth * k) / 2, y: (height - contentHeight * k) / 2 };
+}
+
+export interface UsePanZoomOptions {
+  minZoom?: number;
+  maxZoom?: number;
+  /**
+   * Wheel zoom: `modifier` (default) only with Ctrl/⌘ or a trackpad pinch, so
+   * the page keeps scrolling; `always` captures the wheel; `off` ignores it.
+   */
+  wheel?: "modifier" | "always" | "off";
+}
+
+const DRAG_THRESHOLD = 4;
+
+/**
+ * Pan (drag), zoom (wheel, pinch, buttons) for an element that holds a
+ * transformed stage. Pointer capture starts only once a drag passes a few
+ * pixels, so clicks on content inside the stage still work; `wasDrag()` tells
+ * a click handler to ignore the click that ends a drag.
+ */
+export function usePanZoom<T extends HTMLElement>({
+  minZoom = 0.1,
+  maxZoom = 2.5,
+  wheel = "modifier",
+}: UsePanZoomOptions = {}) {
+  const ref = useRef<T | null>(null);
+  const [view, setViewState] = useState<PanZoomView>({ k: 1, x: 0, y: 0 });
+  const [interacting, setInteracting] = useState(false);
+  const viewRef = useRef(view);
+  const userMoved = useRef(false);
+  const pointers = useRef(new Map<number, { x: number; y: number }>());
+  const gesture = useRef<{ dragged: boolean; startX: number; startY: number; distance: number }>({
+    dragged: false,
+    startX: 0,
+    startY: 0,
+    distance: 0,
+  });
+  const lastDrag = useRef(false);
+
+  const setView = useCallback((next: PanZoomView, { user = true }: { user?: boolean } = {}) => {
+    viewRef.current = next;
+    if (user) userMoved.current = true;
+    setViewState(next);
+  }, []);
+
+  const zoomBy = useCallback(
+    (factor: number, around?: { x: number; y: number }) => {
+      const element = ref.current;
+      const px = around?.x ?? (element ? element.clientWidth / 2 : 0);
+      const py = around?.y ?? (element ? element.clientHeight / 2 : 0);
+      setView(zoomAround(viewRef.current, factor, px, py, minZoom, maxZoom));
+    },
+    [minZoom, maxZoom, setView],
+  );
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || wheel === "off") return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onWheel = (event: WheelEvent) => {
+      if (wheel === "modifier" && !event.ctrlKey && !event.metaKey) return;
+      event.preventDefault();
+      const box = element.getBoundingClientRect();
+      const factor = Math.exp(-event.deltaY * (event.deltaMode === 1 ? 0.05 : 0.0025));
+      setInteracting(true);
+      clearTimeout(timer);
+      timer = setTimeout(() => setInteracting(false), 160);
+      setView(
+        zoomAround(
+          viewRef.current,
+          factor,
+          event.clientX - box.left,
+          event.clientY - box.top,
+          minZoom,
+          maxZoom,
+        ),
+      );
+    };
+    element.addEventListener("wheel", onWheel, { passive: false });
+    return () => {
+      clearTimeout(timer);
+      element.removeEventListener("wheel", onWheel);
+    };
+  }, [wheel, minZoom, maxZoom, setView]);
+
+  const local = (event: PointerEvent<T>) => {
+    const box = event.currentTarget.getBoundingClientRect();
+    return { x: event.clientX - box.left, y: event.clientY - box.top };
+  };
+
+  const onPointerDown = (event: PointerEvent<T>) => {
+    if (event.button !== 0 && event.pointerType === "mouse") return;
+    const point = local(event);
+    pointers.current.set(event.pointerId, point);
+    if (pointers.current.size === 1) {
+      gesture.current = { dragged: false, startX: point.x, startY: point.y, distance: 0 };
+    } else if (pointers.current.size === 2) {
+      const [a, b] = [...pointers.current.values()] as [
+        { x: number; y: number },
+        { x: number; y: number },
+      ];
+      gesture.current.distance = Math.hypot(a.x - b.x, a.y - b.y);
+      gesture.current.dragged = true;
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent<T>) => {
+    const previous = pointers.current.get(event.pointerId);
+    if (!previous) return;
+    const point = local(event);
+    pointers.current.set(event.pointerId, point);
+    const state = gesture.current;
+    if (pointers.current.size >= 2) {
+      const [a, b] = [...pointers.current.values()] as [
+        { x: number; y: number },
+        { x: number; y: number },
+      ];
+      const distance = Math.hypot(a.x - b.x, a.y - b.y);
+      if (state.distance > 0) {
+        const mid = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+        setView(
+          zoomAround(viewRef.current, distance / state.distance, mid.x, mid.y, minZoom, maxZoom),
+        );
+      }
+      state.distance = distance;
+      return;
+    }
+    if (!state.dragged) {
+      if (Math.hypot(point.x - state.startX, point.y - state.startY) < DRAG_THRESHOLD) return;
+      state.dragged = true;
+      setInteracting(true);
+      event.currentTarget.setPointerCapture?.(event.pointerId);
+    }
+    const current = viewRef.current;
+    setView({
+      k: current.k,
+      x: current.x + point.x - previous.x,
+      y: current.y + point.y - previous.y,
+    });
+  };
+
+  const onPointerEnd = (event: PointerEvent<T>) => {
+    if (!pointers.current.has(event.pointerId)) return;
+    pointers.current.delete(event.pointerId);
+    if (pointers.current.size === 0) {
+      lastDrag.current = gesture.current.dragged;
+      setInteracting(false);
+    }
+  };
+
+  return {
+    ref,
+    view,
+    setView,
+    zoomBy,
+    /** True while dragging, pinching or wheel zooming: transitions should be off. */
+    interacting,
+    /** The user moved the view since the last automatic fit. */
+    userMoved,
+    /** The last pointer gesture was a drag, not a click. */
+    wasDrag: () => lastDrag.current,
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: onPointerEnd,
+      onPointerCancel: onPointerEnd,
+    },
+  };
+}

package/src/charts/core/use-series-state.ts

@@ -0,0 +1,40 @@
+"use client";
+
+import { useCallback, useState } from "react";
+
+export interface SeriesState {
+  /** Ids hidden through the legend. */
+  hidden: ReadonlySet<string>;
+  /** Series under the legend pointer or focus; the others are dimmed. */
+  highlighted: string | null;
+  toggle: (id: string) => void;
+  setHighlighted: (id: string | null) => void;
+  isHidden: (id: string) => boolean;
+  /** True when another series is highlighted. */
+  isDimmed: (id: string) => boolean;
+}
+
+/** Legend-driven visibility and highlight, shared by every chart type. */
+export function useSeriesState(initialHidden: readonly string[] = []): SeriesState {
+  const [hidden, setHidden] = useState<ReadonlySet<string>>(() => new Set(initialHidden));
+  const [highlighted, setHighlighted] = useState<string | null>(null);
+
+  const toggle = useCallback((id: string) => {
+    setHidden((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+    setHighlighted(null);
+  }, []);
+
+  return {
+    hidden,
+    highlighted,
+    toggle,
+    setHighlighted,
+    isHidden: (id) => hidden.has(id),
+    isDimmed: (id) => highlighted != null && highlighted !== id && !hidden.has(highlighted),
+  };
+}