@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/core/path.js

@@ -0,0 +1,141 @@
+function mirrorCurve(curve) {
+  if (curve === "step-before") return "step-after";
+  if (curve === "step-after") return "step-before";
+  return curve;
+}
+const round = (value) => Math.round(value * 100) / 100;
+function segments(points) {
+  const out = [];
+  let run = [];
+  for (const point of points) {
+    if (point) {
+      run.push(point);
+    } else if (run.length) {
+      out.push(run);
+      run = [];
+    }
+  }
+  if (run.length) out.push(run);
+  return out;
+}
+function monotoneTangents(points) {
+  const n = points.length;
+  if (n < 2) return [0];
+  const slopes = [];
+  const widths = [];
+  for (let k = 0; k < n - 1; k += 1) {
+    const a = points[k];
+    const b = points[k + 1];
+    const h = b.x - a.x;
+    widths.push(h);
+    slopes.push(h === 0 ? 0 : (b.y - a.y) / h);
+  }
+  const tangents = [slopes[0]];
+  for (let k = 1; k < n - 1; k += 1) {
+    const d0 = slopes[k - 1];
+    const d1 = slopes[k];
+    const h0 = widths[k - 1];
+    const h1 = widths[k];
+    tangents.push(d0 * d1 <= 0 ? 0 : 3 * (h0 + h1) / ((2 * h1 + h0) / d0 + (h1 + 2 * h0) / d1));
+  }
+  tangents.push(slopes[n - 2]);
+  return tangents;
+}
+function curveCommands(points, curve, join = false) {
+  if (!points.length) return "";
+  const first = points[0];
+  let d = `${join ? "L" : "M"}${round(first.x)},${round(first.y)}`;
+  if (curve === "step" || curve === "step-before" || curve === "step-after") {
+    for (let k = 1; k < points.length; k += 1) {
+      const a = points[k - 1];
+      const b = points[k];
+      if (curve === "step-after") {
+        d += `H${round(b.x)}V${round(b.y)}`;
+      } else if (curve === "step-before") {
+        d += `V${round(b.y)}H${round(b.x)}`;
+      } else {
+        const mid = round((a.x + b.x) / 2);
+        d += `H${mid}V${round(b.y)}H${round(b.x)}`;
+      }
+    }
+    return d;
+  }
+  if (curve === "linear" || points.length < 3) {
+    for (let k = 1; k < points.length; k += 1) {
+      const p = points[k];
+      d += `L${round(p.x)},${round(p.y)}`;
+    }
+    return d;
+  }
+  const m = monotoneTangents(points);
+  for (let k = 0; k < points.length - 1; k += 1) {
+    const a = points[k];
+    const b = points[k + 1];
+    const h = (b.x - a.x) / 3;
+    d += `C${round(a.x + h)},${round(a.y + m[k] * h)} ${round(b.x - h)},${round(
+      b.y - m[k + 1] * h
+    )} ${round(b.x)},${round(b.y)}`;
+  }
+  return d;
+}
+function linePath(points, curve = "linear") {
+  return segments(points).map((run) => curveCommands(run, curve)).join("");
+}
+function areaPath(top, bottom, curve = "linear") {
+  let d = "";
+  let start = -1;
+  const flush = (end) => {
+    if (start < 0) return;
+    const upper = top.slice(start, end);
+    const lower = bottom.slice(start, end).reverse();
+    d += `${curveCommands(upper, curve)}${curveCommands(lower, mirrorCurve(curve), true)}Z`;
+    start = -1;
+  };
+  top.forEach((point, index) => {
+    if (point && start < 0) start = index;
+    if (!point) flush(index);
+  });
+  flush(top.length);
+  return d;
+}
+function roundedRectPath(x, y, width, height, radii) {
+  const w = Math.max(0, width);
+  const h = Math.max(0, height);
+  const cap = Math.min(w, h) / 2;
+  const tl = Math.min(radii.tl, cap);
+  const tr = Math.min(radii.tr, cap);
+  const br = Math.min(radii.br, cap);
+  const bl = Math.min(radii.bl, cap);
+  const r = round;
+  return [
+    `M${r(x + tl)},${r(y)}`,
+    `H${r(x + w - tr)}`,
+    tr ? `A${r(tr)},${r(tr)} 0 0 1 ${r(x + w)},${r(y + tr)}` : "",
+    `V${r(y + h - br)}`,
+    br ? `A${r(br)},${r(br)} 0 0 1 ${r(x + w - br)},${r(y + h)}` : "",
+    `H${r(x + bl)}`,
+    bl ? `A${r(bl)},${r(bl)} 0 0 1 ${r(x)},${r(y + h - bl)}` : "",
+    `V${r(y + tl)}`,
+    tl ? `A${r(tl)},${r(tl)} 0 0 1 ${r(x + tl)},${r(y)}` : "",
+    "Z"
+  ].join("");
+}
+function barPath(x, y, width, height, radius, end) {
+  const on = (corner) => corner ? radius : 0;
+  const all = end === "all";
+  return roundedRectPath(x, y, width, height, {
+    tl: on(all || end === "top" || end === "left"),
+    tr: on(all || end === "top" || end === "right"),
+    br: on(all || end === "bottom" || end === "right"),
+    bl: on(all || end === "bottom" || end === "left")
+  });
+}
+export {
+  areaPath,
+  barPath,
+  curveCommands,
+  linePath,
+  monotoneTangents,
+  roundedRectPath,
+  segments
+};

