@jorgerdz/timeview 0.1.0

package/dist/types/timeview/registry.d.ts

@@ -0,0 +1,285 @@
+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 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 declare const TV_VISUALIZERS: ({
+    id: "bandedTimeline";
+    kind: "bandedTimeline";
+    label: string;
+    description: string;
+    Component: typeof BandedTimeline;
+    defaultDataset: TimeDataset;
+    defaultSpec: {
+        kind: "bandedTimeline";
+        title: string | undefined;
+        overlapMode: "lanes";
+        density: "comfortable";
+        legend: {
+            enabled: true;
+            position: "bottom";
+        };
+        caption: {
+            enabled: true;
+            position: "bottom";
+            text: string;
+        };
+        events: {
+            showPoints: true;
+            showLabels: true;
+            showMarkers?: undefined;
+        };
+        laneMode?: undefined;
+        today?: undefined;
+        bucket?: undefined;
+        measure?: undefined;
+        groupBy?: undefined;
+        scaleMode?: undefined;
+        showValues?: undefined;
+        stateMode?: undefined;
+        yAxis?: undefined;
+        defaultDays?: undefined;
+        showPoints?: undefined;
+        showTarget?: undefined;
+        minimap?: undefined;
+        zoom?: undefined;
+        showCounts?: undefined;
+    };
+    defaultPalette: string[];
+    controls: {
+        legend: true;
+        events: true;
+        caption: true;
+        today: false;
+        options: string[];
+    };
+    agentGuide: string;
+} | {
+    id: "laneCalendar";
+    kind: "laneCalendar";
+    label: string;
+    description: string;
+    Component: typeof LaneCalendar;
+    defaultDataset: TimeDataset;
+    defaultSpec: {
+        kind: "laneCalendar";
+        title: string | undefined;
+        laneMode: "packed";
+        density: "comfortable";
+        legend: {
+            enabled: true;
+            position: "bottom";
+        };
+        caption: {
+            enabled: true;
+            position: "bottom";
+            text: string;
+        };
+        events: {
+            showLabels: true;
+            showPoints?: undefined;
+            showMarkers?: undefined;
+        };
+        today: null;
+        overlapMode?: undefined;
+        bucket?: undefined;
+        measure?: undefined;
+        groupBy?: undefined;
+        scaleMode?: undefined;
+        showValues?: undefined;
+        stateMode?: undefined;
+        yAxis?: undefined;
+        defaultDays?: undefined;
+        showPoints?: undefined;
+        showTarget?: undefined;
+        minimap?: undefined;
+        zoom?: undefined;
+        showCounts?: undefined;
+    };
+    defaultPalette: string[];
+    controls: {
+        legend: true;
+        events: true;
+        caption: true;
+        today: true;
+        options: string[];
+    };
+    agentGuide: string;
+} | {
+    id: "densityHeatmap";
+    kind: "densityHeatmap";
+    label: string;
+    description: string;
+    Component: typeof DensityHeatmap;
+    defaultDataset: TimeDataset;
+    defaultSpec: {
+        kind: "densityHeatmap";
+        title: string | undefined;
+        bucket: "day";
+        measure: "count";
+        groupBy: "category";
+        scaleMode: "category";
+        density: "comfortable";
+        showValues: true;
+        caption: {
+            enabled: true;
+            position: "bottom";
+            text: string;
+        };
+        overlapMode?: undefined;
+        legend?: undefined;
+        events?: undefined;
+        laneMode?: undefined;
+        today?: undefined;
+        stateMode?: undefined;
+        yAxis?: undefined;
+        defaultDays?: undefined;
+        showPoints?: undefined;
+        showTarget?: undefined;
+        minimap?: undefined;
+        zoom?: undefined;
+        showCounts?: undefined;
+    };
+    defaultPalette: string[];
+    controls: {
+        legend: false;
+        events: false;
+        caption: true;
+        today: false;
+        options: string[];
+    };
+    agentGuide: string;
+} | {
+    id: "metricTimeline";
+    kind: "metricTimeline";
+    label: string;
+    description: string;
+    Component: typeof MetricTimeline;
+    defaultDataset: TimeDataset;
+    defaultSpec: {
+        kind: "metricTimeline";
+        title: string | undefined;
+        stateMode: "band";
+        yAxis: "auto";
+        defaultDays: 90;
+        today: string;
+        density: "comfortable";
+        showPoints: true;
+        showValues: false;
+        showTarget: true;
+        minimap: true;
+        legend: {
+            enabled: true;
+            position: "bottom";
+        };
+        caption: {
+            enabled: true;
+            position: "bottom";
+            text: string;
+        };
+        events: {
+            showMarkers: true;
+            showPoints?: undefined;
+            showLabels?: undefined;
+        };
+        overlapMode?: undefined;
+        laneMode?: undefined;
+        bucket?: undefined;
+        measure?: undefined;
+        groupBy?: undefined;
+        scaleMode?: undefined;
+        zoom?: undefined;
+        showCounts?: undefined;
+    };
+    defaultPalette: string[];
+    controls: {
+        legend: true;
+        events: true;
+        caption: true;
+        today: true;
+        options: string[];
+    };
+    agentGuide: string;
+} | {
+    id: "spanMatrix";
+    kind: "spanMatrix";
+    label: string;
+    description: string;
+    Component: typeof SpanMatrix;
+    defaultDataset: TimeDataset;
+    defaultSpec: {
+        kind: "spanMatrix";
+        title: string | undefined;
+        bucket: "day";
+        groupBy: "category";
+        zoom: number;
+        density: "comfortable";
+        showCounts: true;
+        legend: {
+            enabled: true;
+            position: "bottom";
+        };
+        caption: {
+            enabled: true;
+            position: "bottom";
+            text: string;
+        };
+        events: {
+            showMarkers: true;
+            showPoints?: undefined;
+            showLabels?: undefined;
+        };
+        today: string;
+        overlapMode?: undefined;
+        laneMode?: undefined;
+        measure?: undefined;
+        scaleMode?: undefined;
+        showValues?: undefined;
+        stateMode?: undefined;
+        yAxis?: undefined;
+        defaultDays?: undefined;
+        showPoints?: undefined;
+        showTarget?: undefined;
+        minimap?: undefined;
+    };
+    defaultPalette: string[];
+    controls: {
+        legend: true;
+        events: true;
+        caption: true;
+        today: true;
+        options: string[];
+    };
+    agentGuide: string;
+})[];
+export declare const TV_VISUALIZER_BY_ID: Record<VisualizerId, TimeviewVisualizer>;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/timeview/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/timeview/registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzI,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAClH,KAAK,cAAc,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,cAAc,GAAG,kBAAkB,CAAC;AACvH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAEpI,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,YAAY,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAC9B,cAAc,EAAE,WAAW,CAAC;IAC5B,WAAW,EAAE,cAAc,CAAC;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE;QACR,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,OAAO,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,EAAE,OAAO,CAAC;QACf,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkKK,CAAC;AAEjC,eAAO,MAAM,mBAAmB,EAA2E,MAAM,CAC/G,YAAY,EACZ,kBAAkB,CACnB,CAAC"}

