@event-timeline/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,439 @@
+/**
+ * A continuous timestamp in milliseconds since the Unix epoch (UTC).
+ *
+ * "Date-level" granularity is a display concern, not storage: all calendar
+ * interpretation (day boundaries, tick labels, day-clustering) is done in UTC,
+ * but the stored value is always milliseconds (DESIGN.md §1).
+ */
+type Time = number;
+/** An entity drawn as a horizontal line (lane). */
+interface TimelineElement<TData = unknown> {
+    id: string;
+    label: string;
+    /** URL, emoji, or preloaded image; drawn in the label area (Phase 2+). */
+    icon?: string | HTMLImageElement;
+    /** Per-element style overrides, merged over the theme (Phase 6). */
+    style?: Partial<ElementStyle>;
+    /** Ordering hint honoured only by the `explicit` layout strategy (§7). */
+    order?: number;
+    /** Opaque host payload, echoed back verbatim in callbacks. */
+    data?: TData;
+}
+/** A directed connector drawn as an arrow between two elements at a point in time. */
+interface TimelineEvent<TData = unknown> {
+    id: string;
+    /** Element the arrow leaves (source node dot). */
+    sourceId: string;
+    /** Element the arrow enters (arrowhead). */
+    targetId: string;
+    /** The moment the event occurs. */
+    time: Time;
+    label?: string;
+    style?: Partial<EventStyle>;
+    data?: TData;
+}
+/** A clean dataset handed to the engine to render. */
+interface TimelineData<TData = unknown> {
+    elements: TimelineElement<TData>[];
+    events: TimelineEvent<TData>[];
+}
+/**
+ * The complete set of stylable element properties (DESIGN.md §11). The same
+ * shape is reused at every level of the resolution chain (theme default →
+ * resolver → per-item `style`), so there is one definition of "what is
+ * stylable" rather than parallel shapes per layer (DRY). Sizes are CSS px.
+ */
+interface ElementStyle {
+    lineColor: string;
+    lineWidth: number;
+    labelColor: string;
+    /** CSS font shorthand, e.g. "12px Inter, sans-serif". */
+    labelFont: string;
+    iconSize: number;
+}
+/** The complete set of stylable event properties (DESIGN.md §11). Sizes are CSS px. */
+interface EventStyle {
+    arrowColor: string;
+    arrowWidth: number;
+    arrowheadSize: number;
+    labelColor: string;
+    labelFont: string;
+    /** Source node dot radius. */
+    nodeRadius: number;
+}
+/** Engine-wide theme: defaults plus structural metrics (DESIGN.md §11). */
+interface Theme {
+    background: string;
+    gridlineColor: string;
+    headerTextColor: string;
+    headerFont: string;
+    /** Height of the (multi-row) time header in CSS px. */
+    headerHeight: number;
+    rowHeight: number;
+    rowGap: number;
+    labelPadding: number;
+    /** Overlay colour for the hovered primitive (DESIGN.md §9). */
+    hoverColor: string;
+    /** Overlay colour for selected primitives' outlines (DESIGN.md §9). */
+    selectionColor: string;
+    /** Colour of collapsed-event cluster markers and their counts (DESIGN.md §6). */
+    clusterColor: string;
+    /** Theme-level element defaults (base of the resolution chain). */
+    element: ElementStyle;
+    /** Theme-level event defaults (base of the resolution chain). */
+    event: EventStyle;
+}
+
+/** Why an item was dropped during ingest. */
+type DiagnosticCode = 'invalid-time' | 'dangling-edge' | 'duplicate-id';
+interface Diagnostic {
+    code: DiagnosticCode;
+    kind: 'element' | 'event';
+    /** Id of the offending item, when known. */
+    id?: string;
+    reason: string;
+}
+type OnDiagnostic = (d: Diagnostic) => void;
+
+interface LayoutStrategy {
+    /**
+     * Pure function of the data: returns element ids in top-to-bottom order.
+     * No rendering, no side effects, no pixels — trivially unit-testable.
+     */
+    order(elements: readonly TimelineElement[], events: readonly TimelineEvent[]): string[];
+}
+
+/** Per-frame context handed to a strategy; carries the current zoom (§6). */
+interface ClusterContext {
+    /** Pixel separation under which same-key events merge (also the column width). */
+    minSeparationPx: number;
+    /** Camera time→screen-x (the single coordinate source, §3). */
+    timeToScreenX(t: Time): number;
+}
+interface ClusterStrategy {
+    /**
+     * Stable grouping key for an event at the current zoom. Events sharing a key
+     * and within `minSeparationPx` collapse into one marker; pure, no side effects.
+     */
+    key(event: TimelineEvent, ctx: ClusterContext): string;
+}
+/**
+ * A run of one or more events that render as a unit. A single-event cluster is
+ * "un-clustered" — the renderer draws it as an ordinary arrow; a multi-event
+ * cluster draws a count marker (§6).
+ */
+interface Cluster<TData = unknown> {
+    events: TimelineEvent<TData>[];
+}
+
+type TickLevel = 'year' | 'month' | 'day';
+type TickFormatter = (date: Date, level: TickLevel) => string;
+
+/**
+ * Overlay `partials` onto a complete `base`, later partials winning. A property
+ * set to `undefined` (or absent) in a partial **falls through** to the previous
+ * layer, matching the `?? theme.default` semantics each level previously used and
+ * keeping per-property independence (§11): a partial only overrides the keys it
+ * actually sets.
+ */
+declare function overlayStyle<T extends object>(base: T, ...partials: Array<Partial<T> | undefined>): T;
+/** Data-driven element style override (§11); merged between theme and `.style`. */
+type ElementStyleResolver<TData = unknown> = (element: TimelineElement<TData>) => Partial<ElementStyle>;
+/** Data-driven event style override (§11); merged between theme and `.style`. */
+type EventStyleResolver<TData = unknown> = (event: TimelineEvent<TData>) => Partial<EventStyle>;
+
+type HitResult<TData = unknown> = {
+    kind: 'element';
+    element: TimelineElement<TData>;
+} | {
+    kind: 'event';
+    event: TimelineEvent<TData>;
+} | {
+    kind: 'cluster';
+    events: TimelineEvent<TData>[];
+    count: number;
+};
+
+interface TimelineEventMap<TData = unknown> {
+    viewportChange: {
+        timeRange: [number, number];
+        scrollY: number;
+        pxPerMs: number;
+        visibleRowRange: [number, number];
+    };
+    hover: HitResult<TData> | null;
+    click: {
+        hit: HitResult<TData>;
+        modifiers: {
+            ctrlOrMeta: boolean;
+            shift: boolean;
+        };
+    };
+    selectionChange: {
+        ids: string[];
+    };
+    dataChange: {
+        added: number;
+        removed: number;
+        updated: number;
+    };
+    ready: void;
+}
+
+/** Event collapsing/aggregation config (DESIGN.md §6); all fields defaulted. */
+interface ClusteringOptions {
+    /** Collapse dense events into count markers. Default `true`. */
+    enabled?: boolean;
+    /** Keying strategy. Default `bySourceTargetColumn`. */
+    strategy?: ClusterStrategy;
+    /** Pixel separation under which same-key events merge. Default 12. */
+    minSeparationPx?: number;
+}
+/** Level-of-detail config (DESIGN.md §6); all fields defaulted. */
+interface LodOptions {
+    /** Zoom (CSS px per ms) at/above which per-event labels are drawn. */
+    eventLabelMinPxPerMs?: number;
+}
+/**
+ * Per-frame timing for one drawn layer (DESIGN.md §13). Emitted to the optional
+ * `onFrameStats` sink after each layer draw so hosts and the perf benchmark can
+ * assert the §13 budgets (≤16ms base, ≤4ms overlay at 50k) without the engine
+ * itself depending on `performance` or any logging implementation (DIP).
+ */
+interface FrameStats {
+    layer: 'base' | 'overlay';
+    /** Wall-clock cost of the layer's draw, in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Data-driven per-item style overrides (DESIGN.md §11). Each callback runs
+ * between the theme default and the item's own `.style`; most specific wins.
+ */
+interface StyleResolvers<TData = unknown> {
+    element?: ElementStyleResolver<TData>;
+    event?: EventStyleResolver<TData>;
+}
+/**
+ * Label/tick text formatters (DESIGN.md §11). When omitted the engine echoes the
+ * raw label (and the built-in UTC tick formatter of §8).
+ */
+interface Formatters<TData = unknown> {
+    tickLabel?: TickFormatter;
+    eventLabel?: (event: TimelineEvent<TData>) => string;
+    elementLabel?: (element: TimelineElement<TData>) => string;
+}
+interface TimelineEngineOptions<TData = unknown> {
+    theme?: Partial<Theme>;
+    onDiagnostic?: OnDiagnostic;
+    layout?: LayoutStrategy;
+    /**
+     * Trailing-edge delay (ms) for coalescing incremental re-layouts (DESIGN.md
+     * §7, §10). Applies only to the incremental seam ({@link scheduleLayoutRecompute});
+     * a full `setData` always recomputes synchronously. Default 120.
+     */
+    layoutDebounceMs?: number;
+    /** Allow `ctrl`/`⌘`+click to extend the selection (DESIGN.md §9). */
+    multiSelect?: boolean;
+    /**
+     * Re-layout policy for incremental mutations (`addEvents`/… §10). Default
+     * `'stable-append'`: existing rows stay put and new elements append, applied
+     * synchronously so updates appear at once with no jarring reshuffle (§7).
+     * `'full'` opts into re-running the configured {@link layout} strategy on the
+     * debounced {@link layoutDebounceMs} seam. `setData` always relayouts in full.
+     */
+    streamingLayout?: 'stable-append' | 'full';
+    clustering?: ClusteringOptions;
+    lod?: LodOptions;
+    /** Data-driven per-item style overrides (DESIGN.md §11). */
+    styleResolvers?: StyleResolvers<TData>;
+    /** Label/tick text formatters (DESIGN.md §11). */
+    formatters?: Formatters<TData>;
+    /**
+     * Optional per-frame timing sink (DESIGN.md §13). When supplied, each layer
+     * draw is bracketed with `performance.now()` and reported; when omitted the
+     * draw path stays allocation- and measurement-free (zero overhead).
+     */
+    onFrameStats?: (stats: FrameStats) => void;
+}
+declare class TimelineEngine<TData = unknown> {
+    private readonly theme;
+    private readonly metrics;
+    private readonly store;
+    private readonly camera;
+    private readonly renderer;
+    private readonly scheduler;
+    private readonly emitter;
+    private readonly pointer;
+    private readonly multiSelect;
+    private readonly layoutStrategy;
+    /** Incremental re-layout policy (DESIGN.md §7, §10). */
+    private readonly streamingLayout;
+    /**
+     * Coalesced incremental re-layout (DESIGN.md §7). Streaming mutations
+     * (`addEvents`/`removeEvents`, §10) call {@link scheduleLayoutRecompute} so a
+     * burst re-runs layout once; `setData` bypasses this and recomputes inline.
+     */
+    private readonly debouncedRecomputeLayout;
+    /** Resolved per-frame LOD/clustering config (DESIGN.md §6). */
+    private readonly lod;
+    private readonly clustering;
+    /**
+     * §11 style/label resolution, bound once from the theme + host resolvers. The
+     * builders receive these via `BuildContext`, so resolution lives in one place.
+     */
+    private readonly resolveElementStyle;
+    private readonly resolveEventStyle;
+    private readonly formatElementLabel;
+    private readonly formatEventLabel;
+    private readonly tickFormatter;
+    /** Optional per-frame timing sink (DESIGN.md §13); undefined disables timing. */
+    private readonly onFrameStats?;
+    private readonly iconCache;
+    /**
+     * Resolve an element icon for the current frame (§1, §11): a preloaded image
+     * is used directly when decoded, a URL is loaded/cached (skipped until ready),
+     * and any other string (emoji/glyph) is drawn as text by the builder.
+     */
+    private readonly resolveIcon;
+    private viewport;
+    private dpr;
+    private rowLayout;
+    private hasFitted;
+    private disposed;
+    /** Hit grid + targets rebuilt each base draw; reused during pure hover (§5). */
+    private hitGrid;
+    private frameTargets;
+    /** Latest cursor position pending a (frame-coalesced) hit-test, or null. */
+    private pendingPointer;
+    private hovered;
+    private readonly selectedIds;
+    constructor(baseCanvas: HTMLCanvasElement, overlayCanvas: HTMLCanvasElement, options?: TimelineEngineOptions<TData>);
+    setData(data: TimelineData<TData>): void;
+    /** Incrementally insert events without a full rebuild (DESIGN.md §10). */
+    addEvents(events: readonly TimelineEvent<TData>[]): void;
+    /** Remove events by id (DESIGN.md §10). */
+    removeEvents(ids: readonly string[]): void;
+    /** Append elements with stable-append layout (DESIGN.md §7, §10). */
+    addElements(elements: readonly TimelineElement<TData>[]): void;
+    /** Patch an element's label/icon/style/order in place (DESIGN.md §10). */
+    updateElement(id: string, patch: Partial<TimelineElement<TData>>): void;
+    /**
+     * Shared tail for the incremental mutations (§10): a no-op change emits and
+     * redraws nothing; otherwise re-layout (stable-append by default, §7), emit
+     * `dataChange`, and mark the base dirty. Streaming never refits — that would
+     * jerk the camera mid-stream.
+     */
+    private applyMutation;
+    resize(cssWidth: number, cssHeight: number, dpr: number): void;
+    fit(): void;
+    panToTime(t: Time): void;
+    /** Frame a time range across the viewport width (DESIGN.md §12). */
+    zoomToRange(start: Time, end: Time): void;
+    /**
+     * Replace the selection imperatively (DESIGN.md §9, §12). Ids are the
+     * `kind:id` composites produced by hit-testing (see {@link hitId}), so an
+     * element and an event sharing a raw id stay distinct. A no-op replacement
+     * emits nothing and skips the overlay redraw.
+     */
+    select(ids: string[]): void;
+    getViewport(): TimelineEventMap<TData>['viewportChange'];
+    on<K extends keyof TimelineEventMap<TData>>(key: K, fn: (payload: TimelineEventMap<TData>[K]) => void): () => void;
+    off<K extends keyof TimelineEventMap<TData>>(key: K, fn: (payload: TimelineEventMap<TData>[K]) => void): void;
+    dispose(): void;
+    private now;
+    private zoomBounds;
+    /**
+     * Edge space reserved when fitting (§3): a left gutter so the leftmost line's
+     * start marker (icon + label, §1) clears the viewport edge instead of being
+     * clipped. Derived from the theme so host themes scale it. With no elements
+     * there are no markers, so nothing is reserved (the empty-state window stays
+     * centred on `now`, §3.1).
+     */
+    private fitInset;
+    /**
+     * Recompute row order + positions (DESIGN.md §7). `'full'` runs the configured
+     * strategy (used by `setData` and the opt-in streaming relayout); `'stable-append'`
+     * keeps existing rows and appends new elements (the streaming default, §10).
+     */
+    private recomputeLayout;
+    /**
+     * Apply layout after an *incremental* mutation (DESIGN.md §7, §10). By default
+     * (`streamingLayout: 'stable-append'`) this runs synchronously so new rows and
+     * extents appear at once with no reshuffle; under `'full'` a burst is coalesced
+     * into one trailing strategy recompute via the debounced seam. Full `setData`
+     * bypasses this and recomputes synchronously so `fit`/scroll-clamp see
+     * `contentHeight` immediately.
+     */
+    private scheduleLayoutRecompute;
+    /**
+     * Frame the view before the first explicit fit. With data, fit to it once and
+     * latch (`hasFitted`). Without data, frame the default window on `now` (§3.1)
+     * but stay un-latched, so real data still auto-fits when it arrives.
+     */
+    private maybeFit;
+    /** Mark the base layer dirty and emit the new viewport (any camera change). */
+    private onCameraChange;
+    /**
+     * The semantic-intent sink for the pointer controller (§9). The controller
+     * does no math; every camera mutation and hit-test is applied here so the
+     * Camera stays the single source of coordinate truth (§3).
+     */
+    private pointerHost;
+    /** Resolve a click against the current hit grid: emit click + update selection. */
+    private onClick;
+    /** Zoom to a clicked cluster's member time span, expanding it (§6). */
+    private expandCluster;
+    private emitViewportChange;
+    private drawFrame;
+    /**
+     * Run one layer's draw, reporting its wall-clock cost to `onFrameStats` when a
+     * sink is set (DESIGN.md §13). With no sink the draw runs directly — no
+     * `performance.now()` calls, no allocation — so timing is truly opt-in.
+     */
+    private timed;
+    private drawBase;
+    /**
+     * Overlay pass (DESIGN.md §4, §9): resolve the pending hover against the hit
+     * grid (emitting `hover` only on change), then redraw the hovered and selected
+     * primitives in the highlight/selection colours. It reuses this frame's
+     * `frameTargets` geometry — no recompute — and never touches the base layer,
+     * so hover/selection stay independent of the expensive base redraw.
+     */
+    private drawOverlay;
+    /**
+     * Overlay colour for a target, or null when it should not highlight. A target
+     * highlights when it is itself hovered/selected, or — for an event/cluster —
+     * when one of its endpoints is a hovered/selected element (§9). Hover wins the
+     * colour over selection.
+     */
+    private highlightColorFor;
+    /** Run the coalesced hit-test for the latest cursor position and emit on change. */
+    private resolveHover;
+    /** Redraw one target's geometry in `color`, slightly thickened, on the overlay. */
+    private drawHighlight;
+}
+
+declare const byFirstEvent: LayoutStrategy;
+
+declare const barycenter: LayoutStrategy;
+
+declare const explicit: LayoutStrategy;
+
+/** Collapse every event sharing a pixel column, regardless of endpoints. */
+declare const byPixelColumn: ClusterStrategy;
+/** Collapse events between the same source and target (proximity-gated, §6). */
+declare const byElementPair: ClusterStrategy;
+/** Collapse events sharing a UTC calendar day (proximity-gated, §6). */
+declare const byDay: ClusterStrategy;
+/**
+ * Default: `(sourceId, targetId, pixelColumn)` — same-direction events in the
+ * same column collapse, so a dense fan-out between two lines reads as one marker.
+ */
+declare const bySourceTargetColumn: ClusterStrategy;
+
+declare const defaultTheme: Theme;
+
+/** Current package version placeholder; real releases are driven by Changesets. */
+declare const VERSION = "0.0.0";
+
+export { type Cluster, type ClusterContext, type ClusterStrategy, type ClusteringOptions, type Diagnostic, type DiagnosticCode, type ElementStyle, type ElementStyleResolver, type EventStyle, type EventStyleResolver, type Formatters, type FrameStats, type HitResult, type LayoutStrategy, type LodOptions, type OnDiagnostic, type StyleResolvers, type Theme, type TickFormatter, type TickLevel, type Time, type TimelineData, type TimelineElement, TimelineEngine, type TimelineEngineOptions, type TimelineEvent, type TimelineEventMap, VERSION, barycenter, byDay, byElementPair, byFirstEvent, byPixelColumn, bySourceTargetColumn, defaultTheme, explicit, overlayStyle };