package/dist/charts/core/pattern-defs.d.ts

@@ -0,0 +1,15 @@
+import { type ChartPattern } from "./patterns.js";
+export interface PatternDefItem {
+    /** Id the marks reference with `url(#id)` (see `patternId`). */
+    id: string;
+    pattern: ChartPattern;
+    /** Series color: a CSS color or `var()` token. */
+    color: string;
+}
+/**
+ * `<pattern>` definitions to place inside an `<svg><defs>`. Strokes and fills
+ * use the item colour through `style`, so tokens resolve per theme.
+ */
+export declare function ChartPatternDefs({ items }: {
+    items: readonly PatternDefItem[];
+}): import("react").JSX.Element;

package/dist/charts/core/pattern-defs.js

@@ -0,0 +1,83 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { resolvePattern } from "./patterns.js";
+function ChartPatternDefs({ items }) {
+  return /* @__PURE__ */ jsx(Fragment, { children: items.map(({ id, pattern, color }) => {
+    const tile = resolvePattern(pattern);
+    return /* @__PURE__ */ jsxs(
+      "pattern",
+      {
+        id,
+        patternUnits: "userSpaceOnUse",
+        width: tile.size,
+        height: tile.size,
+        children: [
+          /* @__PURE__ */ jsx(
+            "rect",
+            {
+              width: tile.size,
+              height: tile.size,
+              style: { fill: color, fillOpacity: tile.backdrop ?? 0.2 }
+            }
+          ),
+          tile.shapes.map((shape, index) => {
+            const key = index;
+            if (shape.type === "line") {
+              return /* @__PURE__ */ jsx(
+                "line",
+                {
+                  x1: shape.x1,
+                  y1: shape.y1,
+                  x2: shape.x2,
+                  y2: shape.y2,
+                  strokeWidth: shape.width ?? 1.6,
+                  style: { stroke: color }
+                },
+                key
+              );
+            }
+            if (shape.type === "circle") {
+              return /* @__PURE__ */ jsx(
+                "circle",
+                {
+                  cx: shape.cx,
+                  cy: shape.cy,
+                  r: shape.r,
+                  style: { fill: color }
+                },
+                key
+              );
+            }
+            if (shape.type === "rect") {
+              return /* @__PURE__ */ jsx(
+                "rect",
+                {
+                  x: shape.x,
+                  y: shape.y,
+                  width: shape.width,
+                  height: shape.height,
+                  style: { fill: color }
+                },
+                key
+              );
+            }
+            return /* @__PURE__ */ jsx(
+              "path",
+              {
+                d: shape.d,
+                strokeWidth: shape.width ?? 1.4,
+                strokeLinecap: "round",
+                strokeLinejoin: "round",
+                style: { fill: shape.filled ? color : "none", stroke: color }
+              },
+              key
+            );
+          })
+        ]
+      },
+      id
+    );
+  }) });
+}
+export {
+  ChartPatternDefs
+};

package/dist/charts/core/patterns.d.ts

