@jorgerdz/timeview 0.1.0

package/src/timeview/BandedTimeline.tsx

@@ -0,0 +1,620 @@
+// BandedTimeline.tsx — the first Timeview visualizer (React / HTML renderer).
+//
+// Renders a horizontal day axis, instant-event milestones, and colored
+// interval bands in stacked lanes. Pure presentational; every option arrives
+// through `spec`. The only internal state is hover + selection.
+//
+// Ported pixel-for-pixel from the design handoff's `timeview.jsx`.
+
+import { useState, useMemo, Fragment } from "react";
+import { DAY_MS, domainOf, tvScale, tvDays, tvWeeks, fmt } from "./core/time";
+import { packLanes, overlapSpans } from "./core/intervals";
+import { colorMap, labelName, mix } from "./core/labels";
+import { Caption } from "./shared/Caption";
+import { EmptyState } from "./shared/EmptyState";
+import { Legend } from "./shared/Legend";
+import { Tooltip } from "./shared/Tooltip";
+import { useMeasuredWidth } from "./shared/useMeasuredWidth";
+import type {
+  TimeDataset,
+  TimeEvent,
+  TimeInterval,
+  BandedTimelineSpec,
+  Density,
+  OverlapMode,
+} from "./types";
+
+export interface BandedTimelineProps {
+  /** schema `timeview.dataset.v1` */
+  dataset: TimeDataset;
+  /** view-specific projection (title, density, overlap mode, legend, caption…) */
+  spec: BandedTimelineSpec;
+  /** colors mapped to `dataset.labels` by index */
+  palette: string[];
+}
+
+// ── derived model shapes ────────────────────────────────────────────
+type ModelInterval = TimeInterval & { _s: number; _e: number; _lane: number };
+type ModelEvent = TimeEvent & { _t: number };
+
+interface Model {
+  t0: number;
+  t1: number;
+  intervals: ModelInterval[];
+  events: ModelEvent[];
+  laneCount: number;
+  spans: [number, number][];
+}
+
+type Hover =
+  | { kind: "interval"; id: string; iv: ModelInterval; c: string; mx: number; my: number; sticky?: boolean }
+  | { kind: "event"; id: string; ev: ModelEvent; c: string; mx: number; my: number; sticky?: boolean };
+
+function buildModel(dataset: TimeDataset, overlapMode: OverlapMode): Model {
+  const [t0, t1] = domainOf(dataset);
+  const intervals: ModelInterval[] = (dataset.intervals || []).map((iv) => ({
+    ...iv,
+    _s: new Date(iv.range.start).getTime(),
+    _e: new Date(iv.range.end).getTime(),
+    _lane: 0,
+  }));
+  let laneCount: number;
+  if (overlapMode === "lanes") {
+    intervals.sort((a, b) => a._s - b._s).forEach((iv, i) => (iv._lane = i));
+    laneCount = intervals.length;
+  } else if (overlapMode === "layered") {
+    intervals.forEach((iv) => (iv._lane = 0));
+    laneCount = 1;
+  } else {
+    laneCount = packLanes(intervals); // packed + hatched
+  }
+  const events: ModelEvent[] = (dataset.events || []).map((e) => ({ ...e, _t: new Date(e.at).getTime() }));
+  return { t0, t1, intervals, events, laneCount, spans: overlapMode === "hatched" ? overlapSpans(intervals) : [] };
+}
+
+// ── density presets ─────────────────────────────────────────────────
+interface DensitySpec {
+  laneH: number;
+  gap: number;
+  pad: number;
+  axisH: number;
+  weekH: number;
+  railH: number;
+  band: number;
+  dot: number;
+  layeredH: number;
+}
+const DENS: Record<Density, DensitySpec> = {
+  comfortable: { laneH: 44, gap: 8, pad: 24, axisH: 46, weekH: 24, railH: 30, band: 14, dot: 8, layeredH: 120 },
+  compact: { laneH: 30, gap: 5, pad: 16, axisH: 38, weekH: 20, railH: 24, band: 12.5, dot: 7, layeredH: 92 },
+};
+
+// ── the component ───────────────────────────────────────────────────
+export function BandedTimeline({ dataset, spec, palette }: BandedTimelineProps) {
+  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 overlapMode = spec.overlapMode || "lanes";
+  const showEventLabels = spec.events?.showLabels !== false;
+  const legendPos = spec.legend?.position || "bottom"; // top|bottom|right|off
+  const captionPos = spec.caption?.position || "bottom"; // top|bottom|off
+  const captionText = spec.caption?.text || "";
+  const legendOn = legendPos !== "off" && (dataset.labels || []).length > 0;
+  const captionOn = captionPos !== "off" && !!captionText;
+
+  const track = (e: { clientX: number; clientY: number }) => {
+    const r = wrapRef.current!.getBoundingClientRect();
+    return { mx: e.clientX - r.left, my: e.clientY - r.top };
+  };
+
+  const model = useMemo(() => buildModel(dataset, overlapMode), [dataset, overlapMode]);
+  const cmap = useMemo(() => colorMap(dataset, palette), [dataset, palette]);
+  const isEmpty = model.intervals.length === 0 && model.events.length === 0;
+
+  // plot width = container minus frame padding (and right legend if any)
+  const legendW = legendPos === "right" ? Math.min(230, Math.max(170, w * 0.22)) : 0;
+  const plotW = Math.max(120, w - D.pad * 2 - (legendW ? legendW + D.pad : 0));
+  const x = tvScale(model.t0, model.t1, plotW);
+  const days = tvDays(model.t0, model.t1).filter((d) => d.getTime() < model.t1);
+  const weeks = tvWeeks(model.t0, model.t1);
+  const pxPerDay = plotW / Math.max(1, days.length);
+  const dayStep = pxPerDay >= 30 ? 1 : pxPerDay >= 18 ? 2 : pxPerDay >= 11 ? 3 : 7;
+  const narrow = pxPerDay < 22;
+
+  // layered mode: stagger small label chips so they don't collide
+  const layeredLabels = useMemo(() => {
+    if (overlapMode !== "layered") return { rows: {} as Record<string, number>, count: 1 };
+    const rows: Record<string, number> = {};
+    const rowRight: number[] = [];
+    [...model.intervals]
+      .sort((a, b) => a._s - b._s)
+      .forEach((iv) => {
+        const lx = x(iv._s) + 6;
+        const estW = 26 + iv.title.length * 6.6;
+        let r = rowRight.findIndex((right) => lx >= right + 8);
+        if (r === -1) r = rowRight.length;
+        rowRight[r] = lx + estW;
+        rows[iv.id] = r;
+      });
+    return { rows, count: Math.max(1, rowRight.length) };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [overlapMode, model, plotW]);
+
+  const lanesH = isEmpty
+    ? 150
+    : overlapMode === "layered"
+      ? Math.max(96, layeredLabels.count * 26 + 26)
+      : Math.max(D.laneH, model.laneCount * D.laneH);
+  const plotH = lanesH + D.gap;
+
+  // ── sub-renders ───────────────────────────────────────────────────
+  // gridlines + day labels + week strip
+  const Axis = () => (
+    <>
+      {/* week strip */}
+      <div style={{ position: "relative", height: D.weekH, marginBottom: 4 }}>
+        {weeks.map((wk, i) => {
+          const x0 = Math.max(0, x(wk.start));
+          const x1 = Math.min(plotW, x(wk.end));
+          if (x1 - x0 < 4) return null;
+          const labelStart = wk.start.getTime() < model.t0 ? new Date(model.t0) : wk.start;
+          return (
+            <div
+              key={i}
+              style={{
+                position: "absolute",
+                left: x0,
+                width: x1 - x0,
+                top: 0,
+                bottom: 0,
+                background: i % 2 ? "var(--tv-rail-2)" : "var(--tv-rail)",
+                borderRadius: 5,
+                display: "flex",
+                alignItems: "center",
+                paddingLeft: 9,
+                overflow: "hidden",
+              }}
+            >
+              <span
+                style={{
+                  fontFamily: "var(--tv-mono)",
+                  fontSize: 10.5,
+                  fontWeight: 500,
+                  color: "var(--tv-ink-3)",
+                  letterSpacing: ".02em",
+                  whiteSpace: "nowrap",
+                }}
+              >
+                {x1 - x0 > 78 && !narrow ? `Week of ${fmt.monDay(labelStart)}` : fmt.monDay(labelStart)}
+              </span>
+            </div>
+          );
+        })}
+      </div>
+      {/* day ticks */}
+      <div style={{ position: "relative", height: D.axisH }}>
+        {days.map((d, i) => {
+          const px = x(d);
+          const isMon = (d.getUTCDay() + 6) % 7 === 0;
+          const show = i % dayStep === 0;
+          return (
+            <div key={i} style={{ position: "absolute", left: px, top: 0 }}>
+              <div style={{ width: 1, height: 7, background: isMon ? "var(--tv-grid-week)" : "var(--tv-grid)" }} />
+              {show && (
+                <div style={{ position: "absolute", left: 0, top: 9, transform: "translateX(-50%)", textAlign: "center" }}>
+                  <div
+                    style={{
+                      fontFamily: "var(--tv-mono)",
+                      fontSize: narrow ? 11 : 12.5,
+                      fontWeight: 600,
+                      color: "var(--tv-ink-2)",
+                      lineHeight: 1,
+                    }}
+                  >
+                    {fmt.day(d)}
+                  </div>
+                  {!narrow && (
+                    <div
+                      style={{
+                        fontFamily: "var(--tv-font)",
+                        fontSize: 10,
+                        color: "var(--tv-ink-4)",
+                        marginTop: 3,
+                        lineHeight: 1,
+                      }}
+                    >
+                      {fmt.dow(d)}
+                    </div>
+                  )}
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </>
+  );
+
+  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",
+      }}
+    >
+      {/* title row */}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "baseline",
+          justifyContent: "space-between",
+          gap: 12,
+          marginBottom: captionPos === "top" || legendPos === "top" ? 14 : 16,
+          flexWrap: "wrap",
+        }}
+      >
+        <div style={{ minWidth: 0 }}>
+          <div
+            style={{
+              fontSize: narrow ? 15 : 17,
+              fontWeight: 600,
+              letterSpacing: "-0.01em",
+              color: "var(--tv-ink)",
+              lineHeight: 1.25,
+            }}
+          >
+            {spec.title || dataset.meta?.title}
+          </div>
+        </div>
+        <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-4)", whiteSpace: "nowrap", flex: "none" }}>
+          {fmt.monDay(model.t0)} – {fmt.monDay(new Date(model.t1 - DAY_MS))}
+        </div>
+      </div>
+
+      {captionOn && captionPos === "top" && <Caption position={captionPos} text={captionText} narrow={narrow} />}
+      {legendOn && legendPos === "top" && <Legend labels={dataset.labels || []} colors={cmap} position={legendPos} />}
+
+      <div style={{ display: "flex", gap: D.pad, alignItems: "stretch" }}>
+        {/* PLOT */}
+        <div style={{ width: plotW, flex: "none" }}>
+          <Axis />
+
+          {/* plot body */}
+          <div
+            style={{ position: "relative", width: plotW, height: plotH, marginTop: 6 }}
+            onMouseLeave={() => setHover((h) => (h && h.sticky ? h : null))}
+          >
+            {/* day gridlines */}
+            {days.map((d, i) => {
+              const isMon = (d.getUTCDay() + 6) % 7 === 0;
+              return (
+                <div
+                  key={i}
+                  style={{
+                    position: "absolute",
+                    left: x(d),
+                    top: 0,
+                    bottom: 0,
+                    width: 1,
+                    background: isMon ? "var(--tv-grid-week)" : "var(--tv-grid)",
+                  }}
+                />
+              );
+            })}
+            <div style={{ position: "absolute", left: plotW - 0.5, top: 0, bottom: 0, width: 1, background: "var(--tv-grid-week)" }} />
+
+            {/* hatched overlap zones */}
+            {model.spans.map(([s, e], i) => (
+              <div
+                key={"sp" + i}
+                style={{
+                  position: "absolute",
+                  left: x(s),
+                  width: x(e) - x(s),
+                  top: 0,
+                  bottom: 0,
+                  background: "repeating-linear-gradient(135deg, rgba(21,24,30,0.05) 0 5px, transparent 5px 11px)",
+                  borderLeft: "1px dashed var(--tv-ink-5)",
+                  borderRight: "1px dashed var(--tv-ink-5)",
+                  pointerEvents: "none",
+                }}
+              />
+            ))}
+
+            {/* event hairlines */}
+            {model.events.map((ev) => (
+              <div
+                key={"hl" + ev.id}
+                style={{
+                  position: "absolute",
+                  left: x(ev._t),
+                  top: -2,
+                  bottom: 0,
+                  width: 1,
+                  background: "var(--tv-ink-5)",
+                  pointerEvents: "none",
+                }}
+              />
+            ))}
+
+            {/* interval bands */}
+            {model.intervals.map((iv) => {
+              const c = cmap[iv.labelIds?.[0] ?? ""] || "#64748b";
+              const left = x(iv._s);
+              const wid = Math.max(3, x(iv._e) - x(iv._s));
+              const layered = overlapMode === "layered";
+              const top = layered ? 0 : iv._lane * D.laneH;
+              const h = layered ? lanesH : D.laneH - D.gap;
+              const hovered = hover?.id === iv.id;
+              const selected = sel === iv.id;
+              const tiny = wid < 54;
+              const boxShadow =
+                [
+                  layered ? null : `inset 3px 0 0 0 ${c}`,
+                  selected ? "var(--tv-focus-ring)" : hovered ? "var(--tv-shadow-pop)" : null,
+                ]
+                  .filter(Boolean)
+                  .join(", ") || "none";
+              return (
+                <div
+                  key={iv.id}
+                  tabIndex={0}
+                  role="button"
+                  onMouseEnter={(e) => setHover({ kind: "interval", id: iv.id, iv, c, ...track(e) })}
+                  onMouseMove={(e) => setHover({ kind: "interval", id: iv.id, iv, c, ...track(e) })}
+                  onFocus={() =>
+                    setHover({ kind: "interval", id: iv.id, iv, c, mx: D.pad + Math.min(left + 90, left + wid / 2), my: 96 })
+                  }
+                  onBlur={() => setHover(null)}
+                  onClick={() => setSel((s) => (s === iv.id ? null : iv.id))}
+                  style={{
+                    position: "absolute",
+                    left,
+                    width: wid,
+                    top,
+                    height: h,
+                    background: layered ? mix(c, 30, "#ffffff") : mix(c, 13, "#ffffff"),
+                    opacity: layered ? 0.62 : 1,
+                    mixBlendMode: layered ? "multiply" : "normal",
+                    border: `1px solid ${hovered || selected ? c : mix(c, 34, "#ffffff")}`,
+                    borderRadius: "var(--tv-r-sm)",
+                    cursor: "pointer",
+                    outline: "none",
+                    boxShadow,
+                    transition:
+                      "box-shadow var(--tv-fast) var(--tv-ease), border-color var(--tv-fast) var(--tv-ease), background var(--tv-fast)",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: 7,
+                    padding: layered ? "0 8px" : "0 9px",
+                    overflow: "hidden",
+                    zIndex: hovered || selected ? 5 : 1,
+                  }}
+                >
+                  {!layered && <span style={{ width: D.dot, height: D.dot, borderRadius: "50%", background: c, flex: "none" }} />}
+                  {!layered && !tiny && (
+                    <span
+                      style={{
+                        fontSize: D.band,
+                        fontWeight: 500,
+                        color: "var(--tv-ink-2)",
+                        whiteSpace: "nowrap",
+                        overflow: "hidden",
+                        textOverflow: "ellipsis",
+                        flex: "1 1 auto",
+                        minWidth: 0,
+                      }}
+                    >
+                      {iv.title}
+                    </span>
+                  )}
+                  {!layered && !tiny && !narrow && wid > 130 && (
+                    <span
+                      style={{
+                        fontFamily: "var(--tv-mono)",
+                        fontSize: 10.5,
+                        color: "var(--tv-ink-4)",
+                        flex: "none",
+                        whiteSpace: "nowrap",
+                        letterSpacing: ".01em",
+                      }}
+                    >
+                      {fmt.span(iv._s, iv._e)}
+                    </span>
+                  )}
+                </div>
+              );
+            })}
+
+            {/* layered mode: staggered label chips (direct labels survive without color) */}
+            {overlapMode === "layered" &&
+              model.intervals.map((iv) => {
+                const c = cmap[iv.labelIds?.[0] ?? ""] || "#64748b";
+                const lx = x(iv._s);
+                const r = layeredLabels.rows[iv.id] || 0;
+                return (
+                  <div
+                    key={"ll" + iv.id}
+                    style={{
+                      position: "absolute",
+                      left: lx + 5,
+                      top: 8 + r * 26,
+                      display: "inline-flex",
+                      alignItems: "center",
+                      gap: 6,
+                      padding: "2px 8px 2px 6px",
+                      background: "rgba(255,255,255,0.92)",
+                      border: "1px solid var(--tv-line)",
+                      borderRadius: "var(--tv-r-pill)",
+                      boxShadow: "var(--tv-shadow-1)",
+                      pointerEvents: "none",
+                      maxWidth: Math.max(60, plotW - lx - 8),
+                    }}
+                  >
+                    <span style={{ width: 7, height: 7, borderRadius: "50%", background: c, flex: "none" }} />
+                    <span
+                      style={{
+                        fontSize: 11.5,
+                        fontWeight: 500,
+                        color: "var(--tv-ink-2)",
+                        whiteSpace: "nowrap",
+                        overflow: "hidden",
+                        textOverflow: "ellipsis",
+                      }}
+                    >
+                      {iv.title}
+                    </span>
+                  </div>
+                );
+              })}
+
+            {/* empty state - centered in the plot body */}
+            {isEmpty && (
+              <EmptyState
+                title="No events or intervals in this window"
+                description="Add intervals or milestones to see them on the timeline."
+                icon="calendar"
+                narrow={narrow}
+              />
+            )}
+          </div>
+
+          {model.events.length > 0 && (
+            <div
+              style={{
+                position: "relative",
+                width: plotW,
+                height: showEventLabels ? D.railH + 14 : D.railH,
+                marginTop: 8,
+                borderTop: "1px solid var(--tv-line)",
+                paddingTop: 10,
+              }}
+            >
+              {model.events.map((ev) => {
+                const c = cmap[ev.labelIds?.[0] ?? ""] || "var(--tv-ink-2)";
+                const px = x(ev._t);
+                const hovered = hover?.id === ev.id;
+                const lx = Math.max(46, Math.min(plotW - 46, px));
+                const on = (e: { clientX: number; clientY: number } | null, extra?: { mx: number; my: number }) =>
+                  setHover({ kind: "event", id: ev.id, ev, c, ...(extra || track(e!)) });
+                return (
+                  <Fragment key={ev.id}>
+                    <div
+                      tabIndex={0}
+                      onMouseEnter={(e) => on(e)}
+                      onMouseMove={(e) => on(e)}
+                      onFocus={() => on(null, { mx: D.pad + px, my: plotH + 120 })}
+                      onBlur={() => setHover(null)}
+                      style={{
+                        position: "absolute",
+                        left: px,
+                        top: 0,
+                        transform: "translateX(-50%)",
+                        cursor: "pointer",
+                        outline: "none",
+                        padding: 3,
+                      }}
+                    >
+                      <span
+                        style={{
+                          display: "block",
+                          width: 11,
+                          height: 11,
+                          transform: "rotate(45deg)",
+                          background: "#fff",
+                          border: `2px solid ${c}`,
+                          borderRadius: 2,
+                          boxShadow: hovered ? `0 0 0 4px ${mix(c, 18, "#ffffff")}` : "none",
+                          transition: "box-shadow var(--tv-fast)",
+                        }}
+                      />
+                    </div>
+                    {showEventLabels && (
+                      <span
+                        style={{
+                          position: "absolute",
+                          left: lx,
+                          top: 22,
+                          transform: "translateX(-50%)",
+                          fontSize: 11,
+                          fontWeight: 500,
+                          color: hovered ? "var(--tv-ink)" : "var(--tv-ink-2)",
+                          whiteSpace: "nowrap",
+                          textAlign: "center",
+                          pointerEvents: "none",
+                        }}
+                      >
+                        {ev.title}
+                      </span>
+                    )}
+                  </Fragment>
+                );
+              })}
+            </div>
+          )}
+        </div>
+
+        {/* right legend */}
+        {legendOn && legendPos === "right" && (
+          <div style={{ width: legendW, flex: "none", paddingTop: D.weekH + 6 }}>
+            <div
+              style={{
+                fontFamily: "var(--tv-mono)",
+                fontSize: 10,
+                letterSpacing: ".08em",
+                textTransform: "uppercase",
+                color: "var(--tv-ink-4)",
+                marginBottom: 12,
+              }}
+            >
+              Legend
+            </div>
+            <Legend labels={dataset.labels || []} colors={cmap} position={legendPos} vertical />
+          </div>
+        )}
+      </div>
+
+      {legendOn && legendPos === "bottom" && <Legend labels={dataset.labels || []} colors={cmap} position={legendPos} />}
+      {captionOn && captionPos === "bottom" && <Caption position={captionPos} text={captionText} narrow={narrow} />}
+
+      {/* tooltip — follows cursor, clamped to component */}
+      {hover &&
+        (() => {
+          const isEvent = hover.kind === "event";
+          const src = isEvent ? hover.ev : hover.iv;
+          const line = isEvent ? fmt.full(hover.ev._t) : `${fmt.full(hover.iv._s)} → ${fmt.full(new Date(hover.iv._e))}`;
+          const sub = isEvent ? fmt.time(hover.ev._t) || "All-day milestone" : fmt.span(hover.iv._s, hover.iv._e);
+          const TW = 234;
+          const left = Math.max(8, Math.min(w - TW - 8, hover.mx - TW / 2));
+          const top = Math.max(8, hover.my - 96);
+          return (
+            <Tooltip
+              left={left}
+              top={top}
+              width={TW}
+              color={hover.c}
+              label={labelName(dataset, src.labelIds?.[0])}
+              title={src.title}
+              line={line}
+              sub={sub}
+              kindLabel={isEvent ? "Milestone" : "Interval"}
+              isEvent={isEvent}
+            />
+          );
+        })()}
+    </div>
+  );
+}