package/dist/types/timeview/shared/Caption.d.ts

@@ -0,0 +1,9 @@
+import type { CaptionPosition } from "../types";
+interface CaptionProps {
+    position: CaptionPosition;
+    text: string;
+    narrow: boolean;
+}
+export declare function Caption({ position, text, narrow }: CaptionProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Caption.d.ts.map

package/dist/types/timeview/shared/Caption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Caption.d.ts","sourceRoot":"","sources":["../../../../src/timeview/shared/Caption.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,UAAU,YAAY;IACpB,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,YAAY,+BA6B/D"}

package/dist/types/timeview/shared/EmptyState.d.ts

@@ -0,0 +1,16 @@
+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 declare function EmptyState({ title, description, icon, variant, background, bordered, height, narrow, }: EmptyStateProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=EmptyState.d.ts.map

package/dist/types/timeview/shared/EmptyState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../../../../src/timeview/shared/EmptyState.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,KAAK,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC/D,KAAK,iBAAiB,GAAG,SAAS,GAAG,OAAO,CAAC;AAE7C,UAAU,eAAe;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,IAAiB,EACjB,OAAmB,EACnB,UAAkB,EAClB,QAAgB,EAChB,MAAY,EACZ,MAAc,GACf,EAAE,eAAe,+BAgCjB"}

package/dist/types/timeview/shared/Legend.d.ts

@@ -0,0 +1,10 @@
+import type { LegendPosition, TimeLabel } from "../types";
+interface LegendProps {
+    labels: TimeLabel[];
+    colors: Record<string, string>;
+    position: LegendPosition;
+    vertical?: boolean;
+}
+export declare function Legend({ labels, colors, position, vertical }: LegendProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Legend.d.ts.map

package/dist/types/timeview/shared/Legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Legend.d.ts","sourceRoot":"","sources":["../../../../src/timeview/shared/Legend.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1D,UAAU,WAAW;IACnB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAgB,EAAE,EAAE,WAAW,+BAuDjF"}

package/dist/types/timeview/shared/Tooltip.d.ts

@@ -0,0 +1,15 @@
+interface TooltipProps {
+    left: number;
+    top: number;
+    width: number;
+    color: string;
+    label: string;
+    title: string;
+    line: string;
+    sub: string;
+    kindLabel: string;
+    isEvent: boolean;
+}
+export declare function Tooltip({ left, top, width, color, label, title, line, sub, kindLabel, isEvent }: TooltipProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=Tooltip.d.ts.map

package/dist/types/timeview/shared/Tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tooltip.d.ts","sourceRoot":"","sources":["../../../../src/timeview/shared/Tooltip.tsx"],"names":[],"mappings":"AAIA,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,YAAY,+BAyC7G"}

package/dist/types/timeview/shared/useMeasuredWidth.d.ts

@@ -0,0 +1,2 @@
+export declare function useMeasuredWidth<T extends HTMLElement>(defaultWidth?: number): readonly [import("react").RefObject<T>, number];
+//# sourceMappingURL=useMeasuredWidth.d.ts.map

package/dist/types/timeview/shared/useMeasuredWidth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMeasuredWidth.d.ts","sourceRoot":"","sources":["../../../../src/timeview/shared/useMeasuredWidth.ts"],"names":[],"mappings":"AAIA,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,EAAE,YAAY,SAAO,mDAgB1E"}

package/dist/types/timeview/types.d.ts

@@ -0,0 +1,158 @@
+/** 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/timeview/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/timeview/types.ts"],"names":[],"mappings":"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"}

package/docs/AGENT-USAGE.md

@@ -0,0 +1,93 @@
+# Timeview Agent Usage
+
+Use this guide when an automation agent, cron job, or local script needs to generate
+Timeview charts or dashboards.
+
+## Install
+
+```bash
+npm install @jorgerdz/timeview
+npx playwright install chromium
+```
+
+The package exposes a `timeview` command:
+
+```bash
+npx timeview describe --json
+npx timeview validate ./chart.json --json
+npx timeview render ./chart.json --format png --preset 1600x900 --out ./out/chart.png --json
+npx timeview render-dashboard ./dashboard.json --out ./out --today 2026-06-10 --json
+```
+
+From this repository checkout, use the local script instead:
+
+```bash
+npm run --silent timeview -- describe --json
+```
+
+## Contract
+
+Agents should create a complete `TimeviewConfigV1`:
+
+```json
+{
+  "v": 1,
+  "visualizer": "bandedTimeline",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "labels": [],
+    "events": [],
+    "intervals": []
+  },
+  "spec": { "kind": "bandedTimeline" },
+  "palette": ["#2563eb", "#16a34a", "#dc2626"]
+}
+```
+
+Rules:
+
+- Run `timeview describe --json` before choosing a visualizer.
+- Validate the JSON before rendering.
+- Use complete datasets rather than fixture names.
+- Use ISO date strings.
+- Use `today: null` or an explicit ISO date for deterministic exports.
+- Use `today: "auto"` only for live browser previews; the CLI freezes it during export.
+- Keep palette arrays in config. Palette order maps to `dataset.labels` by index.
+
+## Error Handling
+
+The CLI writes human-readable errors to stderr and exits non-zero when validation or
+rendering fails. Add `--json` to receive a machine-readable stderr payload:
+
+```json
+{
+  "ok": false,
+  "code": "TIMEVIEW_CONFIG_INVALID",
+  "message": "Invalid Timeview config.",
+  "errors": ["schemaVersion must be \"timeview.dataset.v1\"."]
+}
+```
+
+Exit codes:
+
+- `1`: unexpected error
+- `2`: usage error
+- `3`: file or JSON read error
+- `4`: config or dashboard validation error
+- `5`: render error
+
+Prefer repairing the config and re-running validation before rendering.
+
+Future releases should keep `describe --json` machine-readable and additive whenever
+possible.
+
+## Examples
+
+Complete configs live in `examples/configs`:
+
+- `bandedTimeline.json`
+- `laneCalendar.json`
+- `densityHeatmap.json`
+- `metricTimeline.json`
+- `spanMatrix.json`