@@ -0,0 +1,49 @@
+/**
+ * SVG pattern fills for colour-blind friendly charts. A pattern is a square
+ * tile of strokes and fills drawn in the series colour over a soft backdrop of
+ * the same colour, so the token (and therefore the theme) still decides the hue.
+ * Pure data here; `ChartPatternDefs` (pattern-defs.tsx) turns it into `<pattern>`s.
+ */
+export type PatternShape = {
+    type: "line";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    width?: number;
+} | {
+    type: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    type: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | {
+    type: "path";
+    d: string;
+    width?: number;
+    filled?: boolean;
+};
+/** A tile of `size` x `size` pixels repeated across the mark. */
+export interface PatternTile {
+    size: number;
+    shapes: readonly PatternShape[];
+    /** Opacity of the colour backdrop under the shapes (0.2 by default). */
+    backdrop?: number;
+}
+export declare const PATTERN_NAMES: readonly ["stripes", "stripes-reverse", "dots", "crosshatch", "grid", "zigzag", "checks", "diamonds", "waves"];
+export type PatternName = (typeof PATTERN_NAMES)[number];
+/** A named design, or your own tile. */
+export type ChartPattern = PatternName | PatternTile;
+/** The tile of a named design or of a custom pattern (custom tiles are clamped to a sane size). */
+export declare function resolvePattern(pattern: ChartPattern): PatternTile;
+/** Id safe for `url(#id)`: letters, digits, dashes and underscores only. */
+export declare function patternId(scope: string, key: string): string;
+/** Paint value that fills a mark with the pattern of `id`. */
+export declare function patternFill(id: string): string;
+/** Cycles the built-in designs, handy for "one pattern per series" charts. */
+export declare function patternAt(index: number): PatternName;

package/dist/charts/core/patterns.js

@@ -0,0 +1,93 @@
+const PATTERN_NAMES = [
+  "stripes",
+  "stripes-reverse",
+  "dots",
+  "crosshatch",
+  "grid",
+  "zigzag",
+  "checks",
+  "diamonds",
+  "waves"
+];
+const BUILT_IN = {
+  stripes: {
+    size: 8,
+    shapes: [
+      { type: "line", x1: 0, y1: 8, x2: 8, y2: 0, width: 2 },
+      { type: "line", x1: -2, y1: 2, x2: 2, y2: -2, width: 2 },
+      { type: "line", x1: 6, y1: 10, x2: 10, y2: 6, width: 2 }
+    ]
+  },
+  "stripes-reverse": {
+    size: 8,
+    shapes: [
+      { type: "line", x1: 0, y1: 0, x2: 8, y2: 8, width: 2 },
+      { type: "line", x1: -2, y1: 6, x2: 2, y2: 10, width: 2 },
+      { type: "line", x1: 6, y1: -2, x2: 10, y2: 2, width: 2 }
+    ]
+  },
+  dots: {
+    size: 8,
+    shapes: [
+      { type: "circle", cx: 2, cy: 2, r: 1.5 },
+      { type: "circle", cx: 6, cy: 6, r: 1.5 }
+    ]
+  },
+  crosshatch: {
+    size: 8,
+    shapes: [
+      { type: "line", x1: 0, y1: 8, x2: 8, y2: 0, width: 1.4 },
+      { type: "line", x1: 0, y1: 0, x2: 8, y2: 8, width: 1.4 },
+      { type: "line", x1: -2, y1: 2, x2: 2, y2: -2, width: 1.4 },
+      { type: "line", x1: 6, y1: 10, x2: 10, y2: 6, width: 1.4 },
+      { type: "line", x1: -2, y1: 6, x2: 2, y2: 10, width: 1.4 },
+      { type: "line", x1: 6, y1: -2, x2: 10, y2: 2, width: 1.4 }
+    ]
+  },
+  grid: {
+    size: 8,
+    shapes: [
+      { type: "line", x1: 0, y1: 0, x2: 8, y2: 0, width: 1.4 },
+      { type: "line", x1: 0, y1: 0, x2: 0, y2: 8, width: 1.4 }
+    ]
+  },
+  zigzag: {
+    size: 8,
+    shapes: [{ type: "path", d: "M0 6 L2 2 L4 6 L6 2 L8 6", width: 1.4 }]
+  },
+  checks: {
+    size: 8,
+    shapes: [
+      { type: "rect", x: 0, y: 0, width: 4, height: 4 },
+      { type: "rect", x: 4, y: 4, width: 4, height: 4 }
+    ]
+  },
+  diamonds: {
+    size: 8,
+    shapes: [{ type: "path", d: "M4 0.8 L7.2 4 L4 7.2 L0.8 4 Z", width: 1.3 }]
+  },
+  waves: {
+    size: 8,
+    shapes: [{ type: "path", d: "M0 4 Q2 0.5 4 4 T8 4", width: 1.4 }]
+  }
+};
+function resolvePattern(pattern) {
+  if (typeof pattern === "string") return BUILT_IN[pattern] ?? BUILT_IN.stripes;
+  return { ...pattern, size: Math.min(48, Math.max(2, pattern.size)) };
+}
+function patternId(scope, key) {
+  return `${scope.replace(/[^a-zA-Z0-9_-]/g, "")}-p-${key.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+function patternFill(id) {
+  return `url(#${id})`;
+}
+function patternAt(index) {
+  return PATTERN_NAMES[index % PATTERN_NAMES.length];
+}
+export {
+  PATTERN_NAMES,
+  patternAt,
+  patternFill,
+  patternId,
+  resolvePattern
+};

package/dist/charts/core/plot-overlay.d.ts

@@ -0,0 +1,36 @@
+import type { KeyboardEvent } from "react";
+export interface PlotPointer {
+    /** Pointer position relative to the plot, in pixels. */
+    x: number;
+    y: number;
+}
+export interface PlotOverlayProps {
+    /** Position and size of the plot inside the chart container. */
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    /** Accessible name (`labels.explore`). */
+    label: string;
+    /** Number of explorable points. */
+    count: number;
+    /** Active point, or null. */
+    active: number | null;
+    /** Reads the active point aloud: category and values. */
+    valueText: string;
+    onActiveChange: (index: number | null) => void;
+    /** Maps a plot-relative pointer to a point; return null to clear (hit-testing charts). */
+    indexAt: (pointer: PlotPointer) => number | null;
+    /** Which arrow keys step through the points. "both" maps Right/Down to next and Left/Up to previous. */
+    keys?: "horizontal" | "vertical" | "both";
+    /** Extra key handling, e.g. switching streams with Up/Down. Return true when handled. */
+    onKey?: (event: KeyboardEvent<HTMLDivElement>) => boolean;
+    className?: string;
+}
+/**
+ * Transparent, focusable layer over a plot: one place for pointer hover and
+ * keyboard exploration, shared by the non-cartesian charts. It is a
+ * `role="slider"` so assistive tech announces `valueText` as the arrows move.
+ * Arrows step, Home/End jump, Escape clears.
+ */
+export declare function PlotOverlay({ left, top, width, height, label, count, active, valueText, onActiveChange, indexAt, keys, onKey, className, }: PlotOverlayProps): import("react").JSX.Element;

package/dist/charts/core/plot-overlay.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { cn } from "../../utils/cn.js";
+function PlotOverlay({
+  left,
+  top,
+  width,
+  height,
+  label,
+  count,
+  active,
+  valueText,
+  onActiveChange,
+  indexAt,
+  keys = "horizontal",
+  onKey,
+  className
+}) {
+  const local = (event) => {
+    const rect = event.currentTarget.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  };
+  const move = (delta) => {
+    const from = active ?? (delta > 0 ? -1 : count);
+    onActiveChange(Math.min(count - 1, Math.max(0, from + delta)));
+  };
+  const onKeyDown = (event) => {
+    if (onKey?.(event)) {
+      event.preventDefault();
+      return;
+    }
+    const next = keys !== "vertical" && event.key === "ArrowRight" || keys !== "horizontal" && event.key === "ArrowDown";
+    const previous = keys !== "vertical" && event.key === "ArrowLeft" || keys !== "horizontal" && event.key === "ArrowUp";
+    if (next) move(1);
+    else if (previous) move(-1);
+    else if (event.key === "Home") onActiveChange(0);
+    else if (event.key === "End") onActiveChange(count - 1);
+    else if (event.key === "Escape") onActiveChange(null);
+    else return;
+    event.preventDefault();
+  };
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "slider",
+      tabIndex: 0,
+      "aria-label": label,
+      "aria-valuemin": 1,
+      "aria-valuemax": Math.max(1, count),
+      "aria-valuenow": (active ?? 0) + 1,
+      "aria-valuetext": valueText,
+      onKeyDown,
+      onFocus: () => onActiveChange(active ?? 0),
+      onBlur: () => onActiveChange(null),
+      onPointerMove: (event) => onActiveChange(indexAt(local(event))),
+      onPointerDown: (event) => onActiveChange(indexAt(local(event))),
+      onPointerLeave: () => onActiveChange(null),
+      className: cn(
+        "absolute rounded-xs outline-none focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-4",
+        className
+      ),
+      style: { left, top, width, height }
+    }
+  );
+}
+export {
+  PlotOverlay
+};

