@jcsoftdev/ui 0.0.0-stage → 0.1.0

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

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

package/src/charts/heatmap-chart/calendar-heatmap.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import { useMemo } from "react";
+import { ChartFrame } from "../core/chart-frame.js";
+import type { ColorRange, ScaleColors } from "../core/color-scale.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat, type ValueFormat } from "../core/format.js";
+import { formatDate, shortMonth } from "../core/scales/time.js";
+import { type CalendarDay, calendarGrid } from "./calendar-layout.js";
+import {
+  HEATMAP_TOP,
+  HeatmapGrid,
+  type HeatmapLabels,
+  HeatmapLegend,
+  resolveHeatmapLabels,
+  rowGutter,
+} from "./heatmap-grid.js";
+import { heatmapScale } from "./heatmap-scale.js";
+
+export interface CalendarHeatmapProps {
+  /** Accessible name of the drawing and caption of the data table. */
+  title: string;
+  /** One entry per day; missing days inside the range are drawn empty. */
+  days: readonly CalendarDay[];
+  /** First day shown; the earliest entry by default. */
+  from?: Date;
+  /** Last day shown; the latest entry by default. */
+  to?: Date;
+  scale?: "sequential" | "diverging";
+  domain?: readonly [number, number];
+  center?: number;
+  colors?: ScaleColors;
+  /** Stepped coloring, e.g. "Sin citas", "1-5", "6-10", "Más de 10". */
+  ranges?: readonly ColorRange[];
+  valueFormat?: ValueFormat;
+  /** Smallest cell in pixels; narrow containers show only the most recent weeks that fit. */
+  minCellSize?: number;
+  /**
+   * Height of the drawing in px or "fill". By default it follows the width:
+   * cells are square, so the height is the month header plus seven cell sides.
+   */
+  height?: number | "fill";
+  /** Width / height ratio; overrides the width-derived default height. */
+  aspectRatio?: number;
+  gap?: number;
+  radius?: number;
+  /** Weekday names Monday to Sunday; only Monday, Wednesday and Friday are drawn. */
+  weekdays?: readonly string[];
+  legend?: boolean;
+  tooltip?: boolean;
+  animate?: boolean;
+  loading?: boolean;
+  labels?: Partial<HeatmapLabels>;
+  onDayClick?: (day: CalendarDay) => void;
+  className?: string;
+}
+
+/** Largest square side when few weeks are shown. */
+const MAX_CELL = 40;
+
+/** How many week columns fit the width at the minimum cell size, and the weekday gutter. */
+function fitWeeks(
+  width: number,
+  totalWeeks: number,
+  minCellSize: number,
+  rowLabels: readonly string[],
+) {
+  const labelWidth = rowGutter(width, rowLabels);
+  const fit = Math.max(1, Math.floor((width - labelWidth) / minCellSize));
+  return { labelWidth, shown: Math.max(1, Math.min(totalWeeks, fit)) };
+}
+
+const WEEKDAYS = ["lun", "mar", "mié", "jue", "vie", "sáb", "dom"];
+
+/**
+ * Contribution-style calendar: one square per day, weeks as columns (Monday
+ * first), months labelled on top. Same color scales, ranges, crosshair and
+ * keyboard model as `HeatmapChart`.
+ */
+export function CalendarHeatmap({
+  title,
+  days,
+  from,
+  to,
+  scale = "sequential",
+  domain,
+  center = 0,
+  colors,
+  ranges,
+  valueFormat,
+  minCellSize = 11,
+  height,
+  aspectRatio,
+  gap = 3,
+  radius = 3,
+  weekdays = WEEKDAYS,
+  legend = true,
+  tooltip = true,
+  animate = true,
+  loading,
+  labels: labelsProp,
+  onDayClick,
+  className,
+}: CalendarHeatmapProps) {
+  const labels = resolveHeatmapLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const grid = useMemo(() => calendarGrid(days, from, to), [days, from, to]);
+  const finite = useMemo(
+    () =>
+      days
+        .map((day) => day.value)
+        .filter((value): value is number => typeof value === "number" && Number.isFinite(value)),
+    [days],
+  );
+  const colorScale = useMemo(
+    () => heatmapScale(finite, { scale, domain, center, colors, ranges }),
+    [finite, scale, domain, center, colors, ranges],
+  );
+  const rowLabels = weekdays.map((name, index) => (index % 2 === 0 && index < 6 ? name : ""));
+  const listed = useMemo(
+    () =>
+      grid.weeks.flatMap((_, week) =>
+        grid.cells.flatMap((row) => {
+          const cell = row[week];
+          return cell ? [cell] : [];
+        }),
+      ),
+    [grid],
+  );
+
+  const autoHeight = (width: number) => {
+    const { shown, labelWidth } = fitWeeks(width, grid.weeks.length, minCellSize, rowLabels);
+    const side = Math.min(MAX_CELL, (width - labelWidth) / shown);
+    return HEATMAP_TOP + 7 * side;
+  };
+
+  return (
+    <ChartFrame
+      height={height ?? autoHeight}
+      aspectRatio={aspectRatio}
+      labels={labels}
+      loading={loading}
+      empty={finite.length === 0}
+      skeleton="bars"
+      className={className}
+      footer={
+        legend ? (
+          <HeatmapLegend
+            kind={scale}
+            domain={colorScale.domain}
+            center={center}
+            colors={colors}
+            ranges={ranges}
+            format={format}
+          />
+        ) : null
+      }
+      table={
+        <ChartDataTable
+          caption={title}
+          categoryHeader={labels.category}
+          categories={listed.map((cell) => formatDate(cell.date))}
+          columns={[
+            {
+              id: "value",
+              name: title,
+              values: listed.map((cell) =>
+                cell.value == null ? labels.noData : format(cell.value),
+              ),
+            },
+          ]}
+        />
+      }
+    >
+      {(width, measuredHeight) => {
+        const { shown } = fitWeeks(width, grid.weeks.length, minCellSize, rowLabels);
+        const firstWeek = Math.max(0, grid.weeks.length - shown);
+        const weeks = grid.weeks.slice(firstWeek);
+        const columnLabels = weeks.map((_, index) => {
+          const start = grid.monthStarts.find((item) => item.week === index + firstWeek);
+          return start ? shortMonth(start.date) : index === 0 ? shortMonth(weeks[0] as Date) : null;
+        });
+        const values = grid.cells.map((row) =>
+          row.slice(firstWeek).map((cell) => (cell ? cell.value : undefined)),
+        );
+        return (
+          <HeatmapGrid
+            width={width}
+            height={measuredHeight}
+            title={title}
+            rowLabels={rowLabels}
+            columnLabels={columnLabels}
+            values={values}
+            colorScale={colorScale}
+            format={format}
+            cellTitle={(row, column) => {
+              const cell = grid.cells[row]?.[column + firstWeek];
+              return cell ? formatDate(cell.date) : "";
+            }}
+            labels={labels}
+            cellLabels={false}
+            gap={gap}
+            radius={radius}
+            square
+            valueName={title}
+            tooltip={tooltip}
+            animate={animate}
+            onCellClick={
+              onDayClick
+                ? ({ row, column }) => {
+                    const cell = grid.cells[row]?.[column + firstWeek];
+                    if (cell) onDayClick({ date: cell.date, value: cell.value });
+                  }
+                : undefined
+            }
+          />
+        );
+      }}
+    </ChartFrame>
+  );
+}

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

