@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/charts/core/breadcrumb.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { cn } from "../../utils/cn.js";
+
+export interface ChartBreadcrumbItem {
+  id: string;
+  name: string;
+}
+
+export interface ChartBreadcrumbProps {
+  /** Root first, current node last. */
+  items: readonly ChartBreadcrumbItem[];
+  onSelect: (id: string) => void;
+  /** Accessible name of the navigation landmark. */
+  label: string;
+  className?: string;
+}
+
+/**
+ * Drill-down path of a hierarchy chart. Every ancestor is a button that
+ * zooms back out to it; the current node is marked with `aria-current`.
+ */
+export function ChartBreadcrumb({ items, onSelect, label, className }: ChartBreadcrumbProps) {
+  return (
+    <nav aria-label={label} className={cn("min-w-0", className)}>
+      <ol className="m-0 flex list-none flex-wrap items-center gap-1 p-0 text-[12px]">
+        {items.map((item, index) => {
+          const current = index === items.length - 1;
+          return (
+            <li key={item.id} className="flex min-w-0 max-w-[12rem] items-center gap-1">
+              {index > 0 ? (
+                <svg
+                  aria-hidden="true"
+                  width="12"
+                  height="12"
+                  viewBox="0 0 24 24"
+                  className="text-ink-3"
+                >
+                  <path
+                    d="m9 6 6 6-6 6"
+                    fill="none"
+                    stroke="currentColor"
+                    strokeWidth="2.2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              ) : null}
+              {current ? (
+                <span aria-current="page" className="truncate font-bold text-ink">
+                  {item.name}
+                </span>
+              ) : (
+                <button
+                  type="button"
+                  onClick={() => onSelect(item.id)}
+                  className="cursor-pointer truncate rounded-xs border-0 bg-transparent p-0 font-semibold text-ink-3 outline-none hover:text-ink focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-2"
+                >
+                  {item.name}
+                </button>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/src/charts/core/cartesian/annotations.tsx

@@ -0,0 +1,161 @@
+import { memo } from "react";
+import { estimateTextWidth } from "../axes.js";
+import { TONE_COLORS } from "../palette.js";
+import type { AnnotationGeometry } from "./layout.js";
+
+export interface AnnotationLayerProps {
+  annotations: readonly AnnotationGeometry[];
+  width: number;
+  height: number;
+  /** "under" draws range bands behind the data, "over" draws lines and labels above it. */
+  layer: "under" | "over";
+}
+
+function Pill({
+  x,
+  y,
+  text,
+  ink,
+  soft,
+  anchor,
+}: {
+  x: number;
+  y: number;
+  text: string;
+  ink: string;
+  soft: string;
+  anchor: "start" | "middle" | "end";
+}) {
+  const width = estimateTextWidth(text, 10.5) + 12;
+  const left = anchor === "end" ? x - width : anchor === "middle" ? x - width / 2 : x;
+  return (
+    <g>
+      <rect x={left} y={y - 9} width={width} height={18} rx={9} style={{ fill: soft }} />
+      <text
+        x={left + width / 2}
+        y={y}
+        dy="0.35em"
+        textAnchor="middle"
+        className="font-bold text-[10.5px]"
+        style={{ fill: ink }}
+      >
+        {text}
+      </text>
+    </g>
+  );
+}
+
+/** Threshold lines and highlighted ranges with their labels. */
+export const AnnotationLayer = memo(function AnnotationLayer({
+  annotations,
+  width,
+  height,
+  layer,
+}: AnnotationLayerProps) {
+  const items = annotations.filter((note) => (layer === "under") === (note.kind === "range"));
+  if (!items.length) return null;
+  return (
+    <g>
+      {items.map((note) => {
+        const { ink, soft } = TONE_COLORS[note.tone];
+        if (!("direction" in note)) {
+          const half = note.label ? (estimateTextWidth(note.label, 10.5) + 12) / 2 : 0;
+          const x = Math.min(Math.max(note.x, half), Math.max(half, width - half));
+          const above = note.y > 26;
+          const y = note.kind === "point" ? note.y + (above ? -16 : 16) : note.y;
+          return (
+            <g key={note.key} data-annotation={note.kind}>
+              {note.kind === "point" ? (
+                <circle
+                  cx={note.x}
+                  cy={note.y}
+                  r={5}
+                  strokeWidth={2.5}
+                  style={{ fill: ink, stroke: "var(--surface)" }}
+                />
+              ) : null}
+              {note.label ? (
+                note.kind === "point" ? (
+                  <Pill x={x} y={y} text={note.label} ink={ink} soft={soft} anchor="middle" />
+                ) : (
+                  <text
+                    x={x}
+                    y={y}
+                    dy="0.35em"
+                    textAnchor="middle"
+                    paintOrder="stroke"
+                    strokeWidth={3}
+                    strokeLinejoin="round"
+                    className="stroke-surface font-bold text-[11px]"
+                    style={{ fill: ink }}
+                  >
+                    {note.label}
+                  </text>
+                )
+              ) : null}
+            </g>
+          );
+        }
+        const horizontal = note.direction === "horizontal";
+        if (note.kind === "range") {
+          return (
+            <g key={note.key}>
+              <rect
+                x={horizontal ? 0 : note.from}
+                y={horizontal ? note.from : 0}
+                width={horizontal ? width : note.to - note.from}
+                height={horizontal ? note.to - note.from : height}
+                style={{ fill: ink, fillOpacity: 0.07 }}
+              />
+              {note.label ? (
+                <text
+                  x={(horizontal ? 0 : note.from) + 6}
+                  y={(horizontal ? note.from : 0) + 13}
+                  className="font-bold text-[10.5px]"
+                  style={{ fill: ink }}
+                >
+                  {note.label}
+                </text>
+              ) : null}
+            </g>
+          );
+        }
+        return (
+          <g key={note.key}>
+            <line
+              x1={horizontal ? 0 : note.from}
+              x2={horizontal ? width : note.from}
+              y1={horizontal ? note.from : 0}
+              y2={horizontal ? note.from : height}
+              strokeWidth={1.25}
+              strokeDasharray="5 4"
+              shapeRendering="crispEdges"
+              style={{ stroke: ink }}
+            />
+            {note.label ? (
+              horizontal ? (
+                <Pill
+                  x={width - 2}
+                  y={note.from}
+                  text={note.label}
+                  ink={ink}
+                  soft={soft}
+                  anchor="end"
+                />
+              ) : (
+                <Pill
+                  x={note.from + (note.from > width * 0.7 ? -4 : 4)}
+                  y={11}
+                  text={note.label}
+                  ink={ink}
+                  soft={soft}
+                  anchor={note.from > width * 0.7 ? "end" : "start"}
+                />
+              )
+            ) : null}
+          </g>
+        );
+      })}
+    </g>
+  );
+});

package/src/charts/core/cartesian/axis-stack.ts

@@ -0,0 +1,88 @@
+import type { ValueAxisOptions } from "../types.js";
+
+/** A value axis of a cartesian chart: `id` is what a series' `axis` refers to. */
+export interface CartesianAxisSpec extends ValueAxisOptions {
+  id: string;
+  /** Side of the plot; "left" for the `"left"` id, "right" for any other. */
+  side?: "left" | "right";
+  /** Color of the tick labels and axis line, to match the series it measures. */
+  color?: string;
+}
+
+export interface ResolvedAxis {
+  id: string;
+  side: "left" | "right";
+  options: ValueAxisOptions;
+  color?: string;
+}
+
+/**
+ * Axes in drawing order. `yAxis` and `rightAxis` are sugar for the axes with
+ * id "left" and "right"; `extra` entries merge into those or add more axes
+ * (on the right unless they say otherwise). Axes no series uses are dropped,
+ * and the first remaining one is the primary axis (grid, zero line, bars).
+ */
+export function resolveAxes(
+  yAxis: ValueAxisOptions,
+  rightAxis: ValueAxisOptions,
+  extra: readonly CartesianAxisSpec[],
+  used: ReadonlySet<string>,
+): ResolvedAxis[] {
+  const list: ResolvedAxis[] = [
+    { id: "left", side: "left", options: yAxis },
+    { id: "right", side: "right", options: rightAxis },
+  ];
+  for (const { id, side, color, ...options } of extra) {
+    const at = list.findIndex((axis) => axis.id === id);
+    const current = list[at];
+    if (current) {
+      list[at] = {
+        ...current,
+        side: side ?? current.side,
+        color: color ?? current.color,
+        options: { ...current.options, ...options },
+      };
+    } else {
+      list.push({ id, side: side ?? "right", options, color });
+    }
+  }
+  const others = list.some((axis) => axis.id !== "left" && used.has(axis.id));
+  return list.filter((axis) => used.has(axis.id) || (axis.id === "left" && !others));
+}
+
+export interface AxisSlot {
+  id: string;
+  side: "left" | "right";
+  /** Pixels the axis needs beside the plot: its widest label plus padding. */
+  width: number;
+}
+
+export interface AxisStack {
+  left: number;
+  right: number;
+  /** Distance of each axis from the plot edge it hangs on; later axes sit further out. */
+  offsets: Map<string, number>;
+}
+
+/**
+ * Margins and offsets for axes that stack outward from the plot on each side,
+ * in the order given. The left margin never drops below `minLeft`; with no
+ * right axis the right margin is `rightFallback` (room for the last x label).
+ */
+export function stackAxes(
+  slots: readonly AxisSlot[],
+  { minLeft, rightFallback }: { minLeft: number; rightFallback: number },
+): AxisStack {
+  const used = { left: 0, right: 0 };
+  const offsets = new Map<string, number>();
+  for (const slot of slots) {
+    offsets.set(slot.id, used[slot.side]);
+    used[slot.side] += slot.width;
+  }
+  const hasRight = slots.some((slot) => slot.side === "right");
+  return {
+    left: Math.max(minLeft, used.left),
+    right: hasRight ? used.right : rightFallback,
+    offsets,
+  };
+}

package/src/charts/core/cartesian/brush.tsx

@@ -0,0 +1,241 @@
+"use client";
+
+import { type KeyboardEvent, type PointerEvent, useMemo, useRef } from "react";
+import { cn } from "../../../utils/cn.js";
+import { areaPath, linePath, type Point } from "../path.js";
+import { pointScale } from "../scales/band.js";
+import { extent } from "../scales/linear.js";
+
+export type IndexRange = readonly [number, number];
+
+export interface ChartBrushProps {
+  /** Total number of categories (the full, un-zoomed data). */
+  count: number;
+  /** Full-length series drawn as the overview. */
+  series: ReadonlyArray<{ id: string; color: string; data: ReadonlyArray<number | null> }>;
+  /** Original category index of each entry of `series` when the series were downsampled. */
+  indices?: readonly number[];
+  /** Selected window, inclusive indices. */
+  range: IndexRange;
+  onChange: (range: IndexRange) => void;
+  width: number;
+  /** Align with the plot above. */
+  left: number;
+  right: number;
+  height?: number;
+  label: string;
+  /** Text for screen readers describing the window, e.g. "6 oct – 20 oct". */
+  valueText: string;
+  className?: string;
+}
+
+type DragMode =
+  | { kind: "start" }
+  | { kind: "end" }
+  | { kind: "move"; offset: number }
+  | { kind: "new"; anchor: number };
+
+const MIN_SPAN = 1;
+
+/**
+ * Overview of the whole series with a draggable window. Drag the window to
+ * pan, its handles to resize, or anywhere outside to draw a new window.
+ * Keyboard: arrows pan, Shift+arrows resize the end, Home/End jump.
+ */
+export function ChartBrush({
+  count,
+  series,
+  indices,
+  range,
+  onChange,
+  width,
+  left,
+  right,
+  height = 52,
+  label,
+  valueText,
+  className,
+}: ChartBrushProps) {
+  const innerWidth = Math.max(10, width - left - right);
+  const scale = useMemo(() => pointScale({ count, range: [0, innerWidth] }), [count, innerWidth]);
+  const drag = useRef<DragMode | null>(null);
+  const latest = useRef<IndexRange>(range);
+  latest.current = range;
+
+  const paths = useMemo(() => {
+    const domain = extent(series.flatMap((item) => item.data)) ?? [0, 1];
+    const lo = Math.min(0, domain[0]);
+    const span = domain[1] - lo || 1;
+    const y = (value: number) => height - 6 - ((value - lo) / span) * (height - 14);
+    return series.map((item, index) => {
+      const at = (i: number) => scale.center(indices ? (indices[i] as number) : i);
+      const points: Array<Point | null> = item.data.map((value, i) =>
+        value == null ? null : { x: at(i), y: y(value) },
+      );
+      const bottom = points.map((point, i) => ({ x: point?.x ?? at(i), y: height - 6 }));
+      return {
+        id: item.id,
+        color: item.color,
+        line: linePath(points, "smooth"),
+        area: index === 0 ? areaPath(points, bottom, "smooth") : undefined,
+      };
+    });
+  }, [series, indices, scale, height]);
+
+  const [start, end] = range;
+  const x0 = scale.center(start);
+  const x1 = scale.center(end);
+  const clampRange = (a: number, b: number): IndexRange => {
+    const lo = Math.max(0, Math.min(a, b));
+    const hi = Math.min(count - 1, Math.max(a, b));
+    if (hi - lo >= MIN_SPAN) return [lo, hi];
+    return lo + MIN_SPAN <= count - 1 ? [lo, lo + MIN_SPAN] : [Math.max(0, hi - MIN_SPAN), hi];
+  };
+
+  const localX = (event: PointerEvent<SVGSVGElement>) =>
+    event.clientX - event.currentTarget.getBoundingClientRect().left - left;
+
+  const onPointerDown = (event: PointerEvent<SVGSVGElement>) => {
+    if (event.button !== 0) return;
+    const x = localX(event);
+    if (Math.abs(x - x0) <= 10) drag.current = { kind: "start" };
+    else if (Math.abs(x - x1) <= 10) drag.current = { kind: "end" };
+    else if (x > x0 && x < x1) drag.current = { kind: "move", offset: scale.indexAt(x) - start };
+    else drag.current = { kind: "new", anchor: scale.indexAt(x) };
+    event.currentTarget.setPointerCapture(event.pointerId);
+    event.preventDefault();
+  };
+
+  const onPointerMove = (event: PointerEvent<SVGSVGElement>) => {
+    const mode = drag.current;
+    if (!mode) return;
+    const index = scale.indexAt(localX(event));
+    if (mode.kind === "start") onChange(clampRange(Math.min(index, end - MIN_SPAN), end));
+    else if (mode.kind === "end") onChange(clampRange(start, Math.max(index, start + MIN_SPAN)));
+    else if (mode.kind === "new") onChange(clampRange(mode.anchor, index));
+    else {
+      const span = end - start;
+      const lo = Math.min(Math.max(0, index - mode.offset), count - 1 - span);
+      if (lo !== start) onChange([lo, lo + span]);
+    }
+  };
+
+  const onPointerUp = (event: PointerEvent<SVGSVGElement>) => {
+    drag.current = null;
+    if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    // Read the latest window: key repeats can arrive before the parent re-renders.
+    const [from, to] = latest.current;
+    const span = to - from;
+    const emit = (next: IndexRange) => {
+      latest.current = next;
+      onChange(next);
+    };
+    const stepBy = (delta: number) => {
+      if (event.shiftKey) return emit(clampRange(from, Math.max(from + MIN_SPAN, to + delta)));
+      const lo = Math.min(Math.max(0, from + delta), count - 1 - span);
+      emit([lo, lo + span]);
+    };
+    if (event.key === "ArrowRight" || event.key === "ArrowUp") stepBy(1);
+    else if (event.key === "ArrowLeft" || event.key === "ArrowDown") stepBy(-1);
+    else if (event.key === "Home") emit([0, span]);
+    else if (event.key === "End") emit([count - 1 - span, count - 1]);
+    else return;
+    event.preventDefault();
+  };
+
+  return (
+    <div
+      role="slider"
+      tabIndex={0}
+      aria-label={label}
+      aria-valuemin={0}
+      aria-valuemax={count - 1}
+      aria-valuenow={start}
+      aria-valuetext={valueText}
+      onKeyDown={onKeyDown}
+      className={cn(
+        "relative w-full touch-none select-none rounded-event outline-none focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-2",
+        className,
+      )}
+      style={{ height }}
+    >
+      <svg
+        aria-hidden="true"
+        width={width}
+        height={height}
+        className="block cursor-crosshair overflow-visible"
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+        onPointerCancel={onPointerUp}
+      >
+        <g transform={`translate(${left},0)`}>
+          <rect
+            x={0}
+            y={0.5}
+            width={innerWidth}
+            height={height - 1}
+            rx={10}
+            style={{ fill: "var(--surface-2)", fillOpacity: 0.5 }}
+          />
+          {paths.map((path) => (
+            <g key={path.id}>
+              {path.area ? (
+                <path d={path.area} style={{ fill: path.color, fillOpacity: 0.14 }} />
+              ) : null}
+              <path
+                d={path.line}
+                fill="none"
+                strokeWidth={1.25}
+                style={{ stroke: path.color, strokeOpacity: 0.85 }}
+              />
+            </g>
+          ))}
+          <rect
+            x={0}
+            y={0}
+            width={Math.max(0, x0)}
+            height={height}
+            style={{ fill: "var(--surface)", fillOpacity: 0.72 }}
+          />
+          <rect
+            x={x1}
+            y={0}
+            width={Math.max(0, innerWidth - x1)}
+            height={height}
+            style={{ fill: "var(--surface)", fillOpacity: 0.72 }}
+          />
+          <rect
+            x={x0}
+            y={0.5}
+            width={Math.max(0, x1 - x0)}
+            height={height - 1}
+            rx={8}
+            className="cursor-grab"
+            strokeWidth={1.25}
+            style={{ fill: "var(--accent)", fillOpacity: 0.1, stroke: "var(--accent-word)" }}
+          />
+          {[x0, x1].map((x, index) => (
+            <rect
+              // biome-ignore lint/suspicious/noArrayIndexKey: always two handles, start then end.
+              key={index}
+              x={x - 4}
+              y={height / 2 - 12}
+              width={8}
+              height={24}
+              rx={4}
+              className="cursor-ew-resize"
+              strokeWidth={1.25}
+              style={{ fill: "var(--float)", stroke: "var(--accent-word)" }}
+            />
+          ))}
+        </g>
+      </svg>
+    </div>
+  );
+}