@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/dist/charts/bubble-map/bubble-map.js

@@ -0,0 +1,520 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat } from "../core/format.js";
+import { ChartLegend } from "../core/legend.js";
+import { useReducedMotion } from "../core/motion.js";
+import { seriesColor } from "../core/palette.js";
+import { ChartTooltip } from "../core/tooltip.js";
+import { useIndexNavigation } from "../core/use-index-navigation.js";
+import { useSeriesState } from "../core/use-series-state.js";
+import { clusterPoints } from "../maps/geo/cluster.js";
+import { resolveMapLabels } from "../maps/geo/map-labels.js";
+import { MapViewport } from "../maps/geo/map-viewport.js";
+import { greatCircle, routeArcPath, routePolylinePath } from "../maps/geo/routes.js";
+import { defaultMapHeight, useMapGeometry } from "../maps/geo/use-map-geometry.js";
+import { useMapView } from "../maps/geo/use-map-view.js";
+function resolveRoutes(routes, points) {
+  const place = (end) => {
+    if (typeof end !== "string") {
+      return {
+        position: [end.lon, end.lat],
+        name: end.name ?? `${end.lat.toFixed(2)}, ${end.lon.toFixed(2)}`
+      };
+    }
+    const point = points.find((candidate) => candidate.id === end);
+    return point ? { position: [point.lon, point.lat], name: point.name } : null;
+  };
+  return routes.flatMap((route) => {
+    const from = place(route.from);
+    const to = place(route.to);
+    if (!from || !to) return [];
+    return [
+      {
+        route,
+        name: route.name ?? `${from.name} \u2192 ${to.name}`,
+        fromName: from.name,
+        toName: to.name,
+        from: from.position,
+        to: to.position
+      }
+    ];
+  });
+}
+function BubbleMap({
+  title,
+  map,
+  points,
+  categories,
+  valueFormat,
+  valueName,
+  projection,
+  minRadius = 6,
+  maxRadius = 28,
+  cluster = false,
+  clusterDistance = 36,
+  regionLabels = false,
+  routes = [],
+  routeStyle = "curve",
+  routeBend = 0.25,
+  animateRoutes = true,
+  height,
+  aspectRatio,
+  legend = true,
+  tooltip = true,
+  zoomable = true,
+  wheelZoom = "modifier",
+  maxZoom = 16,
+  animate = true,
+  loading,
+  labels: labelsProp,
+  onPointClick,
+  className
+}) {
+  const labels = resolveMapLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const legendState = useSeriesState();
+  const categoryList = useMemo(() => {
+    if (categories) return [...categories];
+    const seen = [];
+    for (const point of points) {
+      const id = point.category ?? "";
+      if (!seen.some((category) => category.id === id)) seen.push({ id, name: id });
+    }
+    return seen;
+  }, [categories, points]);
+  const colorOf = useMemo(() => {
+    const colors = new Map(
+      categoryList.map((category, index) => [category.id, seriesColor(index, category.color)])
+    );
+    return (point) => colors.get(point.category ?? "") ?? seriesColor(0);
+  }, [categoryList]);
+  const visible = useMemo(
+    () => points.filter((point) => !legendState.hidden.has(point.category ?? "")),
+    [points, legendState.hidden]
+  );
+  const showLegend = legend && categoryList.length > 1 && categoryList.every((c) => c.name !== "");
+  const legendItems = categoryList.map((category) => ({
+    id: category.id,
+    name: category.name,
+    color: seriesColor(categoryList.indexOf(category), category.color),
+    shape: "dot",
+    hidden: legendState.hidden.has(category.id)
+  }));
+  const name = valueName ?? labels.value;
+  const resolvedRoutes = useMemo(() => resolveRoutes(routes, points), [routes, points]);
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: height ?? ((width) => defaultMapHeight(map, width, projection)),
+      aspectRatio,
+      labels,
+      loading,
+      empty: points.length === 0,
+      skeleton: "bars",
+      className,
+      legend: showLegend ? /* @__PURE__ */ jsx(
+        ChartLegend,
+        {
+          items: legendItems,
+          onToggle: legendState.toggle,
+          onHighlight: legendState.setHighlighted
+        }
+      ) : null,
+      table: /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(
+          ChartDataTable,
+          {
+            caption: title,
+            categoryHeader: labels.region,
+            categories: points.map((point) => point.name),
+            columns: [
+              {
+                id: "value",
+                name,
+                values: points.map((point) => point.value == null ? "" : format(point.value))
+              },
+              {
+                id: "category",
+                name: labels.category,
+                values: points.map(
+                  (point) => categoryList.find((c) => c.id === (point.category ?? ""))?.name ?? ""
+                )
+              },
+              { id: "lon", name: labels.longitude, values: points.map((p) => p.lon.toFixed(4)) },
+              { id: "lat", name: labels.latitude, values: points.map((p) => p.lat.toFixed(4)) }
+            ]
+          }
+        ),
+        resolvedRoutes.length > 0 ? /* @__PURE__ */ jsx(
+          ChartDataTable,
+          {
+            caption: `${title}. ${labels.routes}`,
+            categoryHeader: labels.origin,
+            categories: resolvedRoutes.map((route) => route.fromName),
+            columns: [
+              {
+                id: "destination",
+                name: labels.destination,
+                values: resolvedRoutes.map((route) => route.toName)
+              },
+              {
+                id: "value",
+                name,
+                values: resolvedRoutes.map(
+                  (route) => route.route.value == null ? "" : format(route.route.value)
+                )
+              }
+            ]
+          }
+        ) : null
+      ] }),
+      children: (width, drawingHeight) => /* @__PURE__ */ jsx(
+        BubblePlot,
+        {
+          width,
+          height: drawingHeight,
+          title,
+          map,
+          points: visible,
+          colorOf,
+          highlight: legendState.highlighted,
+          format,
+          valueName: name,
+          projection,
+          minRadius,
+          maxRadius,
+          cluster,
+          clusterDistance,
+          regionLabels,
+          routes: resolvedRoutes,
+          routeStyle,
+          routeBend,
+          animateRoutes,
+          tooltip,
+          zoomable,
+          wheelZoom,
+          maxZoom,
+          animate,
+          labels,
+          categoryName: (point) => categoryList.find((c) => c.id === (point.category ?? ""))?.name ?? "",
+          onPointClick
+        }
+      )
+    }
+  );
+}
+function BubblePlot({
+  width,
+  height,
+  title,
+  map,
+  points,
+  colorOf,
+  highlight,
+  format,
+  valueName,
+  projection,
+  minRadius,
+  maxRadius,
+  cluster,
+  clusterDistance,
+  regionLabels,
+  routes,
+  routeStyle,
+  routeBend,
+  animateRoutes,
+  tooltip,
+  zoomable,
+  wheelZoom,
+  maxZoom,
+  animate,
+  labels,
+  categoryName,
+  onPointClick
+}) {
+  const geometry = useMapGeometry(map, width, height, { projection });
+  const controller = useMapView({
+    width,
+    height,
+    content: geometry.bounds,
+    gestures: zoomable,
+    wheelZoom,
+    maxZoom,
+    animate
+  });
+  const base = useMemo(
+    () => points.map((point) => {
+      const [x, y] = geometry.projection.project(point.lon, point.lat);
+      return { x, y, value: point.value ?? 0 };
+    }),
+    [points, geometry.projection]
+  );
+  const zoom = controller.view.k;
+  const fills = useMemo(() => geometry.features.map(() => "var(--surface-2)"), [geometry.features]);
+  const texts = useMemo(
+    () => regionLabels ? geometry.features.map((feature) => feature.name) : void 0,
+    [regionLabels, geometry.features]
+  );
+  const items = useMemo(() => {
+    const clusters = cluster ? clusterPoints(base, clusterDistance / zoom) : base.map((point, index) => ({ ...point, members: [index] }));
+    return clusters.map((entry) => {
+      const members = entry.members.map((index) => points[index]);
+      const dominant = /* @__PURE__ */ new Map();
+      for (const member of members) {
+        const color2 = colorOf(member);
+        dominant.set(color2, (dominant.get(color2) ?? 0) + (member.value ?? 1));
+      }
+      const color = [...dominant.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? colorOf(members[0]);
+      return {
+        key: members.map((member) => member.id).join("+"),
+        cluster: entry,
+        points: members,
+        color
+      };
+    });
+  }, [base, points, cluster, clusterDistance, zoom, colorOf]);
+  const radius = useMemo(() => {
+    const top = Math.max(0, ...items.map((item) => item.cluster.value));
+    return (item) => top > 0 && item.cluster.value > 0 ? Math.max(minRadius, maxRadius * Math.sqrt(item.cluster.value / top)) : minRadius;
+  }, [items, minRadius, maxRadius]);
+  const reducedMotion = useReducedMotion();
+  const [routeHover, setRouteHover] = useState(
+    null
+  );
+  const shapes = useMemo(() => {
+    const project = geometry.projection.project;
+    const top = Math.max(0, ...routes.map((entry) => entry.route.value ?? 0));
+    return routes.map((entry) => ({
+      entry,
+      width: top > 0 && entry.route.value ? 1.5 + 3.5 * Math.sqrt(entry.route.value / top) : 2,
+      a: project(entry.from[0], entry.from[1]),
+      b: project(entry.to[0], entry.to[1]),
+      pieces: routeStyle === "great-circle" ? greatCircle(entry.from, entry.to, 40).map(
+        (piece) => piece.map(([lon, lat]) => project(lon, lat))
+      ) : null
+    }));
+  }, [routes, routeStyle, geometry.projection]);
+  const stopDash = useRef(null);
+  const attachRoutes = useCallback(
+    (node) => {
+      stopDash.current?.();
+      stopDash.current = null;
+      if (!node || !animateRoutes || reducedMotion) return;
+      const running = [...node.querySelectorAll("[data-route-dash]")].map(
+        (path) => path.animate([{ strokeDashoffset: 0 }, { strokeDashoffset: -14 }], {
+          duration: 1100,
+          iterations: Number.POSITIVE_INFINITY
+        })
+      );
+      stopDash.current = () => {
+        for (const animation of running) animation.cancel();
+      };
+    },
+    [animateRoutes, reducedMotion]
+  );
+  const nav = useIndexNavigation(items.length);
+  const active = nav.active;
+  const current = active == null ? null : items[active] ?? null;
+  const describe = (item) => item.points.length > 1 ? labels.cluster(item.points.length) : item.points[0]?.name ?? "";
+  const valueLabel = (item) => item.points.some((point) => point.value != null) ? format(item.cluster.value) : "";
+  const valueText = current ? [describe(current), valueLabel(current) && `${valueName}: ${valueLabel(current)}`].filter(Boolean).join(", ") : title;
+  const activate = (index, context) => {
+    const item = items[index];
+    if (!item) return;
+    if (item.points.length === 1) {
+      onPointClick?.(item.points[0]);
+      return;
+    }
+    const xs = item.cluster.members.map((member) => base[member].x);
+    const ys = item.cluster.members.map((member) => base[member].y);
+    const pad = 14;
+    const box = [
+      Math.min(...xs) - pad,
+      Math.min(...ys) - pad,
+      Math.max(...xs) + pad,
+      Math.max(...ys) + pad
+    ];
+    (context?.focusBox ?? controller.focusBox)(box);
+  };
+  return /* @__PURE__ */ jsx(
+    MapViewport,
+    {
+      width,
+      height,
+      title,
+      geometry,
+      labels,
+      fills,
+      interactive: false,
+      regionLabels: texts,
+      controller,
+      zoomable,
+      containerRef: nav.ref,
+      reveal: current && !nav.pointer ? [current.cluster.x, current.cluster.y] : null,
+      keyboard: {
+        count: items.length,
+        active,
+        valueText,
+        onKeyDown: nav.sliderProps.onKeyDown,
+        onFocus: nav.sliderProps.onFocus,
+        onBlur: nav.sliderProps.onBlur,
+        onActivate: () => {
+          if (active != null) activate(active);
+        }
+      },
+      overlay: (context) => /* @__PURE__ */ jsxs("g", { children: [
+        shapes.length > 0 ? /* @__PURE__ */ jsx(
+          "g",
+          {
+            ref: attachRoutes,
+            fill: "none",
+            strokeLinecap: "round",
+            children: shapes.map((shape, index) => {
+              const d = shape.pieces ? routePolylinePath(
+                shape.pieces.map((piece) => piece.map(([x, y]) => context.toScreen(x, y)))
+              ) : routeArcPath(
+                context.toScreen(shape.a[0], shape.a[1]),
+                context.toScreen(shape.b[0], shape.b[1]),
+                routeBend
+              );
+              const color = shape.entry.route.color ?? "var(--accent-word)";
+              const hover = (event) => {
+                const box = nav.ref.current?.getBoundingClientRect();
+                if (!box || context.dragging || event.buttons !== 0) return;
+                setRouteHover({ index, x: event.clientX - box.left, y: event.clientY - box.top });
+              };
+              return /* @__PURE__ */ jsxs("g", { children: [
+                /* @__PURE__ */ jsx("path", { d, strokeWidth: shape.width, style: { stroke: color }, opacity: 0.3 }),
+                /* @__PURE__ */ jsx(
+                  "path",
+                  {
+                    "data-route-dash": "",
+                    d,
+                    strokeWidth: shape.width,
+                    strokeDasharray: "6 8",
+                    pointerEvents: "none",
+                    style: { stroke: color }
+                  }
+                ),
+                /* @__PURE__ */ jsx(
+                  "path",
+                  {
+                    d,
+                    strokeWidth: Math.max(14, shape.width + 8),
+                    pointerEvents: "stroke",
+                    style: { stroke: "transparent" },
+                    onPointerEnter: hover,
+                    onPointerMove: hover,
+                    onPointerLeave: () => setRouteHover(null)
+                  }
+                )
+              ] }, shape.entry.route.id);
+            })
+          },
+          shapes.map((shape) => shape.entry.route.id).join("|")
+        ) : null,
+        items.map((item, index) => ({ item, index, r: radius(item) })).sort((a, b) => b.r - a.r).map(({ item, index, r }) => {
+          const [x, y] = context.toScreen(item.cluster.x, item.cluster.y);
+          if (x < -r || y < -r || x > width + r || y > height + r) return null;
+          const isActive = index === active;
+          const dim = highlight != null && !item.points.some((p) => (p.category ?? "") === highlight);
+          return (
+            // biome-ignore lint/a11y/noStaticElementInteractions: pointer-only mirror of the keyboard model on the focusable slider.
+            /* @__PURE__ */ jsxs(
+              "g",
+              {
+                opacity: dim ? 0.25 : 1,
+                style: { cursor: "pointer" },
+                onPointerEnter: (event) => !context.dragging && nav.hover(index, event),
+                onPointerMove: (event) => !context.dragging && event.buttons === 0 && nav.hover(index, event),
+                onClick: () => {
+                  if (!context.wasDragged()) activate(index, context);
+                },
+                children: [
+                  /* @__PURE__ */ jsx(
+                    "circle",
+                    {
+                      cx: x,
+                      cy: y,
+                      r,
+                      style: {
+                        fill: item.color,
+                        fillOpacity: 0.78,
+                        stroke: isActive ? "var(--ink)" : "var(--surface)",
+                        strokeWidth: isActive ? 2.5 : 1.5
+                      }
+                    }
+                  ),
+                  item.points.length > 1 && r >= 8 ? /* @__PURE__ */ jsx(
+                    "text",
+                    {
+                      x,
+                      y,
+                      textAnchor: "middle",
+                      dominantBaseline: "central",
+                      pointerEvents: "none",
+                      className: "font-bold text-[11px]",
+                      style: { fill: "var(--surface)" },
+                      children: item.points.length
+                    }
+                  ) : null
+                ]
+              },
+              item.key
+            )
+          );
+        })
+      ] }),
+      onLeave: nav.leave,
+      floating: ({ toScreen }) => {
+        const hovered = routeHover ? shapes[routeHover.index] : void 0;
+        if (tooltip && hovered && routeHover && !current) {
+          return /* @__PURE__ */ jsx(
+            ChartTooltip,
+            {
+              x: routeHover.x,
+              y: routeHover.y,
+              containerWidth: width,
+              title: hovered.entry.name,
+              rows: hovered.entry.route.value == null ? [] : [
+                {
+                  id: "value",
+                  name: valueName,
+                  value: format(hovered.entry.route.value),
+                  color: hovered.entry.route.color ?? "var(--accent-word)",
+                  shape: "line"
+                }
+              ]
+            }
+          );
+        }
+        if (!tooltip || !current) return null;
+        const [ax, ay] = toScreen(current.cluster.x, current.cluster.y);
+        const anchor = nav.pointer ?? { x: ax, y: ay - radius(current) };
+        const first = current.points[0];
+        const total = valueLabel(current);
+        const category = categoryName(first);
+        return /* @__PURE__ */ jsx(
+          ChartTooltip,
+          {
+            x: anchor.x,
+            y: anchor.y,
+            containerWidth: width,
+            title: describe(current),
+            rows: [
+              ...total ? [{ id: "value", name: valueName, value: total, color: current.color }] : [],
+              ...category && current.points.length === 1 ? [{ id: "category", name: category, value: "", color: current.color }] : []
+            ]
+          }
+        );
+      }
+    }
+  );
+}
+export {
+  BubbleMap,
+  resolveRoutes
+};

package/dist/charts/bubble-map/index.d.ts

@@ -0,0 +1 @@
+export * from "./bubble-map.js";

package/dist/charts/bubble-map/index.js

@@ -0,0 +1 @@
+export * from "./bubble-map.js";

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

@@ -0,0 +1,49 @@
+import { type ValueFormat } from "../core/format.js";
+import { type ChartLabels } from "../core/types.js";
+export interface BulletItem {
+    id?: string;
+    label: string;
+    /** The measured value: the thin bar. */
+    actual: number;
+    /** The goal: a tick across the bar. */
+    target?: number;
+    /** Upper bounds of the qualitative ranges, ascending (e.g. `[60, 85, 100]` for poor, fair, good). */
+    ranges?: readonly number[];
+    /** Overrides the chart `valueFormat` for this row. */
+    format?: ValueFormat;
+}
+export interface BulletChartProps {
+    items: readonly BulletItem[];
+    /** Accessible name of the chart. */
+    title: string;
+    description?: string;
+    /** Names of the qualitative ranges, lowest first (e.g. "Bajo", "Medio", "Alto"). */
+    rangeLabels?: readonly string[];
+    actualLabel?: string;
+    targetLabel?: string;
+    /** Color of the actual bar (default: the brand slot of the palette). */
+    color?: string;
+    orientation?: "horizontal" | "vertical";
+    /** "row" gives every row its own 0-to-max scale (mixed units); "shared" draws one axis for all. */
+    scale?: "row" | "shared";
+    valueFormat?: ValueFormat;
+    /** Height of every row in pixels (default 46), horizontal charts without `height`. */
+    rowHeight?: number;
+    /** Height in pixels, or `"fill"` for the parent height. */
+    height?: number | "fill";
+    aspectRatio?: number;
+    /** Actual and target written at the end of each row (default true when there is room). */
+    valueLabels?: boolean;
+    legend?: boolean;
+    tooltip?: boolean;
+    loading?: boolean;
+    animate?: boolean;
+    labels?: Partial<ChartLabels>;
+    className?: string;
+}
+/**
+ * Bullet graph: one measured bar against a target tick, on qualitative bands
+ * (poor, fair, good). Many rows compare KPIs in little space; each row has its
+ * own scale unless `scale="shared"`.
+ */
+export declare function BulletChart({ items, title, description, rangeLabels, actualLabel, targetLabel, color, orientation, scale, valueFormat, rowHeight, height, aspectRatio, valueLabels, legend, tooltip, loading, animate, labels: labelOverrides, className, }: BulletChartProps): import("react").JSX.Element;