@@ -0,0 +1,68 @@
+export interface CalendarDay {
+  date: Date;
+  /** `null` marks a day without data (drawn as an empty cell). */
+  value: number | null;
+}
+
+export interface CalendarGrid {
+  /** Monday of every week, oldest first. */
+  weeks: Date[];
+  /** `cells[weekday][week]`, Monday = 0. `undefined` for days outside the range. */
+  cells: Array<Array<{ date: Date; value: number | null } | undefined>>;
+  /** Index of the first week of each month that starts inside the range. */
+  monthStarts: Array<{ week: number; date: Date }>;
+}
+
+function startOfDay(date: Date): Date {
+  const day = new Date(date);
+  day.setHours(0, 0, 0, 0);
+  return day;
+}
+
+/** Monday on or before `date`. */
+export function mondayOf(date: Date): Date {
+  const day = startOfDay(date);
+  day.setDate(day.getDate() - ((day.getDay() + 6) % 7));
+  return day;
+}
+
+function key(date: Date): string {
+  return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+}
+
+/**
+ * Lays days out like a contribution calendar: one column per week (Monday
+ * first), one row per weekday. Days between `from` and `to` without an entry
+ * get `null`; days outside are left `undefined`.
+ */
+export function calendarGrid(days: readonly CalendarDay[], from?: Date, to?: Date): CalendarGrid {
+  const times = days.map((day) => startOfDay(day.date).getTime());
+  const first = startOfDay(from ?? new Date(times.length ? Math.min(...times) : Date.now()));
+  const last = startOfDay(to ?? new Date(times.length ? Math.max(...times) : Date.now()));
+  const values = new Map<string, number | null>();
+  for (const day of days) values.set(key(day.date), day.value);
+
+  const weeks: Date[] = [];
+  for (let monday = mondayOf(first); monday <= last; ) {
+    weeks.push(new Date(monday));
+    monday = new Date(monday);
+    monday.setDate(monday.getDate() + 7);
+  }
+  const cells: CalendarGrid["cells"] = Array.from({ length: 7 }, () => weeks.map(() => undefined));
+  const monthStarts: CalendarGrid["monthStarts"] = [];
+  weeks.forEach((monday, week) => {
+    for (let weekday = 0; weekday < 7; weekday++) {
+      const date = new Date(monday);
+      date.setDate(monday.getDate() + weekday);
+      if (date < first || date > last) continue;
+      (cells[weekday] as Array<{ date: Date; value: number | null } | undefined>)[week] = {
+        date,
+        value: values.get(key(date)) ?? null,
+      };
+      if (date.getDate() === 1 || date.getTime() === first.getTime()) {
+        if (!monthStarts.some((start) => start.week === week)) monthStarts.push({ week, date });
+      }
+    }
+  });
+  return { weeks, cells, monthStarts };
+}

