@jorgerdz/timeview 0.1.0

package/src/timeview/types.ts

@@ -0,0 +1,159 @@
+// types.ts — the shared Timeview data contract.
+//
+// Every Timeview visualizer renders the same `TimeDataset` (schema
+// `timeview.dataset.v1`) projected by a view-specific `ViewSpec`. Keeping the
+// dataset renderer-agnostic is what lets a future LaneCalendar / DensityHeatmap
+// / Gantt consume the exact same fixtures as BandedTimeline.
+
+/** Anything the helpers will accept as a moment in time. */
+export type TimeInput = number | string | Date;
+
+/** A categorical label. `color` is advisory — at render time the active
+ *  `palette[i]` (mapped by index) wins, so a dataset re-themes by swapping
+ *  the palette without touching the data. */
+export interface TimeLabel {
+  id: string;
+  name: string;
+  color?: string;
+}
+
+/** An instant event (milestone). Rendered as a hollow diamond. */
+export interface TimeEvent {
+  id: string;
+  at: string;
+  title: string;
+  labelIds?: string[];
+}
+
+/** A date range. Rendered as an interval band in a lane. */
+export interface TimeInterval {
+  id: string;
+  range: { start: string; end: string };
+  title: string;
+  labelIds?: string[];
+}
+
+/** A dated numeric sample for metric visualizers. */
+export interface MetricSample {
+  at: string;
+  value: number;
+}
+
+/** Optional numeric series carried by metric-oriented visualizers. */
+export interface MetricSeries {
+  id: string;
+  name: string;
+  unit?: string;
+  samples: MetricSample[];
+  target?: { value: number; label?: string };
+}
+
+/** schema `timeview.dataset.v1` */
+export interface TimeDataset {
+  schemaVersion: "timeview.dataset.v1";
+  timezone: string;
+  meta?: { title?: string; description?: string };
+  labels: TimeLabel[];
+  events: TimeEvent[];
+  intervals: TimeInterval[];
+  series?: MetricSeries;
+}
+
+export type Density = "comfortable" | "compact";
+export type LegendPosition = "top" | "bottom" | "right" | "off";
+export type CaptionPosition = "top" | "bottom" | "off";
+export type OverlapMode = "lanes" | "packed" | "layered" | "hatched";
+export type LaneMode = "packed" | "category";
+export type TodayMode = "auto";
+export type TodayValue = string | TodayMode | null;
+export type TimeBucketMode = "day" | "week";
+export type HeatmapMeasure = "count" | "duration";
+export type HeatmapGroupBy = "category" | "none";
+export type HeatmapScaleMode = "category" | "uniform";
+export type MetricStateMode = "band" | "tint" | "off";
+export type MetricYAxisMode = "auto" | "full";
+export type MetricDefaultDays = 30 | 90 | 180 | 365;
+
+/** Options shared by every Timeview visualizer. */
+export interface ViewSpecBase {
+  title?: string;
+  /** "comfortable" | "compact" */
+  density?: Density;
+  legend?: { enabled?: boolean; position?: LegendPosition };
+  caption?: { enabled?: boolean; position?: CaptionPosition; text?: string };
+  events?: { showPoints?: boolean; showLabels?: boolean; showMarkers?: boolean };
+}
+
+/** View-specific projection for BandedTimeline. */
+export interface BandedTimelineSpec extends ViewSpecBase {
+  kind?: "bandedTimeline";
+  /** how simultaneously-active intervals are resolved */
+  overlapMode?: OverlapMode;
+}
+
+/** View-specific projection for LaneCalendar. */
+export interface LaneCalendarSpec extends ViewSpecBase {
+  kind?: "laneCalendar";
+  /** how interval rows are preserved across week rows */
+  laneMode?: LaneMode;
+  /** "auto" uses browser-local today, ISO strings freeze the marker, null/omitted disables it */
+  today?: TodayValue;
+}
+
+/** View-specific projection for DensityHeatmap. */
+export interface DensityHeatmapSpec extends ViewSpecBase {
+  kind?: "densityHeatmap";
+  /** time bucket granularity */
+  bucket?: TimeBucketMode;
+  /** density value encoded by cell intensity */
+  measure?: HeatmapMeasure;
+  /** row grouping derived from existing dataset dimensions */
+  groupBy?: HeatmapGroupBy;
+  /** category-colored rows or one neutral comparable ramp */
+  scaleMode?: HeatmapScaleMode;
+  /** show count/duration text inside cells when space allows */
+  showValues?: boolean;
+}
+
+/** View-specific projection for SpanMatrix. */
+export interface SpanMatrixSpec extends ViewSpecBase {
+  kind?: "spanMatrix";
+  /** time bucket granularity */
+  bucket?: TimeBucketMode;
+  /** row grouping derived from existing dataset dimensions */
+  groupBy?: HeatmapGroupBy;
+  /** column scale multiplier; 1 is the default bucket width */
+  zoom?: number;
+  /** show overlap counts inside present cells */
+  showCounts?: boolean;
+  /** ISO string freezes the marker; null/omitted disables it */
+  today?: string | null;
+}
+
+/** View-specific projection for MetricTimeline. */
+export interface MetricTimelineSpec extends ViewSpecBase {
+  kind?: "metricTimeline";
+  /** State intervals as a separate band row, line tinting, or hidden. */
+  stateMode?: MetricStateMode;
+  /** Fit y-axis to visible window or full series. */
+  yAxis?: MetricYAxisMode;
+  /** Opening viewport span ending at today or the series end. */
+  defaultDays?: MetricDefaultDays;
+  /** ISO string freezes the default viewport end; null/omitted uses the series end. */
+  today?: string | null;
+  showPoints?: boolean;
+  showValues?: boolean;
+  showTarget?: boolean;
+  minimap?: boolean;
+}
+
+/** Back-compat alias for the first Timeview visualizer's spec. */
+export type ViewSpec = BandedTimelineSpec | LaneCalendarSpec | DensityHeatmapSpec | SpanMatrixSpec | MetricTimelineSpec;
+
+/** A linear time→pixel scale (callable, with d3-style extras). */
+export interface TvScale {
+  (t: TimeInput): number;
+  invert: (px: number) => Date;
+  domain: [number, number];
+  width: number;
+}

package/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    emptyOutDir: false,
+    outDir: "dist/studio",
+  },
+});