@jorgerdz/timeview 0.1.0

package/src/timeview/export.ts

@@ -0,0 +1,48 @@
+import type { TimeviewConfigV1 } from "./config";
+import type { ViewSpec } from "./types";
+
+export type ExportFormat = "html" | "png";
+export type ExportPresetId = "1200x720" | "1600x900";
+
+export const EXPORT_PRESETS: Record<ExportPresetId, { width: number; height: number; label: string }> = {
+  "1200x720": { width: 1200, height: 720, label: "1200x720" },
+  "1600x900": { width: 1600, height: 900, label: "1600x900" },
+};
+
+export function isExportPresetId(value: string): value is ExportPresetId {
+  return value in EXPORT_PRESETS;
+}
+
+export function slug(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+export function exportFileName(config: TimeviewConfigV1, extension: ExportFormat): string {
+  const title = slug(config.dataset.meta?.title || "timeview");
+  const visualizer = slug(config.visualizer);
+  return `timeview-${visualizer}-${title || "view"}.${extension}`;
+}
+
+export function localIsoDate(now = new Date()): string {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function freezeConfigForExport(config: TimeviewConfigV1, today = localIsoDate()): TimeviewConfigV1 {
+  if (!("today" in config.spec) || config.spec.today !== "auto") return config;
+
+  return {
+    ...config,
+    spec: {
+      ...config.spec,
+      today,
+    } as ViewSpec,
+  };
+}

package/src/timeview/index.ts

@@ -0,0 +1,106 @@
+// Timeview — public surface.
+//
+// A library of reusable, time-based visualization components. Every visualizer
+// renders a shared `TimeDataset` projected by a view-specific `ViewSpec`.
+
+export { BandedTimeline } from "./BandedTimeline";
+export type { BandedTimelineProps } from "./BandedTimeline";
+export { LaneCalendar } from "./LaneCalendar";
+export type { LaneCalendarProps } from "./LaneCalendar";
+export { DensityHeatmap } from "./DensityHeatmap";
+export type { DensityHeatmapProps } from "./DensityHeatmap";
+export { SpanMatrix } from "./SpanMatrix";
+export type { SpanMatrixProps } from "./SpanMatrix";
+export { MetricTimeline } from "./MetricTimeline";
+export type { MetricTimelineProps } from "./MetricTimeline";
+export { TV_VISUALIZERS, TV_VISUALIZER_BY_ID } from "./registry";
+export type { TimeviewVisualizer, VisualizerId } from "./registry";
+export {
+  cloneTimeviewConfig,
+  decodeTimeviewConfig,
+  encodeTimeviewConfig,
+  normalizePalette,
+  normalizeTimeviewConfig,
+  normalizeViewSpec,
+  validateTimeDataset,
+  validateViewSpec,
+} from "./config";
+export type { TimeviewConfigV1, ValidationResult } from "./config";
+export { normalizeTimeviewDashboard } from "./dashboard";
+export type { TimeviewDashboardPanelV1, TimeviewDashboardV1 } from "./dashboard";
+export { EXPORT_PRESETS, exportFileName, freezeConfigForExport, isExportPresetId, localIsoDate, slug } from "./export";
+export type { ExportFormat, ExportPresetId } from "./export";
+export { tvBuckets, tvAggregate, tvFmtDuration, tvSpanMatrix } from "./core/aggregate";
+export type {
+  TimeBucket,
+  AggregateGroup,
+  AggregateItem,
+  AggregateCell,
+  AggregateOptions,
+  AggregateMatrix,
+  SpanMatrixCell,
+  SpanMatrixEventItem,
+  SpanMatrixIntervalItem,
+  SpanMatrixModel,
+  SpanMatrixOptions,
+  SpanMatrixRow,
+  SpanMatrixRun,
+} from "./core/aggregate";
+export {
+  METRIC_MIN_SPAN,
+  tvClampViewport,
+  tvDefaultViewport,
+  tvLineSegments,
+  tvMetricModel,
+  tvMetricTimeTicks,
+  tvNearest,
+  tvNiceTicks,
+  tvStateAt,
+} from "./core/metric";
+export type { MetricEvent, MetricLineSegment, MetricModel, MetricPoint, MetricState, MetricTarget, MetricTimeTick, NiceTicks } from "./core/metric";
+export { tvGridWeeks, tvDayCell, tvSplitInterval, tvSameUTCDay, startOfDayUTC } from "./core/calendar";
+export type { CalendarWeek, CalendarCell, CalendarIntervalSegment } from "./core/calendar";
+
+export {
+  TV_DATA,
+  TV_PALETTES,
+  DAY_MS,
+  domainOf,
+  tvScale,
+  tvDays,
+  tvWeeks,
+  fmt,
+} from "./data";
+export type { FixtureKey } from "./data";
+
+export type {
+  TimeInput,
+  TimeLabel,
+  TimeEvent,
+  TimeInterval,
+  MetricSample,
+  MetricSeries,
+  TimeDataset,
+  ViewSpecBase,
+  BandedTimelineSpec,
+  LaneCalendarSpec,
+  DensityHeatmapSpec,
+  SpanMatrixSpec,
+  MetricTimelineSpec,
+  ViewSpec,
+  TvScale,
+  OverlapMode,
+  LaneMode,
+  TodayMode,
+  TodayValue,
+  TimeBucketMode,
+  HeatmapMeasure,
+  HeatmapGroupBy,
+  HeatmapScaleMode,
+  MetricStateMode,
+  MetricYAxisMode,
+  MetricDefaultDays,
+  Density,
+  LegendPosition,
+  CaptionPosition,
+} from "./types";

package/src/timeview/registry.ts

@@ -0,0 +1,207 @@
+// registry.ts — demo/library registry for Timeview visualizers.
+
+import type { ComponentType } from "react";
+import { BandedTimeline } from "./BandedTimeline";
+import type { BandedTimelineProps } from "./BandedTimeline";
+import { LaneCalendar } from "./LaneCalendar";
+import type { LaneCalendarProps } from "./LaneCalendar";
+import { DensityHeatmap } from "./DensityHeatmap";
+import type { DensityHeatmapProps } from "./DensityHeatmap";
+import { SpanMatrix } from "./SpanMatrix";
+import type { SpanMatrixProps } from "./SpanMatrix";
+import { MetricTimeline } from "./MetricTimeline";
+import type { MetricTimelineProps } from "./MetricTimeline";
+import { TV_DATA, TV_PALETTES } from "./data";
+import type { BandedTimelineSpec, DensityHeatmapSpec, LaneCalendarSpec, MetricTimelineSpec, SpanMatrixSpec, TimeDataset } from "./types";
+
+export type VisualizerId = "bandedTimeline" | "laneCalendar" | "densityHeatmap" | "spanMatrix" | "metricTimeline";
+type VisualizerSpec = BandedTimelineSpec | LaneCalendarSpec | DensityHeatmapSpec | SpanMatrixSpec | MetricTimelineSpec;
+export type VisualizerProps = BandedTimelineProps | LaneCalendarProps | DensityHeatmapProps | SpanMatrixProps | MetricTimelineProps;
+
+export interface TimeviewVisualizer {
+  id: VisualizerId;
+  kind: NonNullable<VisualizerSpec["kind"]>;
+  label: string;
+  description: string;
+  Component: ComponentType<any>;
+  defaultDataset: TimeDataset;
+  defaultSpec: VisualizerSpec;
+  defaultPalette: string[];
+  controls: {
+    legend: boolean;
+    events: boolean;
+    caption: boolean;
+    today: boolean;
+    options: string[];
+  };
+  agentGuide: string;
+}
+
+export const TV_VISUALIZERS = [
+  {
+    id: "bandedTimeline",
+    kind: "bandedTimeline",
+    label: "BandedTimeline",
+    description: "Horizontal day axis with interval bands and milestone diamonds.",
+    Component: BandedTimeline,
+    defaultDataset: TV_DATA.default,
+    defaultSpec: {
+      kind: "bandedTimeline",
+      title: TV_DATA.default.meta?.title,
+      overlapMode: "lanes",
+      density: "comfortable",
+      legend: { enabled: true, position: "bottom" },
+      caption: { enabled: true, position: "bottom", text: "Intervals may overlap. Diamond markers show milestone dates." },
+      events: { showPoints: true, showLabels: true },
+    },
+    defaultPalette: TV_PALETTES.Studio,
+    controls: {
+      legend: true,
+      events: true,
+      caption: true,
+      today: false,
+      options: ["overlapMode", "density", "legend", "caption", "eventLabels", "palette"],
+    },
+    agentGuide: "Use for plans, launches, trips, and schedules where interval overlap and milestone order matter on a horizontal timeline.",
+  },
+  {
+    id: "laneCalendar",
+    kind: "laneCalendar",
+    label: "LaneCalendar",
+    description: "Week rows and day columns with interval chips and milestone diamonds.",
+    Component: LaneCalendar,
+    defaultDataset: TV_DATA.default,
+    defaultSpec: {
+      kind: "laneCalendar",
+      title: TV_DATA.default.meta?.title,
+      laneMode: "packed",
+      density: "comfortable",
+      legend: { enabled: true, position: "bottom" },
+      caption: {
+        enabled: true,
+        position: "bottom",
+        text: "Chips span the days an interval covers and split at week boundaries; diamonds mark milestone dates.",
+      },
+      events: { showLabels: true },
+      today: null,
+    },
+    defaultPalette: TV_PALETTES.Studio,
+    controls: {
+      legend: true,
+      events: true,
+      caption: true,
+      today: true,
+      options: ["laneMode", "density", "legend", "caption", "milestoneLabels", "today", "palette"],
+    },
+    agentGuide: "Use for calendar-first views where week rows, day cells, and current-day context are more useful than a continuous axis.",
+  },
+  {
+    id: "densityHeatmap",
+    kind: "densityHeatmap",
+    label: "DensityHeatmap",
+    description: "Aggregated category-by-time matrix for counts and active duration.",
+    Component: DensityHeatmap,
+    defaultDataset: TV_DATA.default,
+    defaultSpec: {
+      kind: "densityHeatmap",
+      title: TV_DATA.default.meta?.title,
+      bucket: "day",
+      measure: "count",
+      groupBy: "category",
+      scaleMode: "category",
+      density: "comfortable",
+      showValues: true,
+      caption: {
+        enabled: true,
+        position: "bottom",
+        text: "Cell intensity encodes density. Intervals add active duration to every bucket they touch; milestones add a count to their bucket.",
+      },
+    },
+    defaultPalette: TV_PALETTES.Studio,
+    controls: {
+      legend: false,
+      events: false,
+      caption: true,
+      today: false,
+      options: ["bucket", "measure", "groupBy", "scaleMode", "density", "showValues", "caption", "palette"],
+    },
+    agentGuide: "Use for high-volume data when the goal is spotting density patterns by day/week and category rather than reading every item.",
+  },
+  {
+    id: "metricTimeline",
+    kind: "metricTimeline",
+    label: "MetricTimeline",
+    description: "Numeric trend line with diet/state bands and a navigable viewport.",
+    Component: MetricTimeline,
+    defaultDataset: TV_DATA.metric,
+    defaultSpec: {
+      kind: "metricTimeline",
+      title: TV_DATA.metric.meta?.title,
+      stateMode: "band",
+      yAxis: "auto",
+      defaultDays: 90,
+      today: "2026-06-09",
+      density: "comfortable",
+      showPoints: true,
+      showValues: false,
+      showTarget: true,
+      minimap: true,
+      legend: { enabled: true, position: "bottom" },
+      caption: {
+        enabled: true,
+        position: "bottom",
+        text: "The line shows logged values. State bands mark diet, maintenance, and off-plan periods; the minimap freezes the active viewport for export.",
+      },
+      events: { showMarkers: true },
+    },
+    defaultPalette: TV_PALETTES.Studio,
+    controls: {
+      legend: true,
+      events: true,
+      caption: true,
+      today: true,
+      options: ["stateMode", "yAxis", "defaultDays", "points", "values", "target", "minimap", "milestoneMarkers", "legend", "caption", "palette"],
+    },
+    agentGuide:
+      "Use for logged numeric measurements over time, such as weight, spend, latency, or mood, especially when contextual periods like diet versus non-diet should explain the trend.",
+  },
+  {
+    id: "spanMatrix",
+    kind: "spanMatrix",
+    label: "SpanMatrix",
+    description: "Presence and continuity matrix by category and day/week bucket.",
+    Component: SpanMatrix,
+    defaultDataset: TV_DATA.stacked,
+    defaultSpec: {
+      kind: "spanMatrix",
+      title: TV_DATA.stacked.meta?.title,
+      bucket: "day",
+      groupBy: "category",
+      zoom: 1,
+      density: "comfortable",
+      showCounts: true,
+      legend: { enabled: true, position: "bottom" },
+      caption: {
+        enabled: true,
+        position: "bottom",
+        text: "Each cell marks whether a category had an interval active that day; touching cells join into one run, and hatched cells carry two or more overlapping spans.",
+      },
+      events: { showMarkers: true },
+      today: "2026-01-14",
+    },
+    defaultPalette: TV_PALETTES.Studio,
+    controls: {
+      legend: true,
+      events: true,
+      caption: true,
+      today: true,
+      options: ["bucket", "groupBy", "density", "showCounts", "milestoneMarkers", "today", "legend", "caption", "palette"],
+    },
+    agentGuide: "Use for coverage views where the goal is seeing category presence, continuity, gaps, overlaps, and milestones across day/week buckets.",
+  },
+] satisfies TimeviewVisualizer[];
+
+export const TV_VISUALIZER_BY_ID = Object.fromEntries(TV_VISUALIZERS.map((entry) => [entry.id, entry])) as Record<
+  VisualizerId,
+  TimeviewVisualizer
+>;

package/src/timeview/shared/Caption.tsx

@@ -0,0 +1,40 @@
+// Caption.tsx — shared note-style caption for Timeview components.
+
+import type { CaptionPosition } from "../types";
+
+interface CaptionProps {
+  position: CaptionPosition;
+  text: string;
+  narrow: boolean;
+}
+
+export function Caption({ position, text, narrow }: CaptionProps) {
+  return (
+    <div
+      style={{
+        fontFamily: "var(--tv-font)",
+        fontSize: narrow ? 12 : 13,
+        lineHeight: 1.5,
+        color: "var(--tv-ink-3)",
+        padding: position === "top" ? "0 0 14px" : "14px 0 0",
+        borderTop: position === "bottom" ? "1px solid var(--tv-line)" : "none",
+        marginTop: position === "bottom" ? 4 : 0,
+        maxWidth: 760,
+      }}
+    >
+      <span
+        style={{
+          fontFamily: "var(--tv-mono)",
+          fontSize: 10.5,
+          letterSpacing: ".06em",
+          textTransform: "uppercase",
+          color: "var(--tv-ink-4)",
+          marginRight: 8,
+        }}
+      >
+        Note
+      </span>
+      {text}
+    </div>
+  );
+}

package/src/timeview/shared/EmptyState.tsx

@@ -0,0 +1,90 @@
+// EmptyState.tsx - shared static-safe empty-state block for Timeview visualizers.
+
+import type { CSSProperties } from "react";
+
+type EmptyStateIcon = "calendar" | "grid" | "matrix" | "trend";
+type EmptyStateVariant = "overlay" | "panel";
+
+interface EmptyStateProps {
+  title: string;
+  description?: string;
+  icon?: EmptyStateIcon;
+  variant?: EmptyStateVariant;
+  background?: boolean;
+  bordered?: boolean;
+  height?: CSSProperties["height"];
+  narrow?: boolean;
+}
+
+export function EmptyState({
+  title,
+  description,
+  icon = "calendar",
+  variant = "overlay",
+  background = false,
+  bordered = false,
+  height = 200,
+  narrow = false,
+}: EmptyStateProps) {
+  const isPanel = variant === "panel";
+  return (
+    <div
+      style={{
+        position: isPanel ? "relative" : "absolute",
+        inset: isPanel ? undefined : 0,
+        height: isPanel ? height : undefined,
+        border: bordered ? "1px solid var(--tv-grid)" : "none",
+        borderRadius: bordered ? "var(--tv-r-md)" : undefined,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: description ? 7 : 6,
+        padding: narrow ? 16 : 20,
+        pointerEvents: "none",
+        textAlign: "center",
+        background: background ? "rgba(255,255,255,0.55)" : undefined,
+      }}
+    >
+      <EmptyIcon icon={icon} size={icon === "grid" || icon === "matrix" ? 28 : 30} />
+      <div style={{ fontSize: narrow ? 13.5 : 14, fontWeight: 600, color: "var(--tv-ink-3)", lineHeight: 1.25 }}>
+        {title}
+      </div>
+      {description && (
+        <div style={{ fontSize: 12.5, color: "var(--tv-ink-4)", lineHeight: 1.35, maxWidth: 320 }}>
+          {description}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function EmptyIcon({ icon, size }: { icon: EmptyStateIcon; size: number }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="var(--tv-ink-5)" strokeWidth="1.5" aria-hidden="true">
+      {icon === "trend" ? (
+        <>
+          <path d="M3 17l5-6 4 3 5-7" />
+          <path d="M3 21h18" />
+        </>
+      ) : icon === "grid" ? (
+        <>
+          <rect x="3" y="3" width="7" height="7" rx="1.5" />
+          <rect x="14" y="3" width="7" height="7" rx="1.5" />
+          <rect x="3" y="14" width="7" height="7" rx="1.5" />
+          <rect x="14" y="14" width="7" height="7" rx="1.5" />
+        </>
+      ) : icon === "matrix" ? (
+        <>
+          <rect x="3" y="5" width="18" height="14" rx="2" />
+          <path d="M3 10h18M8 14h5" />
+        </>
+      ) : (
+        <>
+          <rect x="3" y="5" width="18" height="14" rx="2" />
+          <path d="M3 10h18M8 3v4M16 3v4" />
+        </>
+      )}
+    </svg>
+  );
+}

package/src/timeview/shared/Legend.tsx

@@ -0,0 +1,67 @@
+// Legend.tsx — shared categorical legend for Timeview components.
+
+import type { LegendPosition, TimeLabel } from "../types";
+
+interface LegendProps {
+  labels: TimeLabel[];
+  colors: Record<string, string>;
+  position: LegendPosition;
+  vertical?: boolean;
+}
+
+export function Legend({ labels, colors, position, vertical = false }: LegendProps) {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: vertical ? "column" : "row",
+        flexWrap: "wrap",
+        gap: vertical ? 8 : "8px 16px",
+        alignItems: vertical ? "stretch" : "center",
+        padding: vertical ? 0 : position === "top" ? "0 0 14px" : "14px 0 2px",
+      }}
+    >
+      {labels.map((l) => {
+        const c = colors[l.id];
+        return (
+          <div
+            key={l.id}
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              gap: 8,
+              minWidth: 0,
+              flex: "none",
+              maxWidth: vertical ? "100%" : 240,
+            }}
+          >
+            <span
+              style={{
+                width: 11,
+                height: 11,
+                borderRadius: 3,
+                background: c,
+                boxShadow: "inset 0 0 0 1px rgba(0,0,0,0.14)",
+                flex: "none",
+              }}
+            />
+            <span
+              style={{
+                fontFamily: "var(--tv-font)",
+                fontSize: 12.5,
+                color: "var(--tv-ink-2)",
+                fontWeight: 500,
+                lineHeight: 1.3,
+                whiteSpace: vertical ? "normal" : "nowrap",
+                overflow: vertical ? "visible" : "hidden",
+                textOverflow: vertical ? "clip" : "ellipsis",
+              }}
+            >
+              {l.name}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/timeview/shared/Tooltip.tsx

@@ -0,0 +1,59 @@
+// Tooltip.tsx — shared tooltip shell for Timeview components.
+
+import type { CSSProperties } from "react";
+
+interface TooltipProps {
+  left: number;
+  top: number;
+  width: number;
+  color: string;
+  label: string;
+  title: string;
+  line: string;
+  sub: string;
+  kindLabel: string;
+  isEvent: boolean;
+}
+
+export function Tooltip({ left, top, width, color, label, title, line, sub, kindLabel, isEvent }: TooltipProps) {
+  const dotStyle: CSSProperties = {
+    width: 9,
+    height: 9,
+    borderRadius: isEvent ? 1 : "50%",
+    background: isEvent ? "#fff" : color,
+    border: isEvent ? `2px solid ${color}` : "none",
+    transform: isEvent ? "rotate(45deg)" : "none",
+    flex: "none",
+  };
+  return (
+    <div data-tv-transient="tooltip" 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={dotStyle} />
+          <span
+            style={{
+              fontFamily: "var(--tv-mono)",
+              fontSize: 10,
+              letterSpacing: ".05em",
+              textTransform: "uppercase",
+              color: "var(--tv-ink-4)",
+            }}
+          >
+            {kindLabel} · {label}
+          </span>
+        </div>
+        <div style={{ fontSize: 14, fontWeight: 600, color: "var(--tv-ink)", marginBottom: 4, lineHeight: 1.3 }}>{title}</div>
+        <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-3)", lineHeight: 1.45 }}>{line}</div>
+        <div style={{ fontFamily: "var(--tv-mono)", fontSize: 11, color: "var(--tv-ink-4)", marginTop: 2 }}>{sub}</div>
+      </div>
+    </div>
+  );
+}

package/src/timeview/shared/useMeasuredWidth.ts

@@ -0,0 +1,21 @@
+// useMeasuredWidth.ts — ResizeObserver width measurement for responsive visualizers.
+
+import { useLayoutEffect, useRef, useState } from "react";
+
+export function useMeasuredWidth<T extends HTMLElement>(defaultWidth = 1200) {
+  const ref = useRef<T>(null);
+  const [width, setWidth] = useState(defaultWidth);
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ro = new ResizeObserver((ents) => {
+      for (const e of ents) setWidth(e.contentRect.width);
+    });
+    ro.observe(el);
+    setWidth(el.getBoundingClientRect().width);
+    return () => ro.disconnect();
+  }, []);
+
+  return [ref, width] as const;
+}