package/src/charts/heatmap-chart/datetime-columns.ts

@@ -0,0 +1,38 @@
+import { timeTicks } from "../core/scales/time.js";
+
+const clock = new Intl.DateTimeFormat("es-PE", { hour: "2-digit", minute: "2-digit" });
+
+/**
+ * Column labels for a heatmap whose columns are consecutive points in time.
+ * Spans of two days or more are labelled only at calendar boundaries (Mondays,
+ * first of the month, January) on the column closest to each boundary, the way
+ * a continuous time axis would; shorter spans label every column with its clock
+ * time and leave the thinning to the grid. Other columns get `null`.
+ */
+export function datetimeColumnLabels(
+  dates: ReadonlyArray<Date | number>,
+  maxLabels = 8,
+): Array<string | null> {
+  const times = dates.map((date) => +date);
+  if (times.length === 0) return [];
+  const first = times[0] as number;
+  const last = times[times.length - 1] as number;
+  const gaps = times.slice(1).map((time, index) => time - (times[index] as number));
+  const step = gaps.length ? [...gaps].sort((a, b) => a - b)[Math.floor(gaps.length / 2)] || 1 : 1;
+  const ticks = last - first >= 2 * 86_400_000 ? timeTicks(first, last, maxLabels) : [];
+  if (ticks.length < 2) return times.map((time) => clock.format(time));
+  const labels: Array<string | null> = times.map(() => null);
+  for (const tick of ticks) {
+    let best = -1;
+    let distance = Number.POSITIVE_INFINITY;
+    times.forEach((time, index) => {
+      const d = Math.abs(time - tick.value);
+      if (d < distance) {
+        best = index;
+        distance = d;
+      }
+    });
+    if (best >= 0 && distance <= step && labels[best] == null) labels[best] = tick.label;
+  }
+  return labels;
+}

