@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/heatmap-chart/calendar-heatmap.js

@@ -0,0 +1,159 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat } from "../core/format.js";
+import { formatDate, shortMonth } from "../core/scales/time.js";
+import { calendarGrid } from "./calendar-layout.js";
+import {
+  HEATMAP_TOP,
+  HeatmapGrid,
+  HeatmapLegend,
+  resolveHeatmapLabels,
+  rowGutter
+} from "./heatmap-grid.js";
+import { heatmapScale } from "./heatmap-scale.js";
+const MAX_CELL = 40;
+function fitWeeks(width, totalWeeks, minCellSize, rowLabels) {
+  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\xE9", "jue", "vie", "s\xE1b", "dom"];
+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
+}) {
+  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) => 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) => {
+    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 /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: height ?? autoHeight,
+      aspectRatio,
+      labels,
+      loading,
+      empty: finite.length === 0,
+      skeleton: "bars",
+      className,
+      footer: legend ? /* @__PURE__ */ jsx(
+        HeatmapLegend,
+        {
+          kind: scale,
+          domain: colorScale.domain,
+          center,
+          colors,
+          ranges,
+          format
+        }
+      ) : null,
+      table: /* @__PURE__ */ jsx(
+        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)
+              )
+            }
+          ]
+        }
+      ),
+      children: (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]) : null;
+        });
+        const values = grid.cells.map(
+          (row) => row.slice(firstWeek).map((cell) => cell ? cell.value : void 0)
+        );
+        return /* @__PURE__ */ jsx(
+          HeatmapGrid,
+          {
+            width,
+            height: measuredHeight,
+            title,
+            rowLabels,
+            columnLabels,
+            values,
+            colorScale,
+            format,
+            cellTitle: (row, column) => {
+              const cell = grid.cells[row]?.[column + firstWeek];
+              return cell ? formatDate(cell.date) : "";
+            },
+            labels,
+            cellLabels: false,
+            gap,
+            radius,
+            square: true,
+            valueName: title,
+            tooltip,
+            animate,
+            onCellClick: onDayClick ? ({ row, column }) => {
+              const cell = grid.cells[row]?.[column + firstWeek];
+              if (cell) onDayClick({ date: cell.date, value: cell.value });
+            } : void 0
+          }
+        );
+      }
+    }
+  );
+}
+export {
+  CalendarHeatmap
+};

package/dist/charts/heatmap-chart/calendar-layout.d.ts

@@ -0,0 +1,27 @@
+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;
+    }>;
+}
+/** Monday on or before `date`. */
+export declare function mondayOf(date: Date): Date;
+/**
+ * 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 declare function calendarGrid(days: readonly CalendarDay[], from?: Date, to?: Date): CalendarGrid;

package/dist/charts/heatmap-chart/calendar-layout.js

@@ -0,0 +1,47 @@
+function startOfDay(date) {
+  const day = new Date(date);
+  day.setHours(0, 0, 0, 0);
+  return day;
+}
+function mondayOf(date) {
+  const day = startOfDay(date);
+  day.setDate(day.getDate() - (day.getDay() + 6) % 7);
+  return day;
+}
+function key(date) {
+  return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`;
+}
+function calendarGrid(days, from, to) {
+  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 = /* @__PURE__ */ new Map();
+  for (const day of days) values.set(key(day.date), day.value);
+  const weeks = [];
+  for (let monday = mondayOf(first); monday <= last; ) {
+    weeks.push(new Date(monday));
+    monday = new Date(monday);
+    monday.setDate(monday.getDate() + 7);
+  }
+  const cells = Array.from({ length: 7 }, () => weeks.map(() => void 0));
+  const 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][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 };
+}
+export {
+  calendarGrid,
+  mondayOf
+};

package/dist/charts/heatmap-chart/datetime-columns.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function datetimeColumnLabels(dates: ReadonlyArray<Date | number>, maxLabels?: number): Array<string | null>;

package/dist/charts/heatmap-chart/datetime-columns.js

