DreamLake
Browse docs

Timeline

EpisodeTimeline combines thumbnails and labeled intervals on an episode clock. Use it to inspect an event and seek paired video or charts.

The surface is transparent by default, so the timeline sits on its parent's surface. Use background="subtle" when a separate tinted panel is useful. Annotation and loading-range colors remain visible with either setting. Short major and minor ruler ticks distinguish fractional seconds without a full-height grid; labels adapt to the recording duration and available width.

Basic usage

Hover to preview a moment; click to seek. Zoom in to reveal more thumbnails:

1.00×
Code BasicSpec.tsx
tsx
<EpisodeTimeline
  duration={60}
  frames={frames}
  tracks={tracks}
  time={time}
  onHover={setHover}
  onHoverEnd={() => setHover(null)}
  onSeek={setTime}
/>

Hover temporarily overrides time. On pointer leave, the cursor returns to that value, or disappears when it is null. Keep playback time separate when hover should preview without committing a seek.

Shared click-to-pin and hover preview

Use one shared clock and useTimelinePreview(clock) for linked plots, video or 3D views. Clicking pins a time; hover still previews other moments in every view. Leaving the current preview returns all views to the pin. Without a pin, leave restores the time from before the first preview.

Click either plot to pin all views. Hover another moment, then leave: every view returns to the pin. Hover keeps working after a click.

Recorded position
50
0s0.5s1s1.5s2s2.5s3s(s)
Recorded force
420
0s0.5s1s1.5s2s2.5s3s(s)
1.00×
All views: 0.000 sNo pinNo preview

The slider supports touch and arrow keys; Enter pins its selected time. Escape, blur or touch release ends its preview. Pin pauses playback; Play / resume clears pin and preview, then advances from the displayed time.

Code SharedPinPreviewSpec.tsx

The example has two transparent 150px charts, a timeline and a child readout subscribed through ClockProvider. A 3D scene or video should consume the same clock with useClockValue(fps, clock) or through the provider. Do not copy the pin into independent state for each chart, and do not guard hover with if (!pinnedTime): a pin is the return time, not a hover lock.

tsx
import { useTimeline, useTimelinePreview, useClockValue } from "@dreamlake/viz";

const { clock } = useTimeline(duration);
const time = useClockValue(30, clock);
const preview = useTimelinePreview(clock);
const bind = (owner: string) => ({
  time,
  onHover: (time: number) => preview.preview(owner, time),
  onHoverEnd: () => preview.endPreview(owner),
  onSeek: preview.pin,
});

<EpisodeLineChart {...bind("position")} series={position} duration={duration} />
<EpisodeLineChart {...bind("force")} series={force} duration={duration} />
<EpisodeTimeline {...bind("timeline")} duration={duration} />

Assign each view a stable owner ID. A new owner's preview takes over immediately; a late endPreview from the previous owner is ignored. All owners share the original return time until the current preview ends. The hook resolves an explicit clock or the surrounding ClockProvider; hook consumers of the same clock share its controller. Prefer creating it once at the linked group's root.

The hook restores an active preview and releases its hold when its last consumer unmounts. For non-React integrations, new TimelinePreviewController(clock) exposes the same actions plus getSnapshot() and subscribe(listener); call dispose() when finished. Construction and server rendering do not seek or subscribe to the clock.

Preview controller API

MemberMeaning
pinnedTimeCommitted return time in seconds, or null.
previewTimeCurrent transient preview time, or null.
previewOwnerCurrent string or symbol owner ID, or null.
preview(owner, time)Move the shared clock to a transient time; works while pinned.
endPreview(owner)Restore the pin or pre-preview time if this owner is still current.
pin(time)Pause and commit a shared return time; preserve current ownership so hover continues.
clearPin()Remove the pin without changing the displayed time or ending an ongoing preview.
play()Clear pin and preview, release the controller's hold, then play from the displayed time.

Times are episode seconds. Non-finite inputs are ignored; finite times clamp to the clock's duration. This changes only the displayed clock time: charts still read nearest recorded samples and keep exact data and domains.

Playback, keyboard and touch

Preview temporarily holds clock advancement without changing its playing flag or other holds. Leaving restores the return time and releases that hold; playback then continues if it was running. Pinning pauses playback. The controller's play() is the explicit resume action: it clears pin and preview before calling clock.play(), including when playback was already logically running but held by preview. An external seek clears the controller's pin and preview as a navigation override; use preview() for transient inspection.