package/src/charts/heatmap-chart/drilldown-heatmap.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { useState } from "react";
+import { cn } from "../../utils/cn.js";
+import { ChartBreadcrumb } from "../core/breadcrumb.js";
+import type { ValueFormat } from "../core/format.js";
+import { HeatmapChart, type HeatmapChartProps } from "./heatmap-chart.js";
+import type { HeatmapCellInfo } from "./heatmap-grid.js";
+
+/** One matrix of a drill-down: the root, or the detail behind a cell. */
+export interface HeatmapLevel {
+  /** Name in the breadcrumb and, unless `title` is set, the chart title. */
+  name: string;
+  title?: string;
+  rows: readonly string[];
+  columns: ReadonlyArray<string | Date>;
+  values: ReadonlyArray<ReadonlyArray<number | null>>;
+  /** Fixed color domain of this level; the data extent by default. */
+  domain?: readonly [number, number];
+  valueFormat?: ValueFormat;
+  /**
+   * Detail behind a cell (for example the days of a month, or the hours of a
+   * day). Return null or undefined when the cell has nothing underneath.
+   */
+  drill?: (cell: HeatmapCellInfo) => HeatmapLevel | null | undefined;
+}
+
+export interface DrilldownHeatmapProps
+  extends Omit<
+    HeatmapChartProps,
+    "title" | "rows" | "columns" | "values" | "domain" | "valueFormat" | "onCellClick"
+  > {
+  /** Accessible name when a level has no `title`. */
+  title: string;
+  root: HeatmapLevel;
+  /** Accessible name of the breadcrumb landmark. */
+  breadcrumbLabel?: string;
+  onLevelChange?: (path: readonly HeatmapLevel[]) => void;
+}
+
+/**
+ * Heatmap you can dive into: click (or press Enter on) a cell to open the
+ * matrix behind it. The breadcrumb above climbs back to any earlier level.
+ */
+export function DrilldownHeatmap({
+  title,
+  root,
+  breadcrumbLabel = "Path",
+  onLevelChange,
+  className,
+  ...chart
+}: DrilldownHeatmapProps) {
+  const [path, setPath] = useState<readonly HeatmapLevel[]>([root]);
+  // A new root (new data) starts again from the top.
+  const [seenRoot, setSeenRoot] = useState(root);
+  if (seenRoot !== root) {
+    setSeenRoot(root);
+    setPath([root]);
+  }
+  const level = path[path.length - 1] as HeatmapLevel;
+  const move = (next: readonly HeatmapLevel[]) => {
+    setPath(next);
+    onLevelChange?.(next);
+  };
+  const open = (cell: HeatmapCellInfo) => {
+    const child = level.drill?.(cell);
+    if (child) move([...path, child]);
+  };
+  return (
+    <div className={cn("@container flex min-w-0 flex-col gap-2", className)}>
+      {path.length > 1 ? (
+        <ChartBreadcrumb
+          label={breadcrumbLabel}
+          items={path.map((item, index) => ({ id: String(index), name: item.name }))}
+          onSelect={(id) => move(path.slice(0, Number(id) + 1))}
+          className="px-1"
+        />
+      ) : null}
+      <HeatmapChart
+        key={path.map((item) => item.name).join("/")}
+        {...chart}
+        title={level.title ?? (path.length > 1 ? level.name : title)}
+        rows={level.rows}
+        columns={level.columns}
+        values={level.values}
+        domain={level.domain}
+        valueFormat={level.valueFormat}
+        onCellClick={level.drill ? open : undefined}
+      />
+    </div>
+  );
+}

