@jcsoftdev/ui 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,458 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useCallback, useMemo, useRef } from "react";
+import { cn } from "../../utils/cn.js";
+import { DECORATIVE } from "../core/a11y.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat } from "../core/format.js";
+import { EASE_OUT, fadeIn, useAnimatedNumber, useEntryAnimation } from "../core/motion.js";
+import { TONE_COLORS } from "../core/palette.js";
+import { arcLine, degToRad, polarPoint, radToDeg } from "../core/polar.js";
+import { ChartTooltip } from "../core/tooltip.js";
+import { resolveLabels } from "../core/types.js";
+import { useIndexNavigation } from "../core/use-index-navigation.js";
+const BASE_TONE = "accent";
+function rangeColor(range) {
+  return range.color ?? TONE_COLORS[range.tone ?? BASE_TONE].ink;
+}
+function GaugeChart({
+  title,
+  description,
+  value,
+  min = 0,
+  max = 100,
+  variant = "semi",
+  mode = "progress",
+  ranges,
+  height,
+  aspectRatio,
+  thickness = 18,
+  roundedCaps = true,
+  ticks = 0,
+  tickMarks = false,
+  minorTicks = 4,
+  centerContent,
+  minMaxLabels = true,
+  label,
+  valueFormat,
+  tooltip = true,
+  loading = false,
+  animate = true,
+  labels: labelsProp,
+  className
+}) {
+  const labels = resolveLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const frameHeight = height ?? (variant === "semi" ? 230 : 290);
+  const bands = ranges ?? [];
+  const empty = !Number.isFinite(value) || !(max > min);
+  const table = /* @__PURE__ */ jsx(
+    ChartDataTable,
+    {
+      caption: description ? `${title}. ${description}` : title,
+      categoryHeader: labels.category,
+      categories: [
+        labels.value,
+        ...bands.map((band) => band.label ?? `${format(band.from)} \u2013 ${format(band.to)}`)
+      ],
+      columns: [
+        {
+          id: "value",
+          name: labels.value,
+          values: [
+            format(value),
+            ...bands.map((band) => `${format(band.from)} \u2013 ${format(band.to)}`)
+          ]
+        }
+      ]
+    }
+  );
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: frameHeight,
+      aspectRatio,
+      labels,
+      loading,
+      empty,
+      skeleton: "ring",
+      table,
+      className,
+      children: (width, measuredHeight) => /* @__PURE__ */ jsx(
+        GaugePlot,
+        {
+          width,
+          height: measuredHeight,
+          title,
+          value,
+          min,
+          max,
+          variant,
+          mode,
+          bands,
+          thickness,
+          roundedCaps,
+          ticks,
+          tickMarks,
+          minorTicks: Math.max(0, Math.round(minorTicks)),
+          centerContent,
+          minMaxLabels,
+          caption: label,
+          format,
+          tooltip,
+          animate,
+          labels
+        }
+      )
+    }
+  );
+}
+function GaugePlot({
+  width,
+  height,
+  title,
+  value,
+  min,
+  max,
+  variant,
+  mode,
+  bands,
+  thickness,
+  roundedCaps,
+  ticks,
+  tickMarks,
+  minorTicks,
+  centerContent,
+  minMaxLabels,
+  caption,
+  format,
+  tooltip,
+  animate,
+  labels
+}) {
+  const svgRef = useRef(null);
+  const shown = useAnimatedNumber(value, { from: min, disabled: !animate });
+  const items = bands.length > 0 ? bands.length : 1;
+  const nav = useIndexNavigation(items, { wrap: false });
+  const half = variant === "semi" ? 90 : 135;
+  const a0 = degToRad(-half);
+  const a1 = degToRad(half);
+  const span = a1 - a0;
+  const needle = mode === "needle";
+  const reserve = variant === "semi" ? needle ? 52 : 30 : needle ? 40 : 16;
+  const pad = 12;
+  const tail = variant === "semi" ? 0 : Math.sin(degToRad(45));
+  const radius = Math.max(
+    40,
+    Math.min(width / 2 - pad - (minMaxLabels ? 6 : 0), (height - pad - reserve) / (1 + tail))
+  );
+  const band = Math.min(thickness, radius * 0.4);
+  const extent = radius * (1 + tail) + reserve;
+  const cx = width / 2;
+  const cy = Math.max(pad + radius, (height - extent) / 2 + radius);
+  const mid = radius - band / 2;
+  const toFraction = (v) => Math.min(1, Math.max(0, (v - min) / (max - min)));
+  const angleFor = useCallback(
+    (v) => a0 + span * Math.min(1, Math.max(0, (v - min) / (max - min))),
+    [a0, span, min, max]
+  );
+  const capAngle = roundedCaps ? band / 2 / mid : 0;
+  const fraction = toFraction(shown);
+  const active = bands.find((item) => shown >= item.from && shown <= item.to);
+  const valueColor = active ? rangeColor(active) : "var(--accent-word)";
+  const progressEnd = a0 + capAngle + (span - 2 * capAngle) * fraction;
+  const bandPaths = useMemo(
+    () => bands.map((item) => {
+      const from = angleFor(Math.min(item.from, item.to)) + 6e-3;
+      const to = angleFor(Math.max(item.from, item.to)) - 6e-3;
+      return arcLine(cx, cy, mid, from, Math.max(from + 2e-3, to));
+    }),
+    [bands, cx, cy, mid, angleFor]
+  );
+  const tickLabels = useMemo(() => {
+    if (ticks < 1) return [];
+    return Array.from({ length: ticks + 1 }, (_, i) => {
+      const v = min + (max - min) * i / ticks;
+      const point = polarPoint(cx, cy, radius - band - (tickMarks ? 20 : 12), angleFor(v));
+      return { v, ...point };
+    });
+  }, [ticks, tickMarks, min, max, cx, cy, radius, band, angleFor]);
+  const tickLines = useMemo(() => {
+    if (!tickMarks) return "";
+    const divisions = Math.max(1, ticks);
+    const steps = divisions * (minorTicks + 1);
+    const inner = radius - band - 3;
+    let d = "";
+    for (let i = 0; i <= steps; i++) {
+      const major = i % (minorTicks + 1) === 0;
+      const angle = angleFor(min + (max - min) * i / steps);
+      const from = polarPoint(cx, cy, inner, angle);
+      const to = polarPoint(cx, cy, inner - (major ? 8 : 4), angle);
+      d += `M${from.x.toFixed(2)} ${from.y.toFixed(2)}L${to.x.toFixed(2)} ${to.y.toFixed(2)}`;
+    }
+    return d;
+  }, [tickMarks, ticks, minorTicks, min, max, cx, cy, radius, band, angleFor]);
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      root.querySelectorAll("[data-band]").forEach((node, i) => {
+        node.animate([{ opacity: 0 }, { opacity: 1 }], {
+          duration: 500,
+          delay: i * 90,
+          easing: EASE_OUT,
+          fill: "backwards"
+        });
+      });
+      root.querySelectorAll("[data-fade]").forEach((node) => {
+        fadeIn(node, 420, 200);
+      });
+    },
+    { disabled: !animate }
+  );
+  const valueSize = Math.round(Math.min(40, Math.max(20, radius * 0.34)));
+  const captionSize = 12;
+  const valueY = needle ? cy + 22 + valueSize * 0.8 : variant === "semi" ? cy - 6 : cy + valueSize * 0.3;
+  const captionY = needle ? valueY + 6 + captionSize : valueY + 8 + captionSize;
+  const focused = nav.active != null ? nav.active : null;
+  const focusedBand = bands.length > 0 && focused != null ? bands[focused] : void 0;
+  const rows = focusedBand ? [
+    {
+      id: `${focused}`,
+      name: focusedBand.label ?? `${format(focusedBand.from)} \u2013 ${format(focusedBand.to)}`,
+      value: `${format(focusedBand.from)} \u2013 ${format(focusedBand.to)}`,
+      color: rangeColor(focusedBand),
+      shape: "square",
+      note: value >= focusedBand.from && value <= focusedBand.to ? labels.value : void 0
+    }
+  ] : focused != null ? [
+    {
+      id: "value",
+      name: caption ?? title,
+      value: format(value),
+      color: valueColor,
+      shape: "dot"
+    }
+  ] : [];
+  const anchor = nav.pointer ?? (focused != null ? focusedBand ? polarPoint(cx, cy, mid, angleFor((focusedBand.from + focusedBand.to) / 2)) : polarPoint(cx, cy, mid, progressEnd) : null);
+  const valueText = focusedBand ? `${focusedBand.label ?? ""} ${format(focusedBand.from)} \u2013 ${format(focusedBand.to)}`.trim() : `${caption ?? title}: ${format(value)}${active?.label ? `, ${active.label}` : ""}`;
+  const endPoint = (angle) => polarPoint(cx, cy, mid, angle);
+  const minPoint = endPoint(a0);
+  const maxPoint = endPoint(a1);
+  return /* @__PURE__ */ jsxs("div", { ref: nav.ref, className: "relative", style: { width, height }, children: [
+    /* @__PURE__ */ jsxs(
+      "svg",
+      {
+        ref: svgRef,
+        role: "img",
+        "aria-label": `${title}: ${format(value)}`,
+        width,
+        height,
+        className: "block overflow-visible",
+        children: [
+          bands.length === 0 ? /* @__PURE__ */ jsx(
+            "path",
+            {
+              d: arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle),
+              fill: "none",
+              strokeWidth: band,
+              strokeLinecap: roundedCaps ? "round" : "butt",
+              style: { stroke: "var(--chart-grid)" }
+            }
+          ) : bandPaths.map((path, index) => {
+            const item = bands[index];
+            if (!item || !path) return null;
+            return /* @__PURE__ */ jsx(
+              BandMark,
+              {
+                d: path,
+                width: band,
+                color: rangeColor(item),
+                opacity: needle ? 0.92 : 0.26,
+                dimmed: focused != null && focused !== index,
+                onEnter: (event) => nav.hover(index, event),
+                onLeave: nav.leave
+              },
+              index
+            );
+          }),
+          !needle && fraction > 0 ? /* @__PURE__ */ jsx(
+            "path",
+            {
+              d: arcLine(cx, cy, mid, a0 + capAngle, Math.max(progressEnd, a0 + capAngle + 1e-3)),
+              fill: "none",
+              strokeWidth: band,
+              strokeLinecap: roundedCaps ? "round" : "butt",
+              className: "pointer-events-none",
+              style: { stroke: valueColor }
+            }
+          ) : null,
+          tickLines ? /* @__PURE__ */ jsx(
+            "path",
+            {
+              d: tickLines,
+              fill: "none",
+              strokeWidth: 1.4,
+              strokeLinecap: "round",
+              ...DECORATIVE,
+              className: "pointer-events-none",
+              style: { stroke: "var(--ink-3)", strokeOpacity: 0.7 }
+            }
+          ) : null,
+          tickLabels.map((tick) => /* @__PURE__ */ jsx(
+            "text",
+            {
+              "data-fade": "",
+              x: tick.x,
+              y: tick.y,
+              textAnchor: "middle",
+              dominantBaseline: "central",
+              ...DECORATIVE,
+              className: "fill-ink-3 font-medium text-[10px] tabular-nums",
+              children: format(tick.v)
+            },
+            tick.v
+          )),
+          needle ? /* @__PURE__ */ jsxs(
+            "g",
+            {
+              className: "pointer-events-none",
+              style: {
+                transform: `rotate(${Math.round(radToDeg(angleFor(shown)) * 100) / 100}deg)`,
+                transformOrigin: `${cx}px ${cy}px`
+              },
+              children: [
+                /* @__PURE__ */ jsx(
+                  "path",
+                  {
+                    d: `M${cx - 4} ${cy} L${cx} ${cy - (mid + band * 0.3)} L${cx + 4} ${cy} Z`,
+                    style: { fill: "var(--ink)" }
+                  }
+                ),
+                /* @__PURE__ */ jsx("circle", { cx, cy, r: 8, style: { fill: "var(--ink)" } }),
+                /* @__PURE__ */ jsx("circle", { cx, cy, r: 3, style: { fill: "var(--surface)" } })
+              ]
+            }
+          ) : null,
+          minMaxLabels ? /* @__PURE__ */ jsxs("g", { ...DECORATIVE, className: "pointer-events-none", children: [
+            /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: minPoint.x,
+                y: minPoint.y + band / 2 + 15,
+                textAnchor: "middle",
+                className: "fill-ink-3 font-semibold text-[11px] tabular-nums",
+                children: format(min)
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: maxPoint.x,
+                y: maxPoint.y + band / 2 + 15,
+                textAnchor: "middle",
+                className: "fill-ink-3 font-semibold text-[11px] tabular-nums",
+                children: format(max)
+              }
+            )
+          ] }) : null,
+          centerContent ? null : /* @__PURE__ */ jsxs("g", { "data-fade": "", ...DECORATIVE, textAnchor: "middle", className: "pointer-events-none", children: [
+            /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: cx,
+                y: valueY,
+                className: "fill-ink font-bold tabular-nums",
+                style: { fontSize: valueSize },
+                children: format(shown)
+              }
+            ),
+            caption ? /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: cx,
+                y: captionY,
+                className: "fill-ink-3 font-semibold",
+                style: { fontSize: captionSize },
+                children: caption
+              }
+            ) : null,
+            active?.label && bands.length > 0 ? /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: cx,
+                y: caption ? captionY + 16 : captionY,
+                className: "font-bold text-[11px]",
+                style: { fill: valueColor },
+                children: active.label
+              }
+            ) : null
+          ] })
+        ]
+      }
+    ),
+    centerContent ? /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "pointer-events-none absolute flex flex-col items-center text-center",
+        style: {
+          left: cx,
+          top: needle ? cy + 22 : variant === "semi" ? cy - 6 : cy,
+          width: Math.max(40, radius * 1.5),
+          transform: needle ? "translate(-50%, 0)" : variant === "semi" ? "translate(-50%, -100%)" : "translate(-50%, -50%)"
+        },
+        children: centerContent({
+          value,
+          shown,
+          text: format(shown),
+          color: valueColor,
+          band: active?.label,
+          caption
+        })
+      }
+    ) : null,
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        role: "slider",
+        "aria-label": labels.explore,
+        "aria-valuemin": 1,
+        "aria-valuemax": items,
+        "aria-valuenow": (nav.active ?? 0) + 1,
+        "aria-valuetext": valueText,
+        tabIndex: 0,
+        ...nav.sliderProps,
+        className: "pointer-events-none absolute inset-0 rounded-xs outline-none focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-2"
+      }
+    ),
+    tooltip && anchor && rows.length ? /* @__PURE__ */ jsx(ChartTooltip, { x: anchor.x, y: anchor.y, containerWidth: width, rows }) : null
+  ] });
+}
+const BandMark = memo(function BandMark2({
+  d,
+  width,
+  color,
+  opacity,
+  dimmed,
+  onEnter,
+  onLeave
+}) {
+  return /* @__PURE__ */ jsx(
+    "path",
+    {
+      "data-band": "",
+      d,
+      fill: "none",
+      strokeWidth: width,
+      strokeLinecap: "butt",
+      onPointerEnter: onEnter,
+      onPointerMove: onEnter,
+      onPointerLeave: onLeave,
+      className: cn("motion-safe:transition-opacity motion-safe:duration-150"),
+      style: { stroke: color, opacity: dimmed ? opacity * 0.5 : opacity }
+    }
+  );
+});
+export {
+  GaugeChart
+};

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

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

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

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

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

