@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/charts/heatmap-chart/hex-layout.ts

@@ -0,0 +1,88 @@
+/**
+ * Honeycomb geometry for heatmaps: pointy-top hexagons in an "odd-r" offset
+ * grid (odd rows are shifted half a cell to the right). Pure.
+ */
+
+const SQRT3 = Math.sqrt(3);
+
+export interface HexLayoutInput {
+  rows: number;
+  columns: number;
+  /** Area the honeycomb must fit, in pixels. */
+  width: number;
+  height: number;
+}
+
+export interface HexLayout {
+  /** Circumradius of one hexagon. */
+  radius: number;
+  /** Horizontal distance between two neighbours of a row. */
+  stepX: number;
+  /** Vertical distance between two rows. */
+  stepY: number;
+  /** Top-left of the honeycomb inside the area (it is centred). */
+  originX: number;
+  originY: number;
+  /** Centre of a cell. */
+  center(row: number, column: number): { x: number; y: number };
+  /** Cell under a point (relative to the area), or null outside the honeycomb. */
+  cellAt(x: number, y: number): { row: number; column: number } | null;
+}
+
+export function hexLayout({ rows, columns, width, height }: HexLayoutInput): HexLayout {
+  const fitX = columns > 0 ? width / (SQRT3 * (columns + 0.5)) : 0;
+  const fitY = rows > 0 ? height / (1.5 * (rows - 1) + 2) : 0;
+  const radius = Math.max(0, Math.min(fitX, fitY));
+  const stepX = SQRT3 * radius;
+  const stepY = 1.5 * radius;
+  const usedWidth = stepX * (columns + 0.5);
+  const usedHeight = stepY * Math.max(0, rows - 1) + 2 * radius;
+  const originX = Math.max(0, (width - usedWidth) / 2);
+  const originY = Math.max(0, (height - usedHeight) / 2);
+  const center = (row: number, column: number) => ({
+    x: originX + stepX * (column + 0.5 + (row & 1) * 0.5),
+    y: originY + radius + stepY * row,
+  });
+  return {
+    radius,
+    stepX,
+    stepY,
+    originX,
+    originY,
+    center,
+    cellAt(x, y) {
+      if (radius <= 0) return null;
+      // Pixel to fractional axial coordinates relative to cell (0, 0).
+      const first = center(0, 0);
+      const px = x - first.x;
+      const py = y - first.y;
+      const q = ((SQRT3 / 3) * px - py / 3) / radius;
+      const r = ((2 / 3) * py) / radius;
+      // Cube rounding.
+      let cx = Math.round(q);
+      let cz = Math.round(r);
+      const cy = Math.round(-q - r);
+      const dx = Math.abs(cx - q);
+      const dy = Math.abs(cy - (-q - r));
+      const dz = Math.abs(cz - r);
+      if (dx > dy && dx > dz) cx = -cy - cz;
+      else if (dy <= dz) cz = -cx - cy;
+      const row = cz;
+      const column = cx + (row - (row & 1)) / 2;
+      if (row < 0 || row >= rows || column < 0 || column >= columns) return null;
+      return { row, column };
+    },
+  };
+}
+
+/** Closed path of a pointy-top hexagon centred at `(cx, cy)`. */
+export function hexPath(cx: number, cy: number, radius: number): string {
+  const points: string[] = [];
+  for (let i = 0; i < 6; i += 1) {
+    const angle = (Math.PI / 180) * (60 * i - 90);
+    points.push(
+      `${Math.round((cx + radius * Math.cos(angle)) * 100) / 100},${Math.round((cy + radius * Math.sin(angle)) * 100) / 100}`,
+    );
+  }
+  return `M${points.join("L")}Z`;
+}

package/src/charts/heatmap-chart/index.ts

@@ -0,0 +1,9 @@
+export * from "./calendar-heatmap.js";
+export * from "./calendar-layout.js";
+export * from "./datetime-columns.js";
+export * from "./drilldown-heatmap.js";
+export * from "./heatmap-chart.js";
+export type { HeatmapCellInfo, HeatmapLabels } from "./heatmap-grid.js";
+export { DEFAULT_HEATMAP_LABELS, resolveHeatmapLabels } from "./heatmap-grid.js";
+export * from "./heatmap-scale.js";
+export * from "./hex-layout.js";