@@ -0,0 +1,29 @@
+import { timeTicks } from "../core/scales/time.js";
+const clock = new Intl.DateTimeFormat("es-PE", { hour: "2-digit", minute: "2-digit" });
+function datetimeColumnLabels(dates, maxLabels = 8) {
+  const times = dates.map((date) => +date);
+  if (times.length === 0) return [];
+  const first = times[0];
+  const last = times[times.length - 1];
+  const gaps = times.slice(1).map((time, index) => time - times[index]);
+  const step = gaps.length ? [...gaps].sort((a, b) => a - b)[Math.floor(gaps.length / 2)] || 1 : 1;
+  const ticks = last - first >= 2 * 864e5 ? timeTicks(first, last, maxLabels) : [];
+  if (ticks.length < 2) return times.map((time) => clock.format(time));
+  const labels = 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;
+}
+export {
+  datetimeColumnLabels
+};

package/dist/charts/heatmap-chart/drilldown-heatmap.d.ts

@@ -0,0 +1,33 @@
+import type { ValueFormat } from "../core/format.js";
+import { 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 declare function DrilldownHeatmap({ title, root, breadcrumbLabel, onLevelChange, className, ...chart }: DrilldownHeatmapProps): import("react").JSX.Element;

package/dist/charts/heatmap-chart/drilldown-heatmap.js

@@ -0,0 +1,58 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "../../utils/cn.js";
+import { ChartBreadcrumb } from "../core/breadcrumb.js";
+import { HeatmapChart } from "./heatmap-chart.js";
+function DrilldownHeatmap({
+  title,
+  root,
+  breadcrumbLabel = "Path",
+  onLevelChange,
+  className,
+  ...chart
+}) {
+  const [path, setPath] = useState([root]);
+  const [seenRoot, setSeenRoot] = useState(root);
+  if (seenRoot !== root) {
+    setSeenRoot(root);
+    setPath([root]);
+  }
+  const level = path[path.length - 1];
+  const move = (next) => {
+    setPath(next);
+    onLevelChange?.(next);
+  };
+  const open = (cell) => {
+    const child = level.drill?.(cell);
+    if (child) move([...path, child]);
+  };
+  return /* @__PURE__ */ jsxs("div", { className: cn("@container flex min-w-0 flex-col gap-2", className), children: [
+    path.length > 1 ? /* @__PURE__ */ jsx(
+      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,
+    /* @__PURE__ */ jsx(
+      HeatmapChart,
+      {
+        ...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 : void 0
+      },
+      path.map((item) => item.name).join("/")
+    )
+  ] });
+}
+export {
+  DrilldownHeatmap
+};

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

@@ -0,0 +1,59 @@
+import type { ColorRange, ScaleColors } from "../core/color-scale.js";
+import { type ValueFormat } from "../core/format.js";
+import { type HeatmapCellInfo, type HeatmapLabels } from "./heatmap-grid.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 declare function HeatmapChart({ title, rows, columns, values, scale, domain, center, colors, ranges, valueFormat, cellLabels, gap, radius, shape, renderer, height, aspectRatio, legend, tooltip, animate, loading, labels: labelsProp, onCellClick, className, }: HeatmapChartProps): import("react").JSX.Element;

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

@@ -0,0 +1,127 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveFormat } from "../core/format.js";
+import { formatDate } from "../core/scales/time.js";
+import { datetimeColumnLabels } from "./datetime-columns.js";
+import {
+  HeatmapGrid,
+  HeatmapLegend,
+  resolveHeatmapLabels
+} from "./heatmap-grid.js";
+import { heatmapScale } from "./heatmap-scale.js";
+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
+}) {
+  const labels = resolveHeatmapLabels(labelsProp);
+  const format = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const finite = useMemo(
+    () => values.flatMap(
+      (row) => row.filter((value) => 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]
+  );
+  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 /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: drawingHeight,
+      aspectRatio,
+      labels,
+      loading,
+      empty: finite.length === 0 || rows.length === 0 || columns.length === 0,
+      skeleton: "bars",
+      className,
+      footer: legend ? /* @__PURE__ */ jsx(
+        HeatmapLegend,
+        {
+          kind: scale,
+          domain: colorScale.domain,
+          center,
+          colors,
+          ranges,
+          format
+        }
+      ) : null,
+      table: /* @__PURE__ */ jsx(
+        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);
+            })
+          }))
+        }
+      ),
+      children: (width, measuredHeight) => /* @__PURE__ */ jsx(
+        HeatmapGrid,
+        {
+          width,
+          height: measuredHeight,
+          title,
+          rowLabels: rows,
+          columnLabels: dated ? datetimeColumnLabels(columns, Math.max(2, Math.floor(width / 72))) : columnText,
+          values,
+          colorScale,
+          format,
+          cellTitle: (row, column) => `${rows[row] ?? ""} \xB7 ${columnText[column] ?? ""}`,
+          labels,
+          cellLabels,
+          gap,
+          radius,
+          square: false,
+          shape,
+          renderer,
+          tooltip,
+          animate,
+          onCellClick
+        }
+      )
+    }
+  );
+}
+export {
+  HeatmapChart
+};