package/src/charts/heatmap-chart/heatmap-chart.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { useMemo } from "react";
+import { ChartFrame } from "../core/chart-frame.js";
+import type { ColorRange, ScaleColors } from "../core/color-scale.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat, type ValueFormat } from "../core/format.js";
+import { formatDate } from "../core/scales/time.js";
+import { datetimeColumnLabels } from "./datetime-columns.js";
+import {
+  type HeatmapCellInfo,
+  HeatmapGrid,
+  type HeatmapLabels,
+  HeatmapLegend,
+  resolveHeatmapLabels,
+} from "./heatmap-grid.js";
+import { heatmapScale } from "./heatmap-scale.js";
+
+export interface HeatmapChartProps {
+  /** Accessible name of the drawing and caption of the data table. */
+  title: string;
+  /** Row names, top to bottom. */
+  rows: readonly string[];
+  /**
+   * Column names, left to right. When every column is a `Date` the columns are
+   * consecutive points in time: the header is labelled only at calendar
+   * boundaries (weeks, months, years), like a continuous time axis.
+   */
+  columns: ReadonlyArray<string | Date>;
+  /** `values[row][column]`; `null` is a cell without data. */
+  values: ReadonlyArray<ReadonlyArray<number | null>>;
+  /** "sequential" (empty to brand) or "diverging" (low hue, neutral at `center`, brand). */
+  scale?: "sequential" | "diverging";
+  /** Fixed [min, max] of the color scale; the data extent by default. */
+  domain?: readonly [number, number];
+  /** Neutral value of a diverging scale. */
+  center?: number;
+  /** Override the scale colors (CSS colors or tokens). */
+  colors?: ScaleColors;
+  /** Stepped coloring by ranges or thresholds; replaces the continuous scale. */
+  ranges?: readonly ColorRange[];
+  valueFormat?: ValueFormat;
+  /** Values inside the cells (only where they fit). */
+  cellLabels?: boolean;
+  /** Gap between cells in pixels. */
+  gap?: number;
+  radius?: number;
+  /** "hex" draws a honeycomb: pointy-top hexagons with odd rows shifted half a cell. */
+  shape?: "rect" | "hex";
+  /**
+   * "canvas" paints the cells on a canvas, for matrices with tens of thousands
+   * of cells. Labels, tooltip, focus ring and keyboard stay SVG/HTML.
+   */
+  renderer?: "svg" | "canvas";
+  /** Height of the drawing in px or "fill"; 34 px per row plus the column header by default. */
+  height?: number | "fill";
+  /** Width / height ratio; sizes the drawing from the container width. */
+  aspectRatio?: number;
+  /** Color key (gradient bar or range swatches). */
+  legend?: boolean;
+  tooltip?: boolean;
+  animate?: boolean;
+  loading?: boolean;
+  labels?: Partial<HeatmapLabels>;
+  onCellClick?: (cell: HeatmapCellInfo) => void;
+  className?: string;
+}
+
+/**
+ * Matrix heatmap: one colored cell per row × column, e.g. occupancy by hour
+ * and weekday. Continuous sequential or diverging scales come from tokens;
+ * `ranges` switches to stepped colors. Hover and keyboard focus light the
+ * row and column of the cell.
+ */
+export function HeatmapChart({
+  title,
+  rows,
+  columns,
+  values,
+  scale = "sequential",
+  domain,
+  center = 0,
+  colors,
+  ranges,
+  valueFormat,
+  cellLabels = false,
+  gap = 3,
+  radius = 4,
+  shape = "rect",
+  renderer = "svg",
+  height,
+  aspectRatio,
+  legend = true,
+  tooltip = true,
+  animate = true,
+  loading,
+  labels: labelsProp,
+  onCellClick,
+  className,
+}: HeatmapChartProps) {
+  const labels = resolveHeatmapLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const finite = useMemo(
+    () =>
+      values.flatMap((row) =>
+        row.filter((value): value is number => typeof value === "number" && Number.isFinite(value)),
+      ),
+    [values],
+  );
+  const colorScale = useMemo(
+    () => heatmapScale(finite, { scale, domain, center, colors, ranges }),
+    [finite, scale, domain, center, colors, ranges],
+  );
+  const dated = columns.length > 0 && columns.every((column) => column instanceof Date);
+  const columnText = useMemo(
+    () => columns.map((column) => (column instanceof Date ? formatDate(column) : column)),
+    [columns],
+  );
+  // A table with every cell of a dense canvas matrix would defeat the canvas.
+  const tableRows = renderer === "canvas" ? rows.slice(0, 60) : rows;
+  const tableColumns = renderer === "canvas" ? columnText.slice(0, 40) : columnText;
+  const drawingHeight = height ?? Math.max(120, rows.length * 34 + 22);
+  return (
+    <ChartFrame
+      height={drawingHeight}
+      aspectRatio={aspectRatio}
+      labels={labels}
+      loading={loading}
+      empty={finite.length === 0 || rows.length === 0 || columns.length === 0}
+      skeleton="bars"
+      className={className}
+      footer={
+        legend ? (
+          <HeatmapLegend
+            kind={scale}
+            domain={colorScale.domain}
+            center={center}
+            colors={colors}
+            ranges={ranges}
+            format={format}
+          />
+        ) : null
+      }
+      table={
+        <ChartDataTable
+          caption={title}
+          categoryHeader={labels.category}
+          categories={tableRows}
+          columns={tableColumns.map((column, index) => ({
+            id: `${index}`,
+            name: column,
+            values: tableRows.map((_, row) => {
+              const value = values[row]?.[index];
+              return value == null ? labels.noData : format(value);
+            }),
+          }))}
+        />
+      }
+    >
+      {(width, measuredHeight) => (
+        <HeatmapGrid
+          width={width}
+          height={measuredHeight}
+          title={title}
+          rowLabels={rows}
+          columnLabels={
+            dated
+              ? datetimeColumnLabels(columns as Date[], Math.max(2, Math.floor(width / 72)))
+              : columnText
+          }
+          values={values}
+          colorScale={colorScale}
+          format={format}
+          cellTitle={(row, column) => `${rows[row] ?? ""} · ${columnText[column] ?? ""}`}
+          labels={labels}
+          cellLabels={cellLabels}
+          gap={gap}
+          radius={radius}
+          square={false}
+          shape={shape}
+          renderer={renderer}
+          tooltip={tooltip}
+          animate={animate}
+          onCellClick={onCellClick}
+        />
+      )}
+    </ChartFrame>
+  );
+}