@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/hex-tile-map/hex-layout.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare const PERU_HEX_TILES: readonly HexTile[];
+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 declare function layoutHexGrid(tiles: readonly Pick<HexTile, "row" | "col">[], width: number, height: number): HexGrid;
+/** The six corners of a pointy-top hexagon as an SVG `points` value; `inset` shrinks it for the gap. */
+export declare function hexPoints(cx: number, cy: number, size: number, inset?: number): string;
+/** Index of the tile whose hexagon contains the point, or -1. */
+export declare function hexAt(centers: ReadonlyArray<readonly [number, number]>, size: number, x: number, y: number): number;
+/** Ids of the tiles that share an edge with `tile` (odd-r offset neighbours). */
+export declare function hexNeighbors(tile: HexTile, tiles: readonly HexTile[]): string[];

package/dist/charts/hex-tile-map/hex-layout.js

@@ -0,0 +1,96 @@
+const PERU_HEX_TILES = [
+  { 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\xEDn", 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\xE1nuco", code: "HUC", row: 2, col: 3 },
+  { id: "PE-UCA", name: "Ucayali", code: "UCA", row: 2, col: 4 },
+  { id: "PE-ANC", name: "\xC1ncash", code: "ANC", row: 3, col: 1 },
+  { id: "PE-PAS", name: "Pasco", code: "PAS", row: 3, col: 2 },
+  { id: "PE-JUN", name: "Jun\xEDn", 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\xEDmac", 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);
+function unitsX(tile) {
+  return tile.col + (tile.row % 2 === 1 ? 0.5 : 0);
+}
+function layoutHexGrid(tiles, width, height) {
+  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);
+  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) => [
+    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 };
+}
+function hexPoints(cx, cy, size, inset = 0) {
+  const radius = Math.max(0, size - inset);
+  const corners = [];
+  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(" ");
+}
+function hexAt(centers, size, x, y) {
+  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;
+    }
+  });
+  return best >= 0 && bestDistance <= SQRT3 / 2 * size ? best : -1;
+}
+function hexNeighbors(tile, tiles) {
+  const odd = tile.row % 2 === 1;
+  const around = [
+    [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);
+}
+export {
+  PERU_HEX_TILES,
+  hexAt,
+  hexNeighbors,
+  hexPoints,
+  layoutHexGrid
+};

package/dist/charts/hex-tile-map/hex-tile-map.d.ts

@@ -0,0 +1,41 @@
+import type { ChoroplethDatum, ChoroplethRegionInfo } from "../choropleth-map/choropleth-map.js";
+import { type ColorRange, type ScaleColors } from "../core/color-scale.js";
+import { type ValueFormat } from "../core/format.js";
+import { type MapLabels } from "../maps/geo/map-labels.js";
+import { type HexTile } 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;
+}
+/**
+ * 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 declare function HexTileMap({ title, data, tiles, scale, domain, center, colors, ranges, valueFormat, valueName, tileLabels, height, aspectRatio, legend, tooltip, animate, loading, labels: labelsProp, onTileClick, className, }: HexTileMapProps): import("react").JSX.Element;

package/dist/charts/hex-tile-map/hex-tile-map.js

@@ -0,0 +1,307 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { cn } from "../../utils/cn.js";
+import { DECORATIVE } from "../core/a11y.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { inkOn } from "../core/color-scale.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat } 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 { resolveMapLabels } from "../maps/geo/map-labels.js";
+import { MapLegend } from "../maps/geo/map-legend.js";
+import { createRegionIndex } from "../maps/geo/match.js";
+import { hexPoints, layoutHexGrid, PERU_HEX_TILES } from "./hex-layout.js";
+const NO_DATA_FILL = "var(--surface-2)";
+function defaultHeight(tiles, width) {
+  const grid = layoutHexGrid(tiles, 1e3, 1e3);
+  const ratio = grid.width > 0 ? grid.height / grid.width : 1;
+  return Math.round(Math.min(640, Math.max(220, width * ratio)));
+}
+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
+}) {
+  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 /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: height ?? ((width) => defaultHeight(tiles, width)),
+      aspectRatio,
+      labels,
+      loading,
+      empty: finite.length === 0,
+      skeleton: "bars",
+      className,
+      footer: legend ? /* @__PURE__ */ jsx(
+        MapLegend,
+        {
+          kind: scale,
+          domain: colorScale.domain,
+          center,
+          colors,
+          ranges,
+          format,
+          noData: data.length > finite.length ? labels.noData : void 0
+        }
+      ) : null,
+      table: /* @__PURE__ */ jsx(
+        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)
+              )
+            }
+          ]
+        }
+      ),
+      children: (width, drawingHeight) => /* @__PURE__ */ jsx(
+        HexPlot,
+        {
+          width,
+          height: drawingHeight,
+          title,
+          cells,
+          format,
+          valueName: name,
+          tileLabels,
+          tooltip,
+          animate,
+          labels,
+          onTileClick
+        }
+      )
+    }
+  );
+}
+function HexPlot({
+  width,
+  height,
+  title,
+  cells,
+  format,
+  valueName,
+  tileLabels,
+  tooltip,
+  animate,
+  labels,
+  onTileClick
+}) {
+  const svgRef = useRef(null);
+  const grid = useMemo(
+    () => layoutHexGrid(
+      cells.map((cell) => cell.tile),
+      width,
+      height
+    ),
+    [cells, width, height]
+  );
+  const nav = useIndexNavigation(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) => {
+    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 /* @__PURE__ */ jsxs("div", { ref: nav.ref, className: "relative", style: { width, height }, onPointerLeave: nav.leave, children: [
+    /* @__PURE__ */ jsx(
+      "svg",
+      {
+        ref: svgRef,
+        role: "img",
+        "aria-label": title,
+        width,
+        height,
+        className: "block overflow-visible",
+        children: cells.map((cell, index) => {
+          const [cx, cy] = grid.centers[index];
+          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.
+            /* @__PURE__ */ jsxs(
+              "g",
+              {
+                "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),
+                children: [
+                  /* @__PURE__ */ jsx(
+                    "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 ? /* @__PURE__ */ jsxs(
+                    "text",
+                    {
+                      ...DECORATIVE,
+                      x: cx,
+                      y: cy,
+                      textAnchor: "middle",
+                      className: "pointer-events-none font-bold tabular-nums",
+                      style: { fill: cell.ink },
+                      children: [
+                        /* @__PURE__ */ jsx(
+                          "tspan",
+                          {
+                            x: cx,
+                            dy: text.length > 1 ? "-0.15em" : "0.35em",
+                            fontSize: showCode ? codeSize : valueSize,
+                            children: text[0]
+                          }
+                        ),
+                        text.length > 1 ? /* @__PURE__ */ jsx("tspan", { x: cx, dy: "1.2em", fontSize: valueSize, className: "font-semibold", children: text[1] }) : null
+                      ]
+                    }
+                  ) : null
+                ]
+              },
+              cell.tile.id
+            )
+          );
+        })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "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 ? /* @__PURE__ */ jsx(
+      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
+  ] });
+}
+export {
+  HexTileMap
+};

package/dist/charts/hex-tile-map/index.d.ts

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

package/dist/charts/hex-tile-map/index.js

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

package/dist/charts/hierarchy-morph/hierarchy-morph.d.ts

@@ -0,0 +1,47 @@
+import { type ValueFormat } from "../core/format.js";
+import { type HierarchyDatum } from "../core/hierarchy.js";
+import { type HierarchyLabels } from "../core/hierarchy-chart.js";
+export type HierarchyMorphMode = "treemap" | "sunburst";
+export interface HierarchyMorphLabels extends HierarchyLabels {
+    /** Accessible name of the view switch. */
+    view: string;
+    /** Switch button: rectangles. */
+    treemap: string;
+    /** Switch button: rings. */
+    sunburst: string;
+}
+export interface HierarchyMorphProps {
+    /** Accessible name of the drawing and caption of the data table. */
+    title: string;
+    /** Root of the tree; its total is shown in the tooltip share. */
+    data: HierarchyDatum;
+    /** Controlled view. */
+    mode?: HierarchyMorphMode;
+    /** Initial view when uncontrolled. */
+    defaultMode?: HierarchyMorphMode;
+    onModeChange?: (mode: HierarchyMorphMode) => void;
+    /** Levels drawn below the root (1 or 2). */
+    levels?: 1 | 2;
+    /** Hide the built-in switch (drive `mode` from outside). */
+    showSwitch?: boolean;
+    height?: number | "fill";
+    /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
+    aspectRatio?: number;
+    valueFormat?: ValueFormat;
+    /** Gap between shapes in pixels. */
+    gap?: number;
+    sort?: boolean;
+    tooltip?: boolean;
+    /** Morph duration in ms; 0 or `false` swaps instantly. */
+    animate?: boolean;
+    loading?: boolean;
+    labels?: Partial<HierarchyMorphLabels>;
+    className?: string;
+}
+/**
+ * One hierarchy, two views. Switching between treemap rectangles and
+ * sunburst rings morphs every shape: each is sampled as a polygon in both
+ * layouts and the points glide from one to the other, so the eye follows a
+ * branch instead of re-reading the chart.
+ */
+export declare function HierarchyMorph({ title, data, mode, defaultMode, onModeChange, levels, showSwitch, height, aspectRatio, valueFormat, gap, sort, tooltip, animate, loading, labels: labelsProp, className, }: HierarchyMorphProps): import("react").JSX.Element;