The native slider and buttons in the example make the same actions available to keyboard and touch users. Arrow keys preview the selected time, Enter pins, and Escape or blur ends the slider preview. Touch release ends its preview; "Pin selected time" commits it. Plot and timeline clicks also call pin. Chart zoom/pan keyboard controls keep their existing behavior. If another component implements its own controls, route them through this same controller.

Frames

Supply thumbnails in ascending time order. Their left edges mark their timestamps. Omit frames to show only the ruler and annotation tracks.

ts
interface FrameSample {
  time: number; // seconds, from 0 to duration
  image: string;
  alt?: string; // retained in data; not currently surfaced by the canvas
}

const frames: FrameSample[] = [
  { time: 0, image: "/keyframes/000.jpg" },
  { time: 0.5, image: "/keyframes/030.jpg" },
  { time: 1, image: "/keyframes/060.jpg" },
];

Reveal more frames

The strip hides overlapping thumbnails with a four-pixel gap between visible images. Zooming reveals more of the supplied frames; the footer reports visible and total counts. The first frame at a duplicate timestamp is kept.

Tracks and blocks

Place task phases or actions in separate rows. Dashed edges mark intervals that continue outside the visible window.

ts
interface TrackBlock {
  id?: string;
  start: number;
  end: number;
  label: string;
}
interface TimelineTrack {
  id: string;
  name?: string; // accessible name, not a visible row label
  blocks: TrackBlock[];
}

const tracks: TimelineTrack[] = [
  {
    id: "phases",
    name: "Task phases",
    blocks: [
      { id: "idle", start: 0, end: 2.4, label: "Idle" },
      { id: "approach", start: 2.4, end: 9.1, label: "Approach" },
    ],
  },
];

Use stable block IDs for callbacks. A block click calls onBlockClick instead of onSeek, allowing annotation inspection without moving playback.

Interaction model

GestureResult
HoverShow the cursor and call onHover(time); call onHoverEnd on leave.
Click empty spaceCall onSeek(time).
Click a blockCall onBlockClick(block, trackId).
Drag at least four pixelsPan when zoomed in.
Shift + vertical dragZoom around the initial pointer position.
Alt, Ctrl, or Meta + wheelZoom around the pointer; trackpad pinch also uses this path.
Horizontal wheelPan. The timeline consumes this gesture to prevent browser history navigation.
Zoom controlsStep zoom or drag the readout for continuous adjustment.

Controlled vs uncontrolled viewport

A standalone timeline manages zoom and pan. Share viewport state to align it with other panels:

tsx
const [viewport, setViewport] = useState({ zoom: 1, panPct: 0 })
<EpisodeTimeline
  duration={duration}
  {...viewport}
  onViewportChange={setViewport}
/>
ts
interface ViewportState {
  zoom: number; // 1 shows the full episode
  panPct: number; // 0 through 1 - 1 / zoom
}

The window starts at panPct * duration and spans duration / zoom. Providing either value controls both; an omitted value uses its default. Apply gestures through onViewportChange and reset to { zoom: 1, panPct: 0 }. Try the shared viewport example.

Loading ranges

Zoom anchors to the pointer and stays inside the episode. For chunked data, pass loadedRanges and pendingRanges as { from, to } intervals in episode seconds to mark available and loading regions.

Props

PropTypeDefaultPurpose
durationnumberrequiredEpisode duration in seconds, greater than zero.
framesFrameSample[][]Thumbnails in ascending time order.
tracksTimelineTrack[][]Track rows, in display order.
timenumber | nullnullCursor position when the pointer is not hovering.
onHover(t: number) => void—Receive the pointer's time.
onHoverEnd() => void—Receive pointer leave.
onSeek(t: number) => void—Receive a click in empty space.
loadedRanges{ from: number; to: number }[] | null—Available spans, shown below the ruler.
pendingRanges{ from: number; to: number }[]—Spans currently loading.
zoom / panPctnumber1 / 0Controlled visible window.
onViewportChange(v: ViewportState) => void—Receive requested viewport changes.
onBlockClick(block: TrackBlock, trackId: string) => void—Receive a block click.
onBlockHover(block: TrackBlock | null, trackId: string | null) => void—Receive block hover changes; null on leave.
framesLabelstring'FRAMES'Caption below the thumbnails.
frameHeightnumberautoThumbnail height in pixels; width uses 16:9. Automatic sizing fits 12 cells.
trackRowHeightnumber28Track height in pixels.
minZoom / maxZoomnumber1 / InfinityZoom limits.
classNamestring—Root CSS classes.
background"none" | "subtle""none"Opt into a tinted panel surface.