package/dist/charts/core/polar.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Polar geometry shared by the radial charts (donut, pie, radial bars, gauge,
+ * radar, polar area, funnel). Angles are radians with 0 at 12 o'clock, growing
+ * clockwise, so a gauge or a donut reads the way a clock does.
+ */
+import type { Point } from "./path.js";
+export declare const TAU: number;
+export declare function degToRad(degrees: number): number;
+export declare function radToDeg(radians: number): number;
+/** Point at `radius` from (cx, cy) in the direction of `angle`. */
+export declare function polarPoint(cx: number, cy: number, radius: number, angle: number): Point;
+/** Angle of the vector (cx, cy) -> (x, y), in [0, TAU). */
+export declare function angleOf(cx: number, cy: number, x: number, y: number): number;
+/** Wraps any angle into [0, TAU). */
+export declare function normalizeAngle(angle: number): number;
+/** Index of the equal-width slot centred on `offset + i * TAU / count` that `angle` falls in. */
+export declare function slotAt(angle: number, count: number, offset?: number): number;
+export interface ArcSlice {
+    index: number;
+    value: number;
+    /** Share of the total, 0-1. */
+    fraction: number;
+    /** Angles after the gap is taken off both sides. */
+    start: number;
+    end: number;
+    /** Middle of the slice before the gap (the label direction). */
+    mid: number;
+}
+export interface SliceOptions {
+    startAngle?: number;
+    endAngle?: number;
+    /** Gap between neighbours, in radians (split between both sides). */
+    padAngle?: number;
+}
+/**
+ * Splits [startAngle, endAngle] proportionally to `values`. Non-finite and
+ * non-positive values get a zero-width slice. A slice narrower than the gap
+ * collapses onto its middle instead of inverting.
+ */
+export declare function sliceAngles(values: readonly number[], options?: SliceOptions): ArcSlice[];
+export interface ArcSpec {
+    cx: number;
+    cy: number;
+    innerRadius: number;
+    outerRadius: number;
+    startAngle: number;
+    endAngle: number;
+    /** Radius of the rounded corners; clamped so the shape stays valid. */
+    cornerRadius?: number;
+}
+/**
+ * Closed path of an annular sector (a pie wedge when `innerRadius` is 0),
+ * with optional rounded corners. The corners are circles tangent to both the
+ * arc and the radial edge, so rounding never changes the gap between slices.
+ */
+export declare function arcPath(spec: ArcSpec): string;
+/**
+ * Open centre-line arc, meant to be stroked (`strokeLinecap="round"` gives
+ * the rounded ends). Used by progress rings, tracks and gauge bands.
+ */
+export declare function arcLine(cx: number, cy: number, radius: number, startAngle: number, endAngle: number): string;
+export interface LabelBox {
+    /** Preferred vertical centre. */
+    y: number;
+    /** Height the label needs. */
+    height: number;
+}
+/**
+ * Vertical collision avoidance for a column of labels. Returns the adjusted
+ * centres in the original order: labels are pushed down until they clear the
+ * one above, then pushed back up from `max`, so nothing overlaps and the
+ * column stays inside [min, max]. A column taller than the room keeps its
+ * order and starts at `min`.
+ */
+export declare function spreadLabels(boxes: readonly LabelBox[], min: number, max: number, gap?: number): number[];
+export interface FunnelStage {
+    index: number;
+    value: number;
+    /** Main-axis start and end of the stage. */
+    from: number;
+    to: number;
+    /** Cross-axis full widths at `from` and at `to`. */
+    widthFrom: number;
+    widthTo: number;
+    /** Share of the first stage, 0-1. */
+    ofFirst: number;
+    /** Share of the previous stage, null for the first one. */
+    conversion: number | null;
+}
+export interface FunnelOptions {
+    /** Main-axis length available. */
+    length: number;
+    /** Cross-axis width of the largest stage. */
+    thickness: number;
+    gap?: number;
+    /** `funnel` keeps a flat neck; `pyramid` tapers the last stage to a point. */
+    variant?: "funnel" | "pyramid";
+    /** Width of the last stage's far edge relative to its own width (funnel only). */
+    neck?: number;
+    /**
+     * `true` (default) narrows each stage towards the next one (trapezoids, one
+     * continuous outline); `false` keeps every stage a straight bar of its own width.
+     */
+    tapered?: boolean;
+}
+/**
+ * Stage geometry along one axis: each stage spans its slice of `length`,
+ * starts as wide as its own value and ends as wide as the next stage, so the
+ * outline is continuous. Widths are proportional to value.
+ */
+export declare function funnelStages(values: readonly number[], options: FunnelOptions): FunnelStage[];