package/dist/charts/heatmap-chart/heatmap-grid.d.ts

@@ -0,0 +1,75 @@
+import { type ColorRange, type ScaleColors } from "../core/color-scale.js";
+import type { ValueFormatter } from "../core/format.js";
+import { type ChartLabels } from "../core/types.js";
+import type { HeatmapScale } from "./heatmap-scale.js";
+/** Visible strings of the heatmaps. */
+export interface HeatmapLabels extends ChartLabels {
+    /** Tooltip value of a cell without data. */
+    noData: string;
+}
+export declare const DEFAULT_HEATMAP_LABELS: HeatmapLabels;
+export declare function resolveHeatmapLabels(labels?: Partial<HeatmapLabels>): HeatmapLabels;
+/** A cell: a number, `null` for no data (drawn empty), `undefined` for no cell at all. */
+export type HeatmapValue = number | null | undefined;
+export interface HeatmapCellInfo {
+    row: number;
+    column: number;
+    value: number | null;
+}
+export interface HeatmapGridProps {
+    width: number;
+    height: number;
+    title: string;
+    rowLabels: readonly string[];
+    /** `null` leaves a column without a label (e.g. calendar weeks inside a month). */
+    columnLabels: ReadonlyArray<string | null>;
+    /** `values[row][column]`. */
+    values: ReadonlyArray<ReadonlyArray<HeatmapValue>>;
+    colorScale: HeatmapScale;
+    format: ValueFormatter;
+    /** Tooltip title and spoken name of a cell. */
+    cellTitle: (row: number, column: number) => string;
+    labels: HeatmapLabels;
+    cellLabels: boolean;
+    gap: number;
+    radius: number;
+    /** Square cells (calendar) instead of filling the whole area. */
+    square: boolean;
+    tooltip: boolean;
+    animate: boolean;
+    onCellClick?: (cell: HeatmapCellInfo) => void;
+    /** Name of the value in the tooltip; the row label by default. */
+    valueName?: string;
+    /** "hex" lays the cells out as a honeycomb (odd rows shifted half a cell). */
+    shape?: "rect" | "hex";
+    /**
+     * "canvas" paints the cells on a canvas for very large matrices. Labels,
+     * focus ring, tooltip and keyboard stay SVG/HTML; the crosshair dimming is
+     * skipped because it would repaint every cell on each pointer move.
+     */
+    renderer?: "svg" | "canvas";
+}
+/** Height of the column-label header above the cells. */
+export declare const HEATMAP_TOP = 22;
+/** Width of the row-label gutter, from the measured labels (capped on narrow containers). */
+export declare function rowGutter(width: number, rowLabels: readonly string[]): number;
+/**
+ * Rows × columns of colored cells. Hover (or keyboard focus) lights its row and
+ * column like a crosshair and dims the rest. Column labels thin out when they
+ * would collide; cell values only show where they fit.
+ */
+export declare function HeatmapGrid({ width, height, title, rowLabels, columnLabels, values, colorScale, format, cellTitle, labels, cellLabels, gap, radius, square, tooltip, animate, onCellClick, valueName, shape, renderer, }: HeatmapGridProps): import("react").JSX.Element;
+export interface HeatmapLegendProps {
+    kind: "sequential" | "diverging";
+    domain: readonly [number, number];
+    center?: number;
+    colors?: ScaleColors;
+    ranges?: readonly ColorRange[];
+    format: ValueFormatter;
+}
+/**
+ * Color key: a gradient bar with its extremes (and center when diverging), or
+ * one swatch per range. Sits below the drawing in narrow containers and above
+ * it, aligned to the end, from `@md`.
+ */
+export declare function HeatmapLegend({ kind, domain, center, colors, ranges, format, }: HeatmapLegendProps): import("react").JSX.Element;