@@ -0,0 +1,75 @@
+import { type MapPoint, type MapRoute } from "../bubble-map/bubble-map.js";
+import type { ChoroplethDatum } from "../choropleth-map/choropleth-map.js";
+import type { ColorRange, ScaleColors } from "../core/color-scale.js";
+import { type ValueFormat } from "../core/format.js";
+import { type GlobeRotation } from "../maps/geo/globe.js";
+import { type MapLabels } from "../maps/geo/map-labels.js";
+import type { GeoMap } from "../maps/geo/types.js";
+/** Visible strings of the globe, on top of the shared map strings. */
+export interface GlobeLabels extends MapLabels {
+    /** Button that returns to the initial view. */
+    resetView: string;
+    /** Buttons that stop and start the idle spin. */
+    pauseSpin: string;
+    playSpin: string;
+    /** Spoken position of the view center. */
+    centerAt: (lon: number, lat: number) => string;
+}
+export declare const DEFAULT_GLOBE_LABELS: GlobeLabels;
+export interface GlobeChartProps {
+    /** Accessible name of the drawing and caption of the data table. */
+    title: string;
+    /** Land to draw, e.g. `worldMap` from `@jcsoftdev/ui/charts/maps/data/world`. */
+    map: GeoMap;
+    /** Value per region (id or name); fills the land with a color scale. */
+    data?: readonly ChoroplethDatum[];
+    scale?: "sequential" | "diverging";
+    domain?: readonly [number, number];
+    center?: number;
+    colors?: ScaleColors;
+    ranges?: readonly ColorRange[];
+    valueFormat?: ValueFormat;
+    /** Name of the value in the tooltip and the data table. */
+    valueName?: string;
+    /** Markers on the surface, area-proportional when they carry a `value`. */
+    points?: readonly MapPoint[];
+    /** Great-circle arcs between places, lifted a little over the surface. */
+    routes?: readonly MapRoute[];
+    minRadius?: number;
+    maxRadius?: number;
+    /** Meridians and parallels. */
+    graticule?: boolean;
+    /** Degrees between graticule lines (30 by default). */
+    graticuleStep?: number;
+    /** View center when the user has not turned the globe yet. Lima by default. */
+    initialRotation?: GlobeRotation;
+    /** Controlled view center; combine with `onRotationChange`. */
+    rotation?: GlobeRotation;
+    onRotationChange?: (rotation: GlobeRotation) => void;
+    /** Slow idle spin that pauses while the pointer or focus is on the globe. Off under reduced motion. */
+    autoRotate?: boolean;
+    /** Degrees per second of the idle spin. */
+    autoRotateSpeed?: number;
+    height?: number | "fill";
+    aspectRatio?: number;
+    legend?: boolean;
+    tooltip?: boolean;
+    /** The numbers as a screen-reader table (always hidden visually). */
+    dataTable?: "hidden";
+    loading?: boolean;
+    labels?: Partial<GlobeLabels>;
+    onRegionClick?: (region: {
+        id: string;
+        name: string;
+        value: number | null;
+    }) => void;
+    onPointClick?: (point: MapPoint) => void;
+    className?: string;
+}
+/**
+ * The world as a globe (orthographic projection) you turn with the pointer or the arrow keys.
+ * Regions can be colored by value, markers sized by value and great-circle routes drawn over the
+ * surface. It fills its container as a disc, adapts to any width and keeps every interaction
+ * available without a pointer.
+ */
+export declare function GlobeChart({ title, map, data, scale, domain, center, colors, ranges, valueFormat, valueName, points, routes, minRadius, maxRadius, graticule, graticuleStep, initialRotation, rotation: controlled, onRotationChange, autoRotate, autoRotateSpeed, height, aspectRatio, legend, tooltip, loading, labels: labelsProp, onRegionClick, onPointClick, className, }: GlobeChartProps): import("react").JSX.Element;