package/src/charts/hex-tile-map/hex-layout.ts

@@ -0,0 +1,147 @@
+/**
+ * Hex tile maps: one equal-size hexagon per region, placed by hand so that neighbours
+ * on the grid are (roughly) neighbours on the ground. The layout is pointy-top with odd
+ * rows pushed half a tile to the right ("odd-r"). Everything here is framework free.
+ */
+
+export interface HexTile {
+  /** Region id, matched against the data (ISO 3166-2 for Peru: "PE-CUS"). */
+  id: string;
+  name: string;
+  /** Two or three letters written on the tile. */
+  code: string;
+  row: number;
+  col: number;
+}
+
+/**
+ * Peru as 25 tiles (24 departments + Callao), north-west at the top left and the
+ * south-east at the bottom right, with the Pacific coast down the left edge.
+ * Lima is the department; the metropolitan area of the choropleth map belongs to it.
+ */
+export const PERU_HEX_TILES: readonly HexTile[] = [
+  { id: "PE-TUM", name: "Tumbes", code: "TUM", row: 0, col: 0 },
+  { id: "PE-LOR", name: "Loreto", code: "LOR", row: 0, col: 3 },
+  { id: "PE-PIU", name: "Piura", code: "PIU", row: 1, col: 0 },
+  { id: "PE-CAJ", name: "Cajamarca", code: "CAJ", row: 1, col: 1 },
+  { id: "PE-AMA", name: "Amazonas", code: "AMA", row: 1, col: 2 },
+  { id: "PE-SAM", name: "San Martín", code: "SAM", row: 1, col: 3 },
+  { id: "PE-LAM", name: "Lambayeque", code: "LAM", row: 2, col: 1 },
+  { id: "PE-LAL", name: "La Libertad", code: "LAL", row: 2, col: 2 },
+  { id: "PE-HUC", name: "Huánuco", code: "HUC", row: 2, col: 3 },
+  { id: "PE-UCA", name: "Ucayali", code: "UCA", row: 2, col: 4 },
+  { id: "PE-ANC", name: "Áncash", code: "ANC", row: 3, col: 1 },
+  { id: "PE-PAS", name: "Pasco", code: "PAS", row: 3, col: 2 },
+  { id: "PE-JUN", name: "Junín", code: "JUN", row: 3, col: 3 },
+  { id: "PE-CUS", name: "Cusco", code: "CUS", row: 3, col: 4 },
+  { id: "PE-MDD", name: "Madre de Dios", code: "MDD", row: 3, col: 5 },
+  { id: "PE-CAL", name: "Callao", code: "CAL", row: 4, col: 1 },
+  { id: "PE-LIM", name: "Lima", code: "LIM", row: 4, col: 2 },
+  { id: "PE-HUV", name: "Huancavelica", code: "HUV", row: 4, col: 3 },
+  { id: "PE-AYA", name: "Ayacucho", code: "AYA", row: 4, col: 4 },
+  { id: "PE-APU", name: "Apurímac", code: "APU", row: 4, col: 5 },
+  { id: "PE-ICA", name: "Ica", code: "ICA", row: 5, col: 3 },
+  { id: "PE-ARE", name: "Arequipa", code: "ARE", row: 5, col: 4 },
+  { id: "PE-PUN", name: "Puno", code: "PUN", row: 5, col: 5 },
+  { id: "PE-MOQ", name: "Moquegua", code: "MOQ", row: 6, col: 5 },
+  { id: "PE-TAC", name: "Tacna", code: "TAC", row: 6, col: 6 },
+];
+
+const SQRT3 = Math.sqrt(3);
+
+/** Horizontal tile units of a tile: columns, plus half a tile on odd rows. */
+function unitsX(tile: Pick<HexTile, "row" | "col">): number {
+  return tile.col + (tile.row % 2 === 1 ? 0.5 : 0);
+}
+
+export interface HexGrid {
+  /** Distance from a tile's center to a corner, in pixels. */
+  size: number;
+  /** Center of every tile, in the order of the input. */
+  centers: Array<[number, number]>;
+  /** Pixel box taken by the tiles (the rest of the area is margin). */
+  width: number;
+  height: number;
+  /** Where the box starts inside the area, so the grid is centered. */
+  offsetX: number;
+  offsetY: number;
+}
+
+/** Largest hexagons that fit `tiles` in a `width` x `height` area, centered. */
+export function layoutHexGrid(
+  tiles: readonly Pick<HexTile, "row" | "col">[],
+  width: number,
+  height: number,
+): HexGrid {
+  if (tiles.length === 0) {
+    return { size: 0, centers: [], width: 0, height: 0, offsetX: 0, offsetY: 0 };
+  }
+  const xs = tiles.map(unitsX);
+  const minX = Math.min(...xs);
+  const maxX = Math.max(...xs);
+  const rows = tiles.map((tile) => tile.row);
+  const minRow = Math.min(...rows);
+  const maxRow = Math.max(...rows);
+  // Width: (span + 1) tiles of SQRT3 * size. Height: rows * 1.5 * size plus the cap of a hexagon.
+  const spanUnits = maxX - minX + 1;
+  const spanRows = maxRow - minRow;
+  const size = Math.max(0, Math.min(width / (spanUnits * SQRT3), height / (spanRows * 1.5 + 2)));
+  const boxWidth = spanUnits * SQRT3 * size;
+  const boxHeight = (spanRows * 1.5 + 2) * size;
+  const offsetX = (width - boxWidth) / 2;
+  const offsetY = (height - boxHeight) / 2;
+  const centers = tiles.map((tile): [number, number] => [
+    offsetX + (unitsX(tile) - minX + 0.5) * SQRT3 * size,
+    offsetY + size + (tile.row - minRow) * 1.5 * size,
+  ]);
+  return { size, centers, width: boxWidth, height: boxHeight, offsetX, offsetY };
+}
+
+/** The six corners of a pointy-top hexagon as an SVG `points` value; `inset` shrinks it for the gap. */
+export function hexPoints(cx: number, cy: number, size: number, inset = 0): string {
+  const radius = Math.max(0, size - inset);
+  const corners: string[] = [];
+  for (let i = 0; i < 6; i += 1) {
+    const angle = (Math.PI / 180) * (60 * i - 30);
+    corners.push(
+      `${(cx + radius * Math.cos(angle)).toFixed(2)},${(cy + radius * Math.sin(angle)).toFixed(2)}`,
+    );
+  }
+  return corners.join(" ");
+}
+
+/** Index of the tile whose hexagon contains the point, or -1. */
+export function hexAt(
+  centers: ReadonlyArray<readonly [number, number]>,
+  size: number,
+  x: number,
+  y: number,
+): number {
+  let best = -1;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  centers.forEach(([cx, cy], index) => {
+    const distance = Math.hypot(x - cx, y - cy);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = index;
+    }
+  });
+  // The inscribed circle is a safe hit radius: it never reaches into the next tile.
+  return best >= 0 && bestDistance <= (SQRT3 / 2) * size ? best : -1;
+}
+
+/** Ids of the tiles that share an edge with `tile` (odd-r offset neighbours). */
+export function hexNeighbors(tile: HexTile, tiles: readonly HexTile[]): string[] {
+  const odd = tile.row % 2 === 1;
+  const around: Array<[number, number]> = [
+    [tile.row, tile.col - 1],
+    [tile.row, tile.col + 1],
+    [tile.row - 1, tile.col + (odd ? 0 : -1)],
+    [tile.row - 1, tile.col + (odd ? 1 : 0)],
+    [tile.row + 1, tile.col + (odd ? 0 : -1)],
+    [tile.row + 1, tile.col + (odd ? 1 : 0)],
+  ];
+  return tiles
+    .filter((other) => around.some(([row, col]) => other.row === row && other.col === col))
+    .map((other) => other.id);
+}

