@jorgerdz/timeview 0.1.0

package/src/timeview/DensityHeatmap.tsx

@@ -0,0 +1,513 @@
+// DensityHeatmap.tsx — Timeview aggregation view.
+//
+// Renders a TimeDataset as a {category × time-bucket} density matrix. The
+// bucketing math lives in core/aggregate; this file is presentational.
+
+import { Fragment, useMemo, useState } from "react";
+import type { CSSProperties } from "react";
+import { DAY_MS, fmt } from "./core/time";
+import { tvAggregate, tvFmtDuration } from "./core/aggregate";
+import type { AggregateCell, AggregateGroup, AggregateItem, TimeBucket } from "./core/aggregate";
+import { colorMap, mix } from "./core/labels";
+import { Caption } from "./shared/Caption";
+import { EmptyState } from "./shared/EmptyState";
+import { useMeasuredWidth } from "./shared/useMeasuredWidth";
+import type { Density, DensityHeatmapSpec, TimeDataset } from "./types";
+
+export interface DensityHeatmapProps {
+  /** schema `timeview.dataset.v1` */
+  dataset: TimeDataset;
+  /** aggregation projection (bucket, measure, grouping, heat scale, caption...) */
+  spec: DensityHeatmapSpec;
+  /** colors mapped to `dataset.labels` by index */
+  palette: string[];
+}
+
+const HM_SLATE = "#475569";
+
+interface DensitySpec {
+  pad: number;
+  rowH: number;
+  labelW: number;
+  cellMin: number;
+  head: number;
+  num: number;
+}
+
+const DENS: Record<Density, DensitySpec> = {
+  comfortable: { pad: 22, rowH: 34, labelW: 138, cellMin: 34, head: 30, num: 11.5 },
+  compact: { pad: 16, rowH: 27, labelW: 116, cellMin: 27, head: 26, num: 10.5 },
+};
+
+type Hover = {
+  id: string;
+  g: AggregateGroup;
+  b: TimeBucket;
+  cell: AggregateCell;
+  base: string;
+  mx: number;
+  my: number;
+};
+
+function hmFill(t: number, base: string, empty: boolean): string {
+  if (empty) return "var(--tv-rail)";
+  const pct = 16 + Math.pow(t, 0.85) * 76;
+  return mix(base, pct);
+}
+
+function hmInkOn(t: number): string {
+  return t > 0.52 ? "#fff" : "var(--tv-ink-2)";
+}
+
+export function DensityHeatmap({ dataset, spec, palette }: DensityHeatmapProps) {
+  const [wrapRef, w] = useMeasuredWidth<HTMLDivElement>();
+  const [hover, setHover] = useState<Hover | null>(null);
+  const [sel, setSel] = useState<string | null>(null);
+
+  const density: Density = spec.density || "comfortable";
+  const D = DENS[density] || DENS.comfortable;
+  const measure = spec.measure || "count";
+  const bucketMode = spec.bucket || "day";
+  const groupBy = spec.groupBy || "category";
+  const scaleMode = spec.scaleMode || "category";
+  const showValues = spec.showValues !== false;
+  const captionPos = spec.caption?.position || "bottom";
+  const captionText = spec.caption?.text || "";
+  const captionOn = captionPos !== "off" && !!captionText;
+  const narrow = w < 560;
+
+  const cmap = useMemo(() => colorMap(dataset, palette), [dataset, palette]);
+  const agg = useMemo(() => tvAggregate(dataset, { bucket: bucketMode, measure, groupBy }), [dataset, bucketMode, measure, groupBy]);
+  const isEmpty = agg.max === 0;
+  const labelW = narrow ? Math.max(84, D.labelW - 30) : D.labelW;
+  const baseFor = (g: AggregateGroup) => (scaleMode === "uniform" || groupBy === "none" ? HM_SLATE : cmap[g.labelId || ""] || HM_SLATE);
+  const t01 = (v: number) => (agg.max > 0 ? v / agg.max : 0);
+
+  const track = (e: { clientX: number; clientY: number }) => {
+    const r = wrapRef.current!.getBoundingClientRect();
+    return { mx: e.clientX - r.left, my: e.clientY - r.top };
+  };
+
+  const cellLabel = (cell: AggregateCell) => {
+    if (measure === "duration") return cell.durationMs > 0 ? tvFmtDuration(cell.durationMs) : "";
+    return cell.count > 0 ? String(cell.count) : "";
+  };
+
+  const ScaleKey = () => {
+    const steps = [0, 0.18, 0.42, 0.7, 1];
+    const unit = measure === "duration" ? "duration" : "count";
+    const maxLabel = measure === "duration" ? tvFmtDuration(agg.max) : agg.max;
+    return (
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 10,
+          flexWrap: "wrap",
+          padding: "14px 0 2px",
+          borderTop: "1px solid var(--tv-line)",
+          marginTop: 6,
+        }}
+      >
+        <span
+          style={{
+            fontFamily: "var(--tv-mono)",
+            fontSize: 10,
+            letterSpacing: ".08em",
+            textTransform: "uppercase",
+            color: "var(--tv-ink-4)",
+          }}
+        >
+          Density · {unit}
+        </span>
+        <div style={{ display: "flex", alignItems: "center", gap: 4 }}>
+          <span style={{ fontFamily: "var(--tv-mono)", fontSize: 10.5, color: "var(--tv-ink-4)" }}>0</span>
+          <div style={{ display: "flex", gap: 2 }}>
+            {steps.map((s, i) => (
+              <span
+                key={i}
+                title={i === 0 ? "empty" : undefined}
+                style={{
+                  width: 22,
+                  height: 13,
+                  borderRadius: 3,
+                  background: hmFill(s, HM_SLATE, s === 0),
+                  boxShadow: "inset 0 0 0 1px rgba(16,24,40,0.06)",
+                }}
+              />
+            ))}
+          </div>
+          <span style={{ fontFamily: "var(--tv-mono)", fontSize: 10.5, color: "var(--tv-ink-3)" }}>{maxLabel}</span>
+        </div>
+        {scaleMode === "category" && groupBy === "category" && (
+          <span style={{ fontFamily: "var(--tv-font)", fontSize: 11.5, color: "var(--tv-ink-4)" }}>
+            · each row ramps its own category hue
+          </span>
+        )}
+      </div>
+    );
+  };
+
+  const stickyCol: CSSProperties = { position: "sticky", left: 0, zIndex: 3, background: "var(--tv-canvas)" };
+  const gridCols = `${labelW}px repeat(${agg.buckets.length}, minmax(${D.cellMin}px, 1fr))`;
+  const innerMin = labelW + agg.buckets.length * D.cellMin;
+
+  return (
+    <div
+      ref={wrapRef}
+      className="tv-component"
+      style={{
+        background: "var(--tv-canvas)",
+        border: "1px solid var(--tv-line)",
+        borderRadius: "var(--tv-r-lg)",
+        boxShadow: "var(--tv-shadow-1)",
+        padding: D.pad,
+        fontFamily: "var(--tv-font)",
+        color: "var(--tv-ink)",
+        position: "relative",
+        width: "100%",
+        overflow: "hidden",
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 12, marginBottom: 6, flexWrap: "wrap" }}>
+        <div
+          style={{
+            fontSize: narrow ? 15 : 17,
+            fontWeight: 600,
+            letterSpacing: "-0.01em",
+            color: "var(--tv-ink)",
+            lineHeight: 1.25,
+            minWidth: 0,
+          }}
+        >
+          {spec.title || dataset.meta?.title}
+        </div>
+        <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-4)", whiteSpace: "nowrap", flex: "none" }}>
+          {fmt.monDay(agg.t0)} – {fmt.monDay(new Date(agg.t1 - DAY_MS))}
+        </div>
+      </div>
+
+      <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-3)", marginBottom: 16 }}>
+        {measure === "duration" ? "active duration" : "item count"} · per {bucketMode} · by {groupBy === "none" ? "total" : "category"}
+      </div>
+
+      {captionOn && captionPos === "top" && <Caption position={captionPos} text={captionText} narrow={narrow} />}
+
+      <div
+        style={{
+          position: "relative",
+          overflowX: "auto",
+          overflowY: "hidden",
+          border: "1px solid var(--tv-line)",
+          borderRadius: "var(--tv-r-md)",
+        }}
+      >
+        <div style={{ display: "grid", gridTemplateColumns: gridCols, minWidth: innerMin }}>
+          <div
+            style={{
+              ...stickyCol,
+              height: D.head,
+              borderBottom: "1px solid var(--tv-line)",
+              display: "flex",
+              alignItems: "center",
+              paddingLeft: 11,
+            }}
+          >
+            <span
+              style={{
+                fontFamily: "var(--tv-mono)",
+                fontSize: 10,
+                letterSpacing: ".06em",
+                textTransform: "uppercase",
+                color: "var(--tv-ink-4)",
+              }}
+            >
+              {bucketMode === "week" ? "Week" : "Day"}
+            </span>
+          </div>
+
+          {agg.buckets.map((b) => {
+            const strong = b.mode === "week" || b.isMonday;
+            const monthStart = b.mode === "day" && new Date(b.start).getUTCDate() === 1;
+            return (
+              <div
+                key={b.key}
+                style={{
+                  height: D.head,
+                  borderBottom: "1px solid var(--tv-line)",
+                  borderLeft: `1px solid ${strong ? "var(--tv-grid-week)" : "var(--tv-grid)"}`,
+                  display: "flex",
+                  flexDirection: "column",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  background: b.isWeekend ? "var(--tv-rail)" : "transparent",
+                  gap: 1,
+                  overflow: "hidden",
+                }}
+              >
+                <span
+                  style={{
+                    fontFamily: "var(--tv-mono)",
+                    fontSize: 11,
+                    fontWeight: 600,
+                    color: monthStart ? "var(--tv-accent)" : "var(--tv-ink-2)",
+                    lineHeight: 1,
+                  }}
+                >
+                  {b.label}
+                </span>
+                {!narrow && (
+                  <span style={{ fontFamily: "var(--tv-font)", fontSize: 9, color: "var(--tv-ink-4)", lineHeight: 1 }}>{b.sub}</span>
+                )}
+              </div>
+            );
+          })}
+
+          {agg.groups.map((g, gi) => {
+            const base = baseFor(g);
+            const last = gi === agg.groups.length - 1;
+            return (
+              <Fragment key={g.id}>
+                <div
+                  key={g.id + "-label"}
+                  style={{
+                    ...stickyCol,
+                    height: D.rowH,
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 8,
+                    padding: "0 10px",
+                    borderBottom: last ? "none" : "1px solid var(--tv-grid)",
+                    boxShadow: "1px 0 0 var(--tv-line)",
+                  }}
+                >
+                  <span
+                    style={{
+                      width: 9,
+                      height: 9,
+                      borderRadius: 2,
+                      background: base,
+                      flex: "none",
+                      boxShadow: "inset 0 0 0 1px rgba(0,0,0,0.14)",
+                    }}
+                  />
+                  <span
+                    style={{
+                      fontFamily: "var(--tv-font)",
+                      fontSize: narrow ? 11.5 : 12.5,
+                      fontWeight: 500,
+                      color: "var(--tv-ink-2)",
+                      whiteSpace: "nowrap",
+                      overflow: "hidden",
+                      textOverflow: "ellipsis",
+                    }}
+                  >
+                    {g.name}
+                  </span>
+                </div>
+
+                {agg.buckets.map((b) => {
+                  const cell = agg.cells[g.id][b.key];
+                  const v = agg.value(cell);
+                  const t = t01(v);
+                  const empty = v === 0;
+                  const strong = b.mode === "week" || b.isMonday;
+                  const id = g.id + "|" + b.key;
+                  const hovered = hover?.id === id;
+                  const selected = sel === id;
+                  const txt = showValues ? cellLabel(cell) : "";
+                  return (
+                    <div
+                      key={g.id + b.key}
+                      tabIndex={0}
+                      role="button"
+                      aria-label={`${g.name}, ${b.mode === "week" ? "week of " : ""}${fmt.monDay(new Date(b.start))}: ${cell.count} items${
+                        measure === "duration" ? ", " + tvFmtDuration(cell.durationMs) : ""
+                      }`}
+                      onMouseEnter={(e) => setHover({ id, g, b, cell, base, ...track(e) })}
+                      onMouseMove={(e) => setHover({ id, g, b, cell, base, ...track(e) })}
+                      onFocus={() => setHover({ id, g, b, cell, base, mx: labelW + b.index * 40, my: 80 + gi * D.rowH })}
+                      onMouseLeave={() => setHover(null)}
+                      onBlur={() => setHover(null)}
+                      onClick={() => setSel((s) => (s === id ? null : id))}
+                      style={{
+                        height: D.rowH,
+                        borderBottom: last ? "none" : "1px solid var(--tv-canvas)",
+                        borderLeft: `1px solid ${empty ? (strong ? "var(--tv-grid-week)" : "var(--tv-grid)") : "rgba(255,255,255,0.7)"}`,
+                        background: hmFill(t, base, empty),
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        cursor: "pointer",
+                        outline: "none",
+                        position: "relative",
+                        boxShadow: selected
+                          ? "var(--tv-focus-ring)"
+                          : hovered
+                            ? "inset 0 0 0 2px rgba(255,255,255,0.85), var(--tv-shadow-pop)"
+                            : "none",
+                        zIndex: hovered || selected ? 4 : "auto",
+                        transition: "box-shadow var(--tv-fast) var(--tv-ease)",
+                      }}
+                    >
+                      {txt && (
+                        <span
+                          style={{
+                            fontFamily: "var(--tv-mono)",
+                            fontSize: D.num,
+                            fontWeight: 600,
+                            color: hmInkOn(t),
+                            lineHeight: 1,
+                            pointerEvents: "none",
+                          }}
+                        >
+                          {txt}
+                        </span>
+                      )}
+                    </div>
+                  );
+                })}
+              </Fragment>
+            );
+          })}
+        </div>
+
+        {isEmpty && (
+          <EmptyState title="No activity in this window" icon="grid" background narrow={narrow} />
+        )}
+      </div>
+
+      <ScaleKey />
+      {captionOn && captionPos === "bottom" && <Caption position={captionPos} text={captionText} narrow={narrow} />}
+
+      {hover && (
+        <HeatmapTooltip
+          left={Math.max(8, Math.min(w - 248 - 8, hover.mx - 124))}
+          top={Math.max(8, hover.my - 96)}
+          width={248}
+          base={hover.base}
+          group={hover.g.name}
+          range={
+            hover.b.mode === "week"
+              ? `${fmt.full(new Date(hover.b.start))} → ${fmt.full(new Date(hover.b.end - DAY_MS))}`
+              : fmt.full(new Date(hover.b.start))
+          }
+          count={hover.cell.count}
+          durationMs={hover.cell.durationMs}
+          items={hover.cell.items}
+          cmap={cmap}
+        />
+      )}
+    </div>
+  );
+}
+
+function HeatmapTooltip({
+  left,
+  top,
+  width,
+  base,
+  group,
+  range,
+  count,
+  durationMs,
+  items,
+  cmap,
+}: {
+  left: number;
+  top: number;
+  width: number;
+  base: string;
+  group: string;
+  range: string;
+  count: number;
+  durationMs: number;
+  items: AggregateItem[];
+  cmap: Record<string, string>;
+}) {
+  const shown = items.slice(0, 4);
+  const more = items.length - shown.length;
+  return (
+    <div style={{ position: "absolute", left, top, width, pointerEvents: "none", zIndex: 50 }}>
+      <div
+        style={{
+          background: "#fff",
+          border: "1px solid var(--tv-line)",
+          borderRadius: "var(--tv-r-md)",
+          boxShadow: "var(--tv-shadow-pop)",
+          padding: "10px 13px",
+        }}
+      >
+        <div style={{ display: "flex", alignItems: "center", gap: 7, marginBottom: 5 }}>
+          <span style={{ width: 9, height: 9, borderRadius: 2, background: base, flex: "none" }} />
+          <span
+            style={{
+              fontFamily: "var(--tv-mono)",
+              fontSize: 10,
+              letterSpacing: ".05em",
+              textTransform: "uppercase",
+              color: "var(--tv-ink-4)",
+            }}
+          >
+            {group}
+          </span>
+        </div>
+        <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-3)", lineHeight: 1.45, marginBottom: 6 }}>
+          {range}
+        </div>
+        <div style={{ display: "flex", gap: 16, marginBottom: count ? 8 : 0 }}>
+          <Metric value={count} label="items" />
+          <Metric value={tvFmtDuration(durationMs)} label="active" />
+        </div>
+        {shown.length > 0 && (
+          <div style={{ borderTop: "1px solid var(--tv-line)", paddingTop: 7, display: "flex", flexDirection: "column", gap: 4 }}>
+            {shown.map((it) => (
+              <div key={it.id + it.kind} style={{ display: "flex", alignItems: "center", gap: 7, minWidth: 0 }}>
+                <span
+                  style={{
+                    width: 7,
+                    height: 7,
+                    flex: "none",
+                    borderRadius: it.kind === "event" ? 1 : "50%",
+                    transform: it.kind === "event" ? "rotate(45deg)" : "none",
+                    background: it.kind === "event" ? "#fff" : cmap[it.labelId || ""] || base,
+                    border: it.kind === "event" ? `1.5px solid ${cmap[it.labelId || ""] || base}` : "none",
+                  }}
+                />
+                <span style={{ fontSize: 11.5, color: "var(--tv-ink-2)", whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+                  {it.title}
+                </span>
+                {it.kind === "interval" && (
+                  <span style={{ fontFamily: "var(--tv-mono)", fontSize: 10, color: "var(--tv-ink-4)", marginLeft: "auto", flex: "none" }}>
+                    {tvFmtDuration(it.overlapMs)}
+                  </span>
+                )}
+              </div>
+            ))}
+            {more > 0 && <div style={{ fontFamily: "var(--tv-mono)", fontSize: 10.5, color: "var(--tv-ink-4)" }}>+{more} more</div>}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function Metric({ value, label }: { value: string | number; label: string }) {
+  return (
+    <div>
+      <div style={{ fontSize: 17, fontWeight: 600, color: "var(--tv-ink)", lineHeight: 1 }}>{value}</div>
+      <div
+        style={{
+          fontFamily: "var(--tv-mono)",
+          fontSize: 9.5,
+          color: "var(--tv-ink-4)",
+          textTransform: "uppercase",
+          letterSpacing: ".05em",
+          marginTop: 3,
+        }}
+      >
+        {label}
+      </div>
+    </div>
+  );
+}