package/src/charts/hex-tile-map/hex-tile-map.tsx

@@ -0,0 +1,361 @@
+"use client";
+
+import { useMemo, useRef } from "react";
+import { cn } from "../../utils/cn.js";
+import type { ChoroplethDatum, ChoroplethRegionInfo } from "../choropleth-map/choropleth-map.js";
+import { DECORATIVE } from "../core/a11y.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { type ColorRange, inkOn, type ScaleColors } from "../core/color-scale.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat, type ValueFormat } from "../core/format.js";
+import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { ChartTooltip } from "../core/tooltip.js";
+import { useIndexNavigation } from "../core/use-index-navigation.js";
+import { heatmapScale } from "../heatmap-chart/heatmap-scale.js";
+import { type MapLabels, resolveMapLabels } from "../maps/geo/map-labels.js";
+import { MapLegend } from "../maps/geo/map-legend.js";
+import { createRegionIndex } from "../maps/geo/match.js";
+import { type HexTile, hexPoints, layoutHexGrid, PERU_HEX_TILES } from "./hex-layout.js";
+
+export interface HexTileMapProps {
+  /** Accessible name of the drawing and caption of the data table. */
+  title: string;
+  /** One value per tile, matched by `id` (or the tile name; accents and case are ignored). */
+  data: readonly ChoroplethDatum[];
+  /** The tiles and their grid cells; Peru's 25 regions by default. */
+  tiles?: readonly HexTile[];
+  scale?: "sequential" | "diverging";
+  domain?: readonly [number, number];
+  center?: number;
+  colors?: ScaleColors;
+  /** Stepped (threshold) coloring; replaces the continuous scale. */
+  ranges?: readonly ColorRange[];
+  valueFormat?: ValueFormat;
+  /** Name of the value in the tooltip and the data table, e.g. "Clientes". */
+  valueName?: string;
+  /** What is written on a tile where it fits: the code, the value, both or nothing. */
+  tileLabels?: "code" | "value" | "both" | "none";
+  /** Height in px, "fill" or a default that follows the grid's proportions. */
+  height?: number | "fill";
+  aspectRatio?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  animate?: boolean;
+  loading?: boolean;
+  labels?: Partial<MapLabels>;
+  onTileClick?: (tile: ChoroplethRegionInfo) => void;
+  className?: string;
+}
+
+const NO_DATA_FILL = "var(--surface-2)";
+
+function defaultHeight(tiles: readonly HexTile[], width: number): number {
+  const grid = layoutHexGrid(tiles, 1000, 1000);
+  const ratio = grid.width > 0 ? grid.height / grid.width : 1;
+  return Math.round(Math.min(640, Math.max(220, width * ratio)));
+}
+
+/**
+ * Tile map: every region is one hexagon of the same size, so small regions (Callao, Tumbes)
+ * weigh as much as large ones and nothing hides behind Loreto. Colored by value like
+ * `ChoroplethMap`, with the same legend, tooltip, keyboard model and data table. The default
+ * layout is Peru's 25 regions; pass `tiles` for any other territory.
+ */
+export function HexTileMap({
+  title,
+  data,
+  tiles = PERU_HEX_TILES,
+  scale = "sequential",
+  domain,
+  center = 0,
+  colors,
+  ranges,
+  valueFormat,
+  valueName,
+  tileLabels = "both",
+  height,
+  aspectRatio,
+  legend = true,
+  tooltip = true,
+  animate = true,
+  loading,
+  labels: labelsProp,
+  onTileClick,
+  className,
+}: HexTileMapProps) {
+  const labels = resolveMapLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const lookup = useMemo(() => createRegionIndex(data), [data]);
+  const finite = useMemo(
+    () =>
+      data.flatMap((datum) =>
+        typeof datum.value === "number" && Number.isFinite(datum.value) ? [datum.value] : [],
+      ),
+    [data],
+  );
+  const colorScale = useMemo(
+    () => heatmapScale(finite, { scale, domain, center, colors, ranges }),
+    [finite, scale, domain, center, colors, ranges],
+  );
+  const name = valueName ?? labels.value;
+  const cells = useMemo(
+    () =>
+      tiles.map((tile) => {
+        const value = lookup(tile)?.value ?? null;
+        const stop = value == null ? null : colorScale.color(value);
+        return {
+          tile,
+          value,
+          color: stop?.color ?? NO_DATA_FILL,
+          ink: stop ? inkOn(stop.strength) : "var(--ink-2)",
+        };
+      }),
+    [tiles, lookup, colorScale],
+  );
+
+  return (
+    <ChartFrame
+      height={height ?? ((width) => defaultHeight(tiles, width))}
+      aspectRatio={aspectRatio}
+      labels={labels}
+      loading={loading}
+      empty={finite.length === 0}
+      skeleton="bars"
+      className={className}
+      footer={
+        legend ? (
+          <MapLegend
+            kind={scale}
+            domain={colorScale.domain}
+            center={center}
+            colors={colors}
+            ranges={ranges}
+            format={format}
+            noData={data.length > finite.length ? labels.noData : undefined}
+          />
+        ) : null
+      }
+      table={
+        <ChartDataTable
+          caption={title}
+          categoryHeader={labels.region}
+          categories={cells.map((cell) => cell.tile.name)}
+          columns={[
+            {
+              id: "value",
+              name,
+              values: cells.map((cell) =>
+                cell.value == null ? labels.noData : format(cell.value),
+              ),
+            },
+          ]}
+        />
+      }
+    >
+      {(width, drawingHeight) => (
+        <HexPlot
+          width={width}
+          height={drawingHeight}
+          title={title}
+          cells={cells}
+          format={format}
+          valueName={name}
+          tileLabels={tileLabels}
+          tooltip={tooltip}
+          animate={animate}
+          labels={labels}
+          onTileClick={onTileClick}
+        />
+      )}
+    </ChartFrame>
+  );
+}
+
+interface Cell {
+  tile: HexTile;
+  value: number | null;
+  color: string;
+  ink: string;
+}
+
+function HexPlot({
+  width,
+  height,
+  title,
+  cells,
+  format,
+  valueName,
+  tileLabels,
+  tooltip,
+  animate,
+  labels,
+  onTileClick,
+}: {
+  width: number;
+  height: number;
+  title: string;
+  cells: readonly Cell[];
+  format: (value: number) => string;
+  valueName: string;
+  tileLabels: "code" | "value" | "both" | "none";
+  tooltip: boolean;
+  animate: boolean;
+  labels: MapLabels;
+  onTileClick?: (tile: ChoroplethRegionInfo) => void;
+}) {
+  const svgRef = useRef<SVGSVGElement>(null);
+  const grid = useMemo(
+    () =>
+      layoutHexGrid(
+        cells.map((cell) => cell.tile),
+        width,
+        height,
+      ),
+    [cells, width, height],
+  );
+  const nav = useIndexNavigation<HTMLDivElement>(cells.length);
+  const active = nav.active;
+  const current = active == null ? null : (cells[active] ?? null);
+  const valueText = current
+    ? `${current.tile.name}: ${current.value == null ? labels.noData : format(current.value)}`
+    : title;
+  const gap = Math.max(1.5, grid.size * 0.08);
+  const codeSize = Math.max(8, Math.min(13, grid.size * 0.46));
+  const valueSize = Math.max(8, Math.min(11, grid.size * 0.36));
+  const showCode = tileLabels !== "none" && tileLabels !== "value" && grid.size >= 15;
+  const showValue = (tileLabels === "value" || tileLabels === "both") && grid.size >= 24;
+
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      root.querySelectorAll("[data-tile]").forEach((node, i) => {
+        node.animate(
+          [
+            { opacity: 0, transform: "scale(0.6)" },
+            { opacity: 1, transform: "scale(1)" },
+          ],
+          { duration: 380, delay: i * 14, easing: EASE_OUT, fill: "backwards" },
+        );
+      });
+    },
+    { disabled: !animate },
+  );
+
+  const click = (index: number) => {
+    const cell = cells[index];
+    if (cell) {
+      onTileClick?.({ index, id: cell.tile.id, name: cell.tile.name, value: cell.value });
+    }
+  };
+  const anchor = current && active != null ? (grid.centers[active] ?? null) : null;
+
+  return (
+    <div ref={nav.ref} className="relative" style={{ width, height }} onPointerLeave={nav.leave}>
+      <svg
+        ref={svgRef}
+        role="img"
+        aria-label={title}
+        width={width}
+        height={height}
+        className="block overflow-visible"
+      >
+        {cells.map((cell, index) => {
+          const [cx, cy] = grid.centers[index] as [number, number];
+          const isActive = index === active;
+          const text = [
+            showCode ? cell.tile.code : null,
+            showValue && cell.value != null ? format(cell.value) : null,
+          ].filter(Boolean);
+          return (
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer mirror of the keyboard model on the slider below.
+            <g
+              key={cell.tile.id}
+              data-tile=""
+              style={{
+                cursor: onTileClick ? "pointer" : "default",
+                transformBox: "fill-box",
+                transformOrigin: "center",
+              }}
+              onPointerEnter={(event) => nav.hover(index, event)}
+              onPointerMove={(event) => nav.hover(index, event)}
+              onClick={() => click(index)}
+            >
+              <polygon
+                points={hexPoints(cx, cy, grid.size, gap / 2)}
+                strokeLinejoin="round"
+                className="motion-safe:transition-[fill] motion-safe:duration-150"
+                style={{
+                  fill: cell.color,
+                  stroke: isActive ? "var(--ink)" : "var(--surface)",
+                  strokeWidth: isActive ? 2.5 : 1,
+                }}
+              />
+              {text.length > 0 ? (
+                <text
+                  {...DECORATIVE}
+                  x={cx}
+                  y={cy}
+                  textAnchor="middle"
+                  className="pointer-events-none font-bold tabular-nums"
+                  style={{ fill: cell.ink }}
+                >
+                  <tspan
+                    x={cx}
+                    dy={text.length > 1 ? "-0.15em" : "0.35em"}
+                    fontSize={showCode ? codeSize : valueSize}
+                  >
+                    {text[0]}
+                  </tspan>
+                  {text.length > 1 ? (
+                    <tspan x={cx} dy="1.2em" fontSize={valueSize} className="font-semibold">
+                      {text[1]}
+                    </tspan>
+                  ) : null}
+                </text>
+              ) : null}
+            </g>
+          );
+        })}
+      </svg>
+      <div
+        role="slider"
+        tabIndex={0}
+        aria-label={labels.explore}
+        aria-valuemin={1}
+        aria-valuemax={Math.max(1, cells.length)}
+        aria-valuenow={(active ?? 0) + 1}
+        aria-valuetext={valueText}
+        onKeyDown={(event) => {
+          if ((event.key === "Enter" || event.key === " ") && active != null) {
+            event.preventDefault();
+            click(active);
+            return;
+          }
+          nav.sliderProps.onKeyDown(event);
+        }}
+        onFocus={nav.sliderProps.onFocus}
+        onBlur={nav.sliderProps.onBlur}
+        className={cn(
+          "pointer-events-none absolute inset-0 rounded-xs outline-none",
+          "focus-visible:outline-2 focus-visible:outline-accent-ink focus-visible:outline-offset-4",
+        )}
+      />
+      {tooltip && current ? (
+        <ChartTooltip
+          x={nav.pointer?.x ?? anchor?.[0] ?? 0}
+          y={nav.pointer?.y ?? anchor?.[1] ?? 0}
+          containerWidth={width}
+          title={current.tile.name}
+          rows={[
+            {
+              id: "value",
+              name: valueName,
+              value: current.value == null ? labels.noData : format(current.value),
+              color: current.color,
+            },
+          ]}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/charts/hex-tile-map/index.ts

@@ -0,0 +1,2 @@
+export * from "./hex-layout.js";
+export * from "./hex-tile-map.js";