entangle-ui 0.9.0 → 0.11.0

package/dist/esm/components/editor/Timeline/Timeline.js

@@ -0,0 +1,450 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React, { useRef, useState, useMemo, useCallback, useSyncExternalStore, useLayoutEffect, useImperativeHandle, useEffect } from 'react';
+import '../../../utils/devWarn.js';
+import { useControlledState } from '../../../hooks/useControlledState/useControlledState.js';
+import { useLatest } from '../../../hooks/useLatest/useLatest.js';
+import { useResizeObserver } from '../../../hooks/useResizeObserver/useResizeObserver.js';
+import '../../../hooks/useBreakpoint/useBreakpoint.js';
+import './../../../assets/src/theme/lightTheme.css.ts.vanilla-Ct6f9Iym.css';
+import '@vanilla-extract/css';
+import './../../../assets/src/theme/darkTheme.css.ts.vanilla-BHZ3ecRn.css';
+import './../../../assets/src/theme/globalScrollbars.css.ts.vanilla-BAJwnUEJ.css';
+import '../../../hooks/useNavigationHistory/useNavigationHistory.js';
+import { cx } from '../../../utils/cx.js';
+import { timelineMainRowStyle, timelineBodyStyle, timelineCanvasStyle, timelineOverlayLayerStyle, ariaLiveRegionStyle, timelineShellStyle, timelineToolbarStyle, timelineFooterStyle } from './Timeline.css.js';
+import { TIMELINE_SLOT } from './Timeline.types.js';
+import { TimelineStoreContext } from './TimelineContext.js';
+import { resolveLoop, snapFrame, nextFollowView } from './timelineCoords.js';
+import { computeRows } from './timelineLayout.js';
+import { TimelineStore } from './TimelineStore.js';
+import { TimelineTrackHeaders } from './TimelineTrackHeaders.js';
+import { useTimelineDraw } from './useTimelineDraw.js';
+import { useTimelineGestures } from './useTimelineGestures.js';
+import { useTimelinePlayback } from './useTimelinePlayback.js';
+import { clamp } from '../../../utils/mathUtils.js';
+
+const RULER_HEIGHT = 22;
+const LOOP_STRIP_HEIGHT = 12;
+function getSlotKind(el) {
+    const marker = el.type[TIMELINE_SLOT];
+    return marker ?? null;
+}
+function categorizeChildren(children) {
+    const slots = {
+        toolbar: null,
+        footer: null,
+        minimap: null,
+        trackScale: null,
+        overlay: [],
+    };
+    React.Children.forEach(children, child => {
+        if (!React.isValidElement(child)) {
+            if (child !== null && child !== undefined && child !== false) {
+                slots.overlay.push(child);
+            }
+            return;
+        }
+        const kind = getSlotKind(child);
+        const props = child.props;
+        if (kind === 'track-scale') {
+            slots.trackScale = child.props;
+            return;
+        }
+        if (kind === 'toolbar') {
+            slots.toolbar = (jsx("div", { className: cx(timelineToolbarStyle, props.className), style: props.style, children: props.children }));
+        }
+        else if (kind === 'footer') {
+            slots.footer = (jsx("div", { className: cx(timelineFooterStyle, props.className), style: props.style, children: props.children }));
+        }
+        else if (kind === 'minimap') {
+            slots.minimap = child;
+        }
+        else {
+            slots.overlay.push(child);
+        }
+    });
+    return slots;
+}
+/**
+ * Horizontal multi-track animation timeline / dope sheet. Tracks hold
+ * keyframes (the shared `CurveKeyframe` model) along a frame-based time axis;
+ * a playhead scrubs across all tracks. Canvas-rendered keyframes with DOM
+ * chrome, store-driven via `useSyncExternalStore`.
+ *
+ * Children read live state via `useTimelineContext()` / `useTimelineGeometry()`
+ * / `useTimelinePlayhead()` / `useTimelineSelection()`.
+ */
+const Timeline = (props) => {
+    const { tracks, onTracksChange, onTracksChangeComplete, startFrame = 0, endFrame, fps = 30, frame, defaultFrame, onFrameChange, onFrameChangeComplete, view, defaultView, onViewChange, minFramesVisible = 1, maxFramesVisible, selection, defaultSelection, onSelectionChange, editable = true, allowAddKeyframe = true, allowDeleteKeyframe = true, snap = true, mode, defaultMode, onModeChange, playing, defaultPlaying, onPlayingChange, loop, defaultLoop, onLoopChange, followMode = 'smooth', loopStrip = false, loopHandles = 'edges', groups, onGroupsChange, trackHeight = 28, expandedTrackHeight = 96, groupHeaderHeight = 22, showRuler = true, showPlayhead = true, trackHeaderWidth = 160, responsive = true, height, playheadColor, backgroundColor, trackScale: trackScaleProp, renderOverlay, renderTrackHeader, formatTime, ariaLabel = 'Timeline', className, style, testId, id, children, ref, } = props;
+    const bodyRef = useRef(null);
+    const canvasRef = useRef(null);
+    const headerColumnRef = useRef(null);
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    const [scrollTop, setScrollTop] = useState(0);
+    const fullView = useMemo(() => ({ startFrame, endFrame }), [startFrame, endFrame]);
+    // ── Controlled / uncontrolled state ──
+    const [frameState, setFrame] = useControlledState({
+        value: frame,
+        defaultValue: defaultFrame,
+        onChange: onFrameChange,
+        fallback: startFrame,
+    });
+    const [viewState, setView] = useControlledState({
+        value: view,
+        defaultValue: defaultView,
+        onChange: onViewChange,
+        fallback: fullView,
+    });
+    const [selectionState, setSelection] = useControlledState({
+        value: selection,
+        defaultValue: defaultSelection,
+        onChange: onSelectionChange,
+        fallback: [],
+    });
+    const [modeState] = useControlledState({
+        value: mode,
+        defaultValue: defaultMode,
+        onChange: onModeChange,
+        fallback: 'dope-sheet',
+    });
+    const [playingState, setPlaying] = useControlledState({
+        value: playing,
+        defaultValue: defaultPlaying,
+        onChange: onPlayingChange,
+        fallback: false,
+    });
+    const [loopState, setLoop] = useControlledState({
+        value: loop,
+        defaultValue: defaultLoop,
+        onChange: onLoopChange,
+        fallback: false,
+    });
+    const loopRegion = useMemo(() => resolveLoop(loopState, startFrame, endFrame), [loopState, startFrame, endFrame]);
+    // ── Groups (controlled or uncontrolled) ──
+    const [internalGroups, setInternalGroups] = useState(groups ?? []);
+    const groupsState = groups ?? internalGroups;
+    const setGroups = useCallback((next) => {
+        if (groups === undefined)
+            setInternalGroups(next);
+        onGroupsChange?.(next);
+    }, [groups, onGroupsChange]);
+    // ── Row layout (variable heights: expanded lanes + group headers) ──
+    const layout = useMemo(() => computeRows(tracks, {
+        trackHeight,
+        expandedHeight: expandedTrackHeight,
+        groupHeaderHeight,
+        globalGraph: modeState === 'graph',
+        groups: groupsState,
+    }), [
+        tracks,
+        trackHeight,
+        expandedTrackHeight,
+        groupHeaderHeight,
+        modeState,
+        groupsState,
+    ]);
+    // ── Store ──
+    const store = useMemo(() => new TimelineStore(), []);
+    const drag = useSyncExternalStore(store.subscribeDrag, store.getDrag);
+    const hover = useSyncExternalStore(store.subscribeHover, store.getHover);
+    const hoverPlayhead = useSyncExternalStore(store.subscribeHoverPlayhead, store.getHoverPlayhead);
+    const hoverLoop = useSyncExternalStore(store.subscribeHoverLoop, store.getHoverLoop);
+    useLayoutEffect(() => {
+        store.setGeometry({
+            view: viewState,
+            size,
+            trackHeight,
+            scrollTop,
+            startFrame,
+            endFrame,
+            fps,
+            mode: modeState,
+        });
+    }, [
+        store,
+        viewState,
+        size,
+        trackHeight,
+        scrollTop,
+        startFrame,
+        endFrame,
+        fps,
+        modeState,
+    ]);
+    useLayoutEffect(() => {
+        store.setPlayhead({ frame: frameState, playing: playingState });
+    }, [store, frameState, playingState]);
+    useLayoutEffect(() => {
+        store.setSelection(selectionState);
+    }, [store, selectionState]);
+    // ── Seek helpers (snap + clamp) ──
+    const applyFrame = useCallback((f) => clamp(snapFrame(f, snap), startFrame, endFrame), [snap, startFrame, endFrame]);
+    const seekLive = useCallback((f) => {
+        setFrame(applyFrame(f));
+    }, [setFrame, applyFrame]);
+    // Consumer callbacks live behind refs so the handlers that fire them keep a
+    // stable identity even when the parent passes a fresh inline function every
+    // render (component-patterns.md rules #3 / #11).
+    const onFrameCompleteRef = useLatest(onFrameChangeComplete);
+    const seekCommit = useCallback((f) => {
+        const v = applyFrame(f);
+        setFrame(v);
+        onFrameCompleteRef.current?.(v);
+    }, [setFrame, applyFrame, onFrameCompleteRef]);
+    // ── Playback (optional built-in rAF loop) ──
+    const setFrameRaw = useCallback((f) => {
+        setFrame(clamp(f, startFrame, endFrame));
+    }, [setFrame, startFrame, endFrame]);
+    const handlePlaybackEnd = useCallback(() => {
+        setPlaying(false);
+    }, [setPlaying]);
+    useTimelinePlayback({
+        playing: playingState,
+        frame: frameState,
+        fps,
+        startFrame,
+        endFrame,
+        loop: loopState,
+        onAdvance: setFrameRaw,
+        onEnd: handlePlaybackEnd,
+    });
+    // ── Follow-playhead during playback ──
+    // `smooth` keeps the playhead centred in the view — the view slides
+    // continuously once the playhead reaches the centre (one frame per tick,
+    // so visually smooth). `paged` waits until the playhead leaves the view
+    // and then jumps forward by a full span (After Effects vs Premiere style).
+    // `off` leaves the view alone.
+    useLayoutEffect(() => {
+        if (!playingState)
+            return;
+        const next = nextFollowView(followMode, viewState, frameState, startFrame, endFrame);
+        if (next)
+            setView(next);
+    }, [
+        playingState,
+        followMode,
+        frameState,
+        viewState,
+        setView,
+        startFrame,
+        endFrame,
+    ]);
+    // ── Track-edit helpers ──
+    // Track-change callbacks behind refs (same rationale as `seekCommit`): the
+    // gesture hook + header handlers stay stable while the parent may pass fresh
+    // inline `onTracksChange` / `onTracksChangeComplete` each render.
+    const onTracksChangeRef = useLatest(onTracksChange);
+    const onTracksChangeCompleteRef = useLatest(onTracksChangeComplete);
+    const setTracksLive = useCallback((t) => {
+        onTracksChangeRef.current?.(t);
+    }, [onTracksChangeRef]);
+    const commitTracks = useCallback((t) => {
+        onTracksChangeCompleteRef.current?.(t);
+    }, [onTracksChangeCompleteRef]);
+    const handleReorderTracks = useCallback((next) => {
+        setTracksLive(next);
+        commitTracks(next);
+    }, [setTracksLive, commitTracks]);
+    const handleToggleTrackExpanded = useCallback((trackId) => {
+        const next = tracks.map(t => t.id === trackId ? { ...t, expanded: !t.expanded } : t);
+        setTracksLive(next);
+        commitTracks(next);
+    }, [tracks, setTracksLive, commitTracks]);
+    const handleToggleGroupCollapsed = useCallback((groupId) => {
+        setGroups(groupsState.map(g => g.id === groupId ? { ...g, collapsed: !g.collapsed } : g));
+    }, [groupsState, setGroups]);
+    // ── View helpers + imperative handle ──
+    const rangeSpan = Math.max(1, endFrame - startFrame);
+    const clampView = useCallback((v) => {
+        const maxSpan = maxFramesVisible ?? rangeSpan;
+        const span = Math.min(maxSpan, Math.max(minFramesVisible, v.endFrame - v.startFrame));
+        const center = (v.startFrame + v.endFrame) / 2;
+        return { startFrame: center - span / 2, endFrame: center + span / 2 };
+    }, [minFramesVisible, maxFramesVisible, rangeSpan]);
+    const requestZoomToFit = useCallback((paddingFrames) => {
+        const p = paddingFrames ?? 0;
+        setView(clampView({ startFrame: startFrame - p, endFrame: endFrame + p }));
+    }, [setView, clampView, startFrame, endFrame]);
+    // Live reads for the imperative `zoomToSelection`, kept in refs so the
+    // callback (wired into the store handle below) has a stable identity.
+    const selectionRef = useLatest(selectionState);
+    const tracksRef = useLatest(tracks);
+    const requestZoomToSelection = useCallback(() => {
+        const sel = selectionRef.current;
+        if (sel.length === 0)
+            return;
+        // O(|selection|) walk: index tracks once, look up the keyframe per ref.
+        const tracksById = new Map(tracksRef.current.map(t => [t.id, t]));
+        let min = Infinity;
+        let max = -Infinity;
+        for (const ref of sel) {
+            const track = tracksById.get(ref.trackId);
+            if (!track)
+                continue;
+            const kf = track.keyframes.find(k => k.id === ref.keyframeId);
+            if (!kf)
+                continue;
+            if (kf.x < min)
+                min = kf.x;
+            if (kf.x > max)
+                max = kf.x;
+        }
+        if (!Number.isFinite(min) || !Number.isFinite(max))
+            return;
+        const pad = Math.max(1, (max - min) * 0.1);
+        setView(clampView({ startFrame: min - pad, endFrame: max + pad }));
+    }, [selectionRef, tracksRef, setView, clampView]);
+    const requestSetView = useCallback((v) => {
+        setView(clampView(v));
+    }, [setView, clampView]);
+    useLayoutEffect(() => {
+        store.configureHandle({
+            focus: () => bodyRef.current?.focus(),
+            getElement: () => bodyRef.current,
+            seek: seekCommit,
+            setPlaying,
+            setView: requestSetView,
+            zoomToFit: requestZoomToFit,
+            zoomToSelection: requestZoomToSelection,
+        });
+    }, [
+        store,
+        seekCommit,
+        setPlaying,
+        requestSetView,
+        requestZoomToFit,
+        requestZoomToSelection,
+    ]);
+    useImperativeHandle(ref, () => store.handle, [store]);
+    // ── Responsive sizing ──
+    useResizeObserver(bodyRef, entry => {
+        const { width, height: h } = entry.contentRect;
+        setSize(prev => prev.width === width && prev.height === h ? prev : { width, height: h });
+    });
+    // ── Vertical scroll ──
+    const rulerHeight = showRuler ? RULER_HEIGHT : 0;
+    const loopStripHeight = loopStrip ? LOOP_STRIP_HEIGHT : 0;
+    const chromeHeight = rulerHeight + loopStripHeight;
+    const maxScrollTop = Math.max(0, layout.contentHeight - (size.height - chromeHeight));
+    // Clamp the scroll offset when the scrollable area shrinks (content removed
+    // or viewport grown). Adjusting state during render is React's documented
+    // alternative to a layout effect here — it avoids an extra commit, and the
+    // guard makes it self-terminating.
+    if (scrollTop > maxScrollTop) {
+        setScrollTop(maxScrollTop);
+    }
+    const scrollBy = useCallback((deltaPixels) => {
+        setScrollTop(s => clamp(s + deltaPixels, 0, maxScrollTop));
+    }, [maxScrollTop]);
+    // ── Gestures ──
+    const { handlers, onWheel } = useTimelineGestures({
+        containerRef: bodyRef,
+        store,
+        view: viewState,
+        size,
+        tracks,
+        selection: selectionState,
+        frame: frameState,
+        startFrame,
+        endFrame,
+        trackHeight,
+        scrollTop,
+        rulerHeight,
+        loopStripHeight,
+        loopHandles,
+        snap,
+        editable,
+        allowAddKeyframe,
+        allowDeleteKeyframe,
+        showPlayhead,
+        rows: layout.rows,
+        trackTops: layout.trackTops,
+        expandedHeight: expandedTrackHeight,
+        groups: groupsState,
+        minFramesVisible,
+        maxFramesVisible,
+        loopRegion,
+        maxScrollTop,
+        seekLive,
+        seekCommit,
+        setSelection,
+        setTracks: setTracksLive,
+        commitTracks: commitTracks,
+        setView,
+        setLoop,
+        scrollBy,
+        setGroups,
+    });
+    // Native non-passive wheel listener (React onWheel is passive). Attach to
+    // both the track body and the left header column so vertical scrolling works
+    // when the cursor is over the track names too. `onWheel` is a stable
+    // `useCallback` (it reads live state through a ref), so this effect attaches
+    // once and never re-subscribes.
+    useEffect(() => {
+        const body = bodyRef.current;
+        const header = headerColumnRef.current;
+        body?.addEventListener('wheel', onWheel, { passive: false });
+        header?.addEventListener('wheel', onWheel, { passive: false });
+        return () => {
+            body?.removeEventListener('wheel', onWheel);
+            header?.removeEventListener('wheel', onWheel);
+        };
+    }, [onWheel]);
+    // ── Slots + draw ──
+    const slots = useMemo(() => categorizeChildren(children), [children]);
+    // Prop wins; the deprecated `<Timeline.TrackScale />` slot still works.
+    const trackScale = trackScaleProp ?? slots.trackScale ?? undefined;
+    useTimelineDraw({
+        canvasRef,
+        size,
+        view: viewState,
+        startFrame,
+        endFrame,
+        fps,
+        frame: frameState,
+        rows: layout.rows,
+        scrollTop,
+        rulerHeight,
+        loopStripHeight,
+        loopHandles,
+        showPlayhead,
+        selection: selectionState,
+        hover,
+        hoverPlayhead,
+        marquee: drag.marquee,
+        loopRegion,
+        loopHover: drag.kind === 'none' ? hoverLoop : null,
+        ...(backgroundColor !== undefined ? { backgroundColor } : {}),
+        ...(playheadColor !== undefined ? { playheadColor } : {}),
+        ...(trackScale ? { trackScale } : {}),
+        ...(renderOverlay ? { renderOverlay } : {}),
+        ...(formatTime ? { formatTime } : {}),
+    });
+    // ── Layout ──
+    // Announce the playhead on discrete moves (keyboard / click), but stay quiet
+    // during continuous scrub drags and playback so AT isn't flooded.
+    const liveMessage = drag.kind === 'none' && !playingState
+        ? `Playhead at frame ${Math.round(frameState)}`
+        : '';
+    const shellHeight = height !== undefined ? `${height}px` : responsive ? '100%' : '240px';
+    return (jsx(TimelineStoreContext.Provider, { value: store, children: jsxs("div", { className: cx(timelineShellStyle, className), "data-testid": testId, id: id, style: { height: shellHeight, ...style }, children: [slots.toolbar, jsxs("div", { className: timelineMainRowStyle, children: [jsx(TimelineTrackHeaders, { ref: headerColumnRef, rows: layout.rows, contentHeight: layout.contentHeight, tracks: tracks, rulerHeight: chromeHeight, scrollTop: scrollTop, width: trackHeaderWidth, selection: selectionState, editable: editable, renderTrackHeader: renderTrackHeader, onReorderTracks: handleReorderTracks, onToggleGroupCollapsed: handleToggleGroupCollapsed, onToggleTrackExpanded: handleToggleTrackExpanded }), jsxs("div", { ref: bodyRef, className: timelineBodyStyle, "data-dragging": drag.kind !== 'none' || undefined, "data-hover-target": drag.kind !== 'none'
+                                ? undefined
+                                : hoverPlayhead
+                                    ? 'playhead'
+                                    : hoverLoop === 'start' || hoverLoop === 'end'
+                                        ? 'loop-edge'
+                                        : hoverLoop === 'body'
+                                            ? 'loop-body'
+                                            : undefined, role: "group", "aria-label": ariaLabel, "aria-roledescription": "Timeline", 
+                            // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- focusable interactive canvas surface
+                            tabIndex: 0, onPointerDown: handlers.onPointerDown, onPointerMove: handlers.onPointerMove, onPointerUp: handlers.onPointerUp, onPointerCancel: handlers.onPointerCancel, onPointerLeave: handlers.onPointerLeave, onDoubleClick: handlers.onDoubleClick, onKeyDown: handlers.onKeyDown, children: [jsx("canvas", { ref: canvasRef, className: timelineCanvasStyle }), jsx("div", { className: timelineOverlayLayerStyle, children: slots.overlay }), jsx("div", { className: ariaLiveRegionStyle, "aria-live": "polite", role: "status", children: liveMessage })] })] }), slots.minimap
+                    ? React.cloneElement(slots.minimap, {
+                        setView: requestSetView,
+                    })
+                    : null, slots.footer] }) }));
+};
+Timeline.displayName = 'Timeline';
+
+export { Timeline };
+//# sourceMappingURL=Timeline.js.map

package/dist/esm/components/editor/Timeline/Timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeline.js","sources":["src/components/editor/Timeline/Timeline.tsx"],"sourcesContent":["'use client';\n\nimport React, {\n  useCallback,\n  useEffect,\n  useImperativeHandle,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from 'react';\n\nimport { useControlledState, useLatest, useResizeObserver } from '@/hooks';\nimport { cx } from '@/utils/cx';\n\nimport {\n  timelineShellStyle,\n  timelineBodyStyle,\n  timelineCanvasStyle,\n  timelineOverlayLayerStyle,\n  timelineMainRowStyle,\n  timelineToolbarStyle,\n  timelineFooterStyle,\n  ariaLiveRegionStyle,\n} from './Timeline.css';\nimport { TIMELINE_SLOT } from './Timeline.types';\nimport { TimelineStoreContext } from './TimelineContext';\nimport {\n  clamp,\n  nextFollowView,\n  resolveLoop,\n  snapFrame,\n} from './timelineCoords';\nimport { computeRows } from './timelineLayout';\nimport { TimelineStore } from './TimelineStore';\nimport { TimelineTrackHeaders } from './TimelineTrackHeaders';\nimport { useTimelineDraw } from './useTimelineDraw';\nimport { useTimelineGestures } from './useTimelineGestures';\nimport { useTimelinePlayback } from './useTimelinePlayback';\n\nimport type {\n  TimelineGroup,\n  TimelineLoop,\n  TimelineMinimapProps,\n  TimelineMode,\n  TimelineProps,\n  TimelineSelection,\n  TimelineSlotKind,\n  TimelineSlotMarker,\n  TimelineTrack,\n  TimelineTrackScaleProps,\n  TimelineView,\n} from './Timeline.types';\nimport type { ViewportSize } from '@/components/primitives/viewport';\n\nconst RULER_HEIGHT = 22;\nconst LOOP_STRIP_HEIGHT = 12;\n\ninterface CategorizedSlots {\n  toolbar: React.ReactNode;\n  footer: React.ReactNode;\n  minimap: React.ReactElement | null;\n  /** Deprecated: prefer the `trackScale` prop on `<Timeline>`. */\n  trackScale: TimelineTrackScaleProps | null;\n  overlay: React.ReactNode[];\n}\n\nfunction getSlotKind(el: React.ReactElement): TimelineSlotKind | null {\n  const marker = (el.type as Partial<TimelineSlotMarker>)[TIMELINE_SLOT];\n  return marker ?? null;\n}\n\nfunction categorizeChildren(children: React.ReactNode): CategorizedSlots {\n  const slots: CategorizedSlots = {\n    toolbar: null,\n    footer: null,\n    minimap: null,\n    trackScale: null,\n    overlay: [],\n  };\n  React.Children.forEach(children, child => {\n    if (!React.isValidElement(child)) {\n      if (child !== null && child !== undefined && child !== false) {\n        slots.overlay.push(child);\n      }\n      return;\n    }\n    const kind = getSlotKind(child);\n    const props = child.props as {\n      children?: React.ReactNode;\n      className?: string;\n      style?: React.CSSProperties;\n    };\n    if (kind === 'track-scale') {\n      slots.trackScale = child.props as TimelineTrackScaleProps;\n      return;\n    }\n    if (kind === 'toolbar') {\n      slots.toolbar = (\n        <div\n          className={cx(timelineToolbarStyle, props.className)}\n          style={props.style}\n        >\n          {props.children}\n        </div>\n      );\n    } else if (kind === 'footer') {\n      slots.footer = (\n        <div\n          className={cx(timelineFooterStyle, props.className)}\n          style={props.style}\n        >\n          {props.children}\n        </div>\n      );\n    } else if (kind === 'minimap') {\n      slots.minimap = child;\n    } else {\n      slots.overlay.push(child);\n    }\n  });\n  return slots;\n}\n\n/**\n * Horizontal multi-track animation timeline / dope sheet. Tracks hold\n * keyframes (the shared `CurveKeyframe` model) along a frame-based time axis;\n * a playhead scrubs across all tracks. Canvas-rendered keyframes with DOM\n * chrome, store-driven via `useSyncExternalStore`.\n *\n * Children read live state via `useTimelineContext()` / `useTimelineGeometry()`\n * / `useTimelinePlayhead()` / `useTimelineSelection()`.\n */\nexport const Timeline = (props: TimelineProps): React.ReactElement => {\n  const {\n    tracks,\n    onTracksChange,\n    onTracksChangeComplete,\n    startFrame = 0,\n    endFrame,\n    fps = 30,\n    frame,\n    defaultFrame,\n    onFrameChange,\n    onFrameChangeComplete,\n    view,\n    defaultView,\n    onViewChange,\n    minFramesVisible = 1,\n    maxFramesVisible,\n    selection,\n    defaultSelection,\n    onSelectionChange,\n    editable = true,\n    allowAddKeyframe = true,\n    allowDeleteKeyframe = true,\n    snap = true,\n    mode,\n    defaultMode,\n    onModeChange,\n    playing,\n    defaultPlaying,\n    onPlayingChange,\n    loop,\n    defaultLoop,\n    onLoopChange,\n    followMode = 'smooth',\n    loopStrip = false,\n    loopHandles = 'edges',\n    groups,\n    onGroupsChange,\n    trackHeight = 28,\n    expandedTrackHeight = 96,\n    groupHeaderHeight = 22,\n    showRuler = true,\n    showPlayhead = true,\n    trackHeaderWidth = 160,\n    responsive = true,\n    height,\n    playheadColor,\n    backgroundColor,\n    trackScale: trackScaleProp,\n    renderOverlay,\n    renderTrackHeader,\n    formatTime,\n    ariaLabel = 'Timeline',\n    className,\n    style,\n    testId,\n    id,\n    children,\n    ref,\n  } = props;\n\n  const bodyRef = useRef<HTMLDivElement>(null);\n  const canvasRef = useRef<HTMLCanvasElement>(null);\n  const headerColumnRef = useRef<HTMLDivElement>(null);\n\n  const [size, setSize] = useState<ViewportSize>({ width: 0, height: 0 });\n  const [scrollTop, setScrollTop] = useState(0);\n\n  const fullView = useMemo<TimelineView>(\n    () => ({ startFrame, endFrame }),\n    [startFrame, endFrame]\n  );\n\n  // ── Controlled / uncontrolled state ──\n\n  const [frameState, setFrame] = useControlledState<number>({\n    value: frame,\n    defaultValue: defaultFrame,\n    onChange: onFrameChange,\n    fallback: startFrame,\n  });\n  const [viewState, setView] = useControlledState<TimelineView>({\n    value: view,\n    defaultValue: defaultView,\n    onChange: onViewChange,\n    fallback: fullView,\n  });\n  const [selectionState, setSelection] = useControlledState<TimelineSelection>({\n    value: selection,\n    defaultValue: defaultSelection,\n    onChange: onSelectionChange,\n    fallback: [],\n  });\n  const [modeState] = useControlledState<TimelineMode>({\n    value: mode,\n    defaultValue: defaultMode,\n    onChange: onModeChange,\n    fallback: 'dope-sheet',\n  });\n  const [playingState, setPlaying] = useControlledState<boolean>({\n    value: playing,\n    defaultValue: defaultPlaying,\n    onChange: onPlayingChange,\n    fallback: false,\n  });\n  const [loopState, setLoop] = useControlledState<TimelineLoop>({\n    value: loop,\n    defaultValue: defaultLoop,\n    onChange: onLoopChange,\n    fallback: false,\n  });\n  const loopRegion = useMemo(\n    () => resolveLoop(loopState, startFrame, endFrame),\n    [loopState, startFrame, endFrame]\n  );\n\n  // ── Groups (controlled or uncontrolled) ──\n\n  const [internalGroups, setInternalGroups] = useState<\n    ReadonlyArray<TimelineGroup>\n  >(groups ?? []);\n  const groupsState = groups ?? internalGroups;\n  const setGroups = useCallback(\n    (next: TimelineGroup[]): void => {\n      if (groups === undefined) setInternalGroups(next);\n      onGroupsChange?.(next);\n    },\n    [groups, onGroupsChange]\n  );\n\n  // ── Row layout (variable heights: expanded lanes + group headers) ──\n\n  const layout = useMemo(\n    () =>\n      computeRows(tracks, {\n        trackHeight,\n        expandedHeight: expandedTrackHeight,\n        groupHeaderHeight,\n        globalGraph: modeState === 'graph',\n        groups: groupsState,\n      }),\n    [\n      tracks,\n      trackHeight,\n      expandedTrackHeight,\n      groupHeaderHeight,\n      modeState,\n      groupsState,\n    ]\n  );\n\n  // ── Store ──\n\n  const store = useMemo(() => new TimelineStore(), []);\n  const drag = useSyncExternalStore(store.subscribeDrag, store.getDrag);\n  const hover = useSyncExternalStore(store.subscribeHover, store.getHover);\n  const hoverPlayhead = useSyncExternalStore(\n    store.subscribeHoverPlayhead,\n    store.getHoverPlayhead\n  );\n  const hoverLoop = useSyncExternalStore(\n    store.subscribeHoverLoop,\n    store.getHoverLoop\n  );\n\n  useLayoutEffect(() => {\n    store.setGeometry({\n      view: viewState,\n      size,\n      trackHeight,\n      scrollTop,\n      startFrame,\n      endFrame,\n      fps,\n      mode: modeState,\n    });\n  }, [\n    store,\n    viewState,\n    size,\n    trackHeight,\n    scrollTop,\n    startFrame,\n    endFrame,\n    fps,\n    modeState,\n  ]);\n\n  useLayoutEffect(() => {\n    store.setPlayhead({ frame: frameState, playing: playingState });\n  }, [store, frameState, playingState]);\n\n  useLayoutEffect(() => {\n    store.setSelection(selectionState);\n  }, [store, selectionState]);\n\n  // ── Seek helpers (snap + clamp) ──\n\n  const applyFrame = useCallback(\n    (f: number): number => clamp(snapFrame(f, snap), startFrame, endFrame),\n    [snap, startFrame, endFrame]\n  );\n  const seekLive = useCallback(\n    (f: number): void => {\n      setFrame(applyFrame(f));\n    },\n    [setFrame, applyFrame]\n  );\n  // Consumer callbacks live behind refs so the handlers that fire them keep a\n  // stable identity even when the parent passes a fresh inline function every\n  // render (component-patterns.md rules #3 / #11).\n  const onFrameCompleteRef = useLatest(onFrameChangeComplete);\n  const seekCommit = useCallback(\n    (f: number): void => {\n      const v = applyFrame(f);\n      setFrame(v);\n      onFrameCompleteRef.current?.(v);\n    },\n    [setFrame, applyFrame, onFrameCompleteRef]\n  );\n\n  // ── Playback (optional built-in rAF loop) ──\n\n  const setFrameRaw = useCallback(\n    (f: number): void => {\n      setFrame(clamp(f, startFrame, endFrame));\n    },\n    [setFrame, startFrame, endFrame]\n  );\n  const handlePlaybackEnd = useCallback((): void => {\n    setPlaying(false);\n  }, [setPlaying]);\n  useTimelinePlayback({\n    playing: playingState,\n    frame: frameState,\n    fps,\n    startFrame,\n    endFrame,\n    loop: loopState,\n    onAdvance: setFrameRaw,\n    onEnd: handlePlaybackEnd,\n  });\n\n  // ── Follow-playhead during playback ──\n  // `smooth` keeps the playhead centred in the view — the view slides\n  // continuously once the playhead reaches the centre (one frame per tick,\n  // so visually smooth). `paged` waits until the playhead leaves the view\n  // and then jumps forward by a full span (After Effects vs Premiere style).\n  // `off` leaves the view alone.\n  useLayoutEffect(() => {\n    if (!playingState) return;\n    const next = nextFollowView(\n      followMode,\n      viewState,\n      frameState,\n      startFrame,\n      endFrame\n    );\n    if (next) setView(next);\n  }, [\n    playingState,\n    followMode,\n    frameState,\n    viewState,\n    setView,\n    startFrame,\n    endFrame,\n  ]);\n\n  // ── Track-edit helpers ──\n\n  // Track-change callbacks behind refs (same rationale as `seekCommit`): the\n  // gesture hook + header handlers stay stable while the parent may pass fresh\n  // inline `onTracksChange` / `onTracksChangeComplete` each render.\n  const onTracksChangeRef = useLatest(onTracksChange);\n  const onTracksChangeCompleteRef = useLatest(onTracksChangeComplete);\n  const setTracksLive = useCallback(\n    (t: TimelineTrack[]): void => {\n      onTracksChangeRef.current?.(t);\n    },\n    [onTracksChangeRef]\n  );\n  const commitTracks = useCallback(\n    (t: TimelineTrack[]): void => {\n      onTracksChangeCompleteRef.current?.(t);\n    },\n    [onTracksChangeCompleteRef]\n  );\n  const handleReorderTracks = useCallback(\n    (next: TimelineTrack[]): void => {\n      setTracksLive(next);\n      commitTracks(next);\n    },\n    [setTracksLive, commitTracks]\n  );\n  const handleToggleTrackExpanded = useCallback(\n    (trackId: string): void => {\n      const next = tracks.map(t =>\n        t.id === trackId ? { ...t, expanded: !t.expanded } : t\n      );\n      setTracksLive(next);\n      commitTracks(next);\n    },\n    [tracks, setTracksLive, commitTracks]\n  );\n  const handleToggleGroupCollapsed = useCallback(\n    (groupId: string): void => {\n      setGroups(\n        groupsState.map(g =>\n          g.id === groupId ? { ...g, collapsed: !g.collapsed } : g\n        )\n      );\n    },\n    [groupsState, setGroups]\n  );\n\n  // ── View helpers + imperative handle ──\n\n  const rangeSpan = Math.max(1, endFrame - startFrame);\n  const clampView = useCallback(\n    (v: TimelineView): TimelineView => {\n      const maxSpan = maxFramesVisible ?? rangeSpan;\n      const span = Math.min(\n        maxSpan,\n        Math.max(minFramesVisible, v.endFrame - v.startFrame)\n      );\n      const center = (v.startFrame + v.endFrame) / 2;\n      return { startFrame: center - span / 2, endFrame: center + span / 2 };\n    },\n    [minFramesVisible, maxFramesVisible, rangeSpan]\n  );\n\n  const requestZoomToFit = useCallback(\n    (paddingFrames?: number): void => {\n      const p = paddingFrames ?? 0;\n      setView(\n        clampView({ startFrame: startFrame - p, endFrame: endFrame + p })\n      );\n    },\n    [setView, clampView, startFrame, endFrame]\n  );\n\n  // Live reads for the imperative `zoomToSelection`, kept in refs so the\n  // callback (wired into the store handle below) has a stable identity.\n  const selectionRef = useLatest(selectionState);\n  const tracksRef = useLatest(tracks);\n  const requestZoomToSelection = useCallback((): void => {\n    const sel = selectionRef.current;\n    if (sel.length === 0) return;\n    // O(|selection|) walk: index tracks once, look up the keyframe per ref.\n    const tracksById = new Map(tracksRef.current.map(t => [t.id, t]));\n    let min = Infinity;\n    let max = -Infinity;\n    for (const ref of sel) {\n      const track = tracksById.get(ref.trackId);\n      if (!track) continue;\n      const kf = track.keyframes.find(k => k.id === ref.keyframeId);\n      if (!kf) continue;\n      if (kf.x < min) min = kf.x;\n      if (kf.x > max) max = kf.x;\n    }\n    if (!Number.isFinite(min) || !Number.isFinite(max)) return;\n    const pad = Math.max(1, (max - min) * 0.1);\n    setView(clampView({ startFrame: min - pad, endFrame: max + pad }));\n  }, [selectionRef, tracksRef, setView, clampView]);\n\n  const requestSetView = useCallback(\n    (v: TimelineView): void => {\n      setView(clampView(v));\n    },\n    [setView, clampView]\n  );\n\n  useLayoutEffect(() => {\n    store.configureHandle({\n      focus: () => bodyRef.current?.focus(),\n      getElement: () => bodyRef.current,\n      seek: seekCommit,\n      setPlaying,\n      setView: requestSetView,\n      zoomToFit: requestZoomToFit,\n      zoomToSelection: requestZoomToSelection,\n    });\n  }, [\n    store,\n    seekCommit,\n    setPlaying,\n    requestSetView,\n    requestZoomToFit,\n    requestZoomToSelection,\n  ]);\n\n  useImperativeHandle(ref, () => store.handle, [store]);\n\n  // ── Responsive sizing ──\n\n  useResizeObserver(bodyRef, entry => {\n    const { width, height: h } = entry.contentRect;\n    setSize(prev =>\n      prev.width === width && prev.height === h ? prev : { width, height: h }\n    );\n  });\n\n  // ── Vertical scroll ──\n\n  const rulerHeight = showRuler ? RULER_HEIGHT : 0;\n  const loopStripHeight = loopStrip ? LOOP_STRIP_HEIGHT : 0;\n  const chromeHeight = rulerHeight + loopStripHeight;\n  const maxScrollTop = Math.max(\n    0,\n    layout.contentHeight - (size.height - chromeHeight)\n  );\n\n  // Clamp the scroll offset when the scrollable area shrinks (content removed\n  // or viewport grown). Adjusting state during render is React's documented\n  // alternative to a layout effect here — it avoids an extra commit, and the\n  // guard makes it self-terminating.\n  if (scrollTop > maxScrollTop) {\n    setScrollTop(maxScrollTop);\n  }\n\n  const scrollBy = useCallback(\n    (deltaPixels: number): void => {\n      setScrollTop(s => clamp(s + deltaPixels, 0, maxScrollTop));\n    },\n    [maxScrollTop]\n  );\n\n  // ── Gestures ──\n\n  const { handlers, onWheel } = useTimelineGestures({\n    containerRef: bodyRef,\n    store,\n    view: viewState,\n    size,\n    tracks,\n    selection: selectionState,\n    frame: frameState,\n    startFrame,\n    endFrame,\n    trackHeight,\n    scrollTop,\n    rulerHeight,\n    loopStripHeight,\n    loopHandles,\n    snap,\n    editable,\n    allowAddKeyframe,\n    allowDeleteKeyframe,\n    showPlayhead,\n    rows: layout.rows,\n    trackTops: layout.trackTops,\n    expandedHeight: expandedTrackHeight,\n    groups: groupsState,\n    minFramesVisible,\n    maxFramesVisible,\n    loopRegion,\n    maxScrollTop,\n    seekLive,\n    seekCommit,\n    setSelection,\n    setTracks: setTracksLive,\n    commitTracks: commitTracks,\n    setView,\n    setLoop,\n    scrollBy,\n    setGroups,\n  });\n\n  // Native non-passive wheel listener (React onWheel is passive). Attach to\n  // both the track body and the left header column so vertical scrolling works\n  // when the cursor is over the track names too. `onWheel` is a stable\n  // `useCallback` (it reads live state through a ref), so this effect attaches\n  // once and never re-subscribes.\n  useEffect(() => {\n    const body = bodyRef.current;\n    const header = headerColumnRef.current;\n    body?.addEventListener('wheel', onWheel, { passive: false });\n    header?.addEventListener('wheel', onWheel, { passive: false });\n    return () => {\n      body?.removeEventListener('wheel', onWheel);\n      header?.removeEventListener('wheel', onWheel);\n    };\n  }, [onWheel]);\n\n  // ── Slots + draw ──\n\n  const slots = useMemo(() => categorizeChildren(children), [children]);\n  // Prop wins; the deprecated `<Timeline.TrackScale />` slot still works.\n  const trackScale = trackScaleProp ?? slots.trackScale ?? undefined;\n\n  useTimelineDraw({\n    canvasRef,\n    size,\n    view: viewState,\n    startFrame,\n    endFrame,\n    fps,\n    frame: frameState,\n    rows: layout.rows,\n    scrollTop,\n    rulerHeight,\n    loopStripHeight,\n    loopHandles,\n    showPlayhead,\n    selection: selectionState,\n    hover,\n    hoverPlayhead,\n    marquee: drag.marquee,\n    loopRegion,\n    loopHover: drag.kind === 'none' ? hoverLoop : null,\n    ...(backgroundColor !== undefined ? { backgroundColor } : {}),\n    ...(playheadColor !== undefined ? { playheadColor } : {}),\n    ...(trackScale ? { trackScale } : {}),\n    ...(renderOverlay ? { renderOverlay } : {}),\n    ...(formatTime ? { formatTime } : {}),\n  });\n\n  // ── Layout ──\n\n  // Announce the playhead on discrete moves (keyboard / click), but stay quiet\n  // during continuous scrub drags and playback so AT isn't flooded.\n  const liveMessage =\n    drag.kind === 'none' && !playingState\n      ? `Playhead at frame ${Math.round(frameState)}`\n      : '';\n\n  const shellHeight =\n    height !== undefined ? `${height}px` : responsive ? '100%' : '240px';\n\n  return (\n    <TimelineStoreContext.Provider value={store}>\n      <div\n        className={cx(timelineShellStyle, className)}\n        data-testid={testId}\n        id={id}\n        style={{ height: shellHeight, ...style }}\n      >\n        {slots.toolbar}\n        <div className={timelineMainRowStyle}>\n          <TimelineTrackHeaders\n            ref={headerColumnRef}\n            rows={layout.rows}\n            contentHeight={layout.contentHeight}\n            tracks={tracks}\n            rulerHeight={chromeHeight}\n            scrollTop={scrollTop}\n            width={trackHeaderWidth}\n            selection={selectionState}\n            editable={editable}\n            renderTrackHeader={renderTrackHeader}\n            onReorderTracks={handleReorderTracks}\n            onToggleGroupCollapsed={handleToggleGroupCollapsed}\n            onToggleTrackExpanded={handleToggleTrackExpanded}\n          />\n          {/* The timeline body is a labelled group that doubles as an\n              interactive canvas surface (focusable, with pointer + key\n              handlers driving the gesture model). */}\n          {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */}\n          <div\n            ref={bodyRef}\n            className={timelineBodyStyle}\n            data-dragging={drag.kind !== 'none' || undefined}\n            data-hover-target={\n              drag.kind !== 'none'\n                ? undefined\n                : hoverPlayhead\n                  ? 'playhead'\n                  : hoverLoop === 'start' || hoverLoop === 'end'\n                    ? 'loop-edge'\n                    : hoverLoop === 'body'\n                      ? 'loop-body'\n                      : undefined\n            }\n            role=\"group\"\n            aria-label={ariaLabel}\n            aria-roledescription=\"Timeline\"\n            // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- focusable interactive canvas surface\n            tabIndex={0}\n            onPointerDown={handlers.onPointerDown}\n            onPointerMove={handlers.onPointerMove}\n            onPointerUp={handlers.onPointerUp}\n            onPointerCancel={handlers.onPointerCancel}\n            onPointerLeave={handlers.onPointerLeave}\n            onDoubleClick={handlers.onDoubleClick}\n            onKeyDown={handlers.onKeyDown}\n          >\n            <canvas ref={canvasRef} className={timelineCanvasStyle} />\n            <div className={timelineOverlayLayerStyle}>{slots.overlay}</div>\n            <div\n              className={ariaLiveRegionStyle}\n              aria-live=\"polite\"\n              role=\"status\"\n            >\n              {liveMessage}\n            </div>\n          </div>\n        </div>\n        {slots.minimap\n          ? React.cloneElement(slots.minimap, {\n              setView: requestSetView,\n            } as Partial<TimelineMinimapProps>)\n          : null}\n        {slots.footer}\n      </div>\n    </TimelineStoreContext.Provider>\n  );\n};\n\nTimeline.displayName = 'Timeline';\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA;AACA;AAWA;;;AAGA;AAEA;AACE;AACE;AACA;AACA;AACA;AACA;;;;AAIE;AACE;;;;AAIJ;AACA;AAKA;AACE;;;AAGF;;;AASO;;;AASA;AACL;;;AAEA;;AAEJ;AACA;AACF;AAEA;;;;;;;;AAQG;AACI;AACL;AA4DA;AACA;AACA;AAEA;;;;AAUA;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;AACD;AACE;AACA;AACA;AACA;AACD;;;AAQD;AAGA;AACA;;;AAGI;AACF;;;;AAUI;;;AAGA;AACD;;;;;;;AAQF;;AAKH;AACA;AACA;AACA;AAIA;;;AAOI;;;;;;;AAOA;AACD;AACH;;;;;;;;;;AAUC;;AAGC;;;AAIA;AACF;;AAIA;AAIA;AAEI;AACF;;;;AAMF;AACA;AAEI;;AAEA;;;AAOJ;;;AAMA;;AAEA;AACA;AACE;AACA;;;;AAIA;AACA;AACA;AACD;;;;;;;;AASC;;AACA;AAOA;;AACF;;;;;;;;AAQC;;;;;AAOD;AACA;AACA;AAEI;AACF;AAGF;AAEI;AACF;AAGF;;;AAIE;AAGF;AAEI;;;;AAQJ;AAEI;AAKF;;AAMF;AACA;AAEI;;AAKA;AACA;;AAKJ;AAEI;AACA;;;;AASJ;AACA;AACA;AACE;AACA;;;;;AAIA;AACA;;AAEE;;;AAEA;;AACA;AAAgB;AAChB;AAAgB;;AAElB;;AACA;AACA;;AAGF;AAEI;AACF;;;;AAOE;AACA;;AAEA;AACA;AACA;AACD;AACH;;;;;;;AAOC;AAED;;AAIA;;AAEE;AAGF;;;;AAMA;;;;;;AAUA;;;AAIA;AAEI;AACF;;AAMF;AACE;;AAEA;;;AAGA;AACA;;;;;;;;;;;;;;;AAeA;AACA;;;;;;;;AAQA;AACA;;;;;AAKD;;;;;;;AAQC;AACA;AACA;AACA;AACA;AACE;AACA;AACF;AACF;;AAIA;;;AAIA;;;AAGE;;;;AAIA;;;;;;;AAOA;;;;;AAKA;AACA;AACA;AACA;AACA;AACA;AACD;;;;;;;;AAcD;AAmCc;AACA;AACE;AACA;AACE;;AAEE;;;AAOV;;AAsBE;;;AAOd;AAEA;;"}

package/dist/esm/components/editor/Timeline/Timeline.types.js

@@ -0,0 +1,10 @@
+// ─── Slot markers ───
+/**
+ * Symbol attached to `Timeline.Toolbar` / `.Footer` so the parent
+ * `<Timeline>` can identify slot children without relying on `displayName`
+ * (clobbered by `React.memo` / Vanilla Extract recipes).
+ */
+const TIMELINE_SLOT = Symbol.for('etui.timeline.slot');
+
+export { TIMELINE_SLOT };
+//# sourceMappingURL=Timeline.types.js.map

package/dist/esm/components/editor/Timeline/Timeline.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Timeline.types.js","sources":["src/components/editor/Timeline/Timeline.types.ts"],"sourcesContent":["import type { ViewportSize } from '@/components/primitives/viewport';\nimport type { BaseComponent } from '@/types/common';\nimport type { CurveData, CurveKeyframe } from '@/types/keyframe';\nimport type { Prettify } from '@/types/utilities';\nimport type React from 'react';\n\n// ─── Core model ───\n\n/** Dope sheet (keyframe timing) or graph editor (value curves). */\nexport type TimelineMode = 'dope-sheet' | 'graph';\n\n/** Pre/post-infinity behaviour, reused from the shared curve model. */\nexport type TimelineInfinity = {\n  pre?: CurveData['preInfinity'];\n  post?: CurveData['postInfinity'];\n};\n\n/**\n * One animated property. Keyframes use the shared `CurveKeyframe` model\n * (`x` = frame, `y` = value); graph mode assembles a `CurveData` per track\n * from `{ keyframes, domainX: [startFrame, endFrame], domainY: valueRange }`.\n */\nexport interface TimelineTrack {\n  id: string;\n  /** Display label in the header column. */\n  label?: string;\n  /** Keyframe / lane accent color (theme accent fallback). */\n  color?: string;\n  /** Keyframes — `x` is a frame, `y` is the value at that frame. */\n  keyframes: CurveKeyframe[];\n  /** Value range (graph-mode domainY). Auto-fit from keyframes when omitted. */\n  valueRange?: [number, number];\n  /** Pre/post-infinity behaviour for graph mode. */\n  infinity?: TimelineInfinity;\n  /** Visible but not editable. */\n  locked?: boolean;\n  /** Collapsed / not drawn. */\n  hidden?: boolean;\n  /** Expand this track into a graph (curve) lane regardless of the global mode. */\n  expanded?: boolean;\n  /** Group this track belongs to (matches a `TimelineGroup.id`). */\n  groupId?: string;\n  /** Row-height override (CSS px). */\n  height?: number;\n}\n\n/** A collapsible group of tracks (matched by `TimelineTrack.groupId`). */\nexport interface TimelineGroup {\n  id: string;\n  label?: string;\n  color?: string;\n  collapsed?: boolean;\n}\n\n/** A reference to one keyframe on one track. */\nexport interface TimelineKeyframeRef {\n  trackId: string;\n  keyframeId: string;\n}\n\n/** Current keyframe selection, flat across tracks. */\nexport type TimelineSelection = ReadonlyArray<TimelineKeyframeRef>;\n\n/** The visible frame window (zoom/pan over time). */\nexport interface TimelineView {\n  startFrame: number;\n  endFrame: number;\n}\n\n/** A loop sub-range, or `true` for the whole timeline range. */\nexport type TimelineLoop = boolean | { startFrame: number; endFrame: number };\n\n// ─── Render info ───\n\n/**\n * Helpers + current state passed to `renderOverlay`. Exposes the same\n * frame ↔ pixel math the built-in drawing uses, so consumer drawing stays\n * aligned with everything else.\n */\nexport interface TimelineDrawInfo {\n  /** Track-area size in CSS pixels (canvas already DPR-scaled). */\n  size: ViewportSize;\n  /** Visible frame window. */\n  view: TimelineView;\n  /** Global frame range. */\n  startFrame: number;\n  endFrame: number;\n  /** Frames per second. */\n  fps: number;\n  /** Current playhead frame. */\n  frame: number;\n  /** Map a frame to a track-area CSS-pixel X. */\n  frameToX: (frame: number) => number;\n  /** Inverse of `frameToX`. */\n  xToFrame: (x: number) => number;\n}\n\n/** State passed to the `renderTrackHeader` render prop. */\nexport interface TimelineTrackHeaderInfo {\n  /** Row index of the track. */\n  index: number;\n  /** Whether any of this track's keyframes are currently selected. */\n  hasSelection: boolean;\n}\n\n// ─── Slot markers ───\n\n/**\n * Symbol attached to `Timeline.Toolbar` / `.Footer` so the parent\n * `<Timeline>` can identify slot children without relying on `displayName`\n * (clobbered by `React.memo` / Vanilla Extract recipes).\n */\nexport const TIMELINE_SLOT: unique symbol = Symbol.for('etui.timeline.slot');\n\nexport type TimelineSlotKind = 'toolbar' | 'footer' | 'minimap' | 'track-scale';\n\nexport interface TimelineSlotMarker {\n  [TIMELINE_SLOT]: TimelineSlotKind;\n}\n\n// ─── Imperative handle ───\n\n/**\n * Imperative handle exposed via `ref` on `<Timeline>`. Stable for the\n * lifetime of the component.\n */\nexport interface TimelineHandle {\n  /** Focus the timeline body so keyboard navigation starts working. */\n  focus(): void;\n  /** Access the underlying body DOM element. */\n  getElement(): HTMLDivElement | null;\n  /** Move the playhead to a frame (snapped + clamped). */\n  seek(frame: number): void;\n  /** Start playback. */\n  play(): void;\n  /** Pause playback. */\n  pause(): void;\n  /** Toggle playback. */\n  toggle(): void;\n  /** Current playhead frame. */\n  getFrame(): number;\n  /** Fit the view to the whole frame range, with optional padding (frames). */\n  zoomToFit(paddingFrames?: number): void;\n  /** Fit the view to the current selection. No-op when nothing is selected. */\n  zoomToSelection(): void;\n  /** Current visible frame window. */\n  getView(): TimelineView;\n  /** Set the visible frame window (clamped to bounds + minFramesVisible). */\n  setView(view: TimelineView): void;\n  /** Map a frame to a track-area CSS-pixel X. */\n  frameToX(frame: number): number;\n  /** Inverse of `frameToX`. */\n  xToFrame(x: number): number;\n}\n\n// ─── Props ───\n\nexport interface TimelineBaseProps extends Omit<\n  BaseComponent,\n  'onChange' | 'ref'\n> {\n  /** Tracks rendered top-to-bottom. */\n  tracks: ReadonlyArray<TimelineTrack>;\n  /** Fires continuously during keyframe drag. */\n  onTracksChange?: (tracks: TimelineTrack[]) => void;\n  /** Fires once on commit (drag end, add, delete) — use for undo integration. */\n  onTracksChangeComplete?: (tracks: TimelineTrack[]) => void;\n\n  /** First frame of the global range. @default 0 */\n  startFrame?: number;\n  /** Last frame of the global range (the duration). */\n  endFrame: number;\n  /** Frames per second — drives timecode display + the snap grid. @default 30 */\n  fps?: number;\n\n  /** Playhead frame (controlled). */\n  frame?: number;\n  /** Initial playhead frame (uncontrolled). @default startFrame */\n  defaultFrame?: number;\n  /** Fires continuously while scrubbing. */\n  onFrameChange?: (frame: number) => void;\n  /** Fires once on scrub end. */\n  onFrameChangeComplete?: (frame: number) => void;\n\n  /** Visible frame window (controlled). */\n  view?: TimelineView;\n  /** Initial visible frame window (uncontrolled). @default whole range */\n  defaultView?: TimelineView;\n  /** Fires when the view zooms/pans. */\n  onViewChange?: (view: TimelineView) => void;\n  /** Minimum frames visible (max zoom-in). @default 1 */\n  minFramesVisible?: number;\n  /** Maximum frames visible (max zoom-out). @default range span */\n  maxFramesVisible?: number;\n\n  /** Keyframe selection (controlled). */\n  selection?: TimelineSelection;\n  /** Initial selection (uncontrolled). @default [] */\n  defaultSelection?: TimelineSelection;\n  /** Fires when the selection changes. */\n  onSelectionChange?: (selection: TimelineSelection) => void;\n\n  /** Master editing switch. @default true */\n  editable?: boolean;\n  /** Allow double-click to add keyframes. @default true */\n  allowAddKeyframe?: boolean;\n  /** Allow Delete/Backspace to remove keyframes. @default true */\n  allowDeleteKeyframe?: boolean;\n  /** Snap-to-frame: `true` = 1 frame, number = N-frame grid, `false` = off. @default true */\n  snap?: boolean | number;\n\n  /** Editor mode (controlled). */\n  mode?: TimelineMode;\n  /** Initial mode (uncontrolled). @default 'dope-sheet' */\n  defaultMode?: TimelineMode;\n  /** Fires when the mode toggles. */\n  onModeChange?: (mode: TimelineMode) => void;\n\n  /** Playback running (controlled). */\n  playing?: boolean;\n  /** Initial playback state (uncontrolled). @default false */\n  defaultPlaying?: boolean;\n  /** Fires when playback starts/stops. */\n  onPlayingChange?: (playing: boolean) => void;\n  /** Loop the whole range (`true`) or a sub-range (controlled). @default false */\n  loop?: TimelineLoop;\n  /** Initial loop (uncontrolled). */\n  defaultLoop?: TimelineLoop;\n  /** Fires when the loop region is dragged on the ruler. */\n  onLoopChange?: (loop: TimelineLoop) => void;\n  /**\n   * How the view tracks the playhead during playback.\n   * - `'smooth'` — keep the playhead centred in the view; the view slides\n   *   continuously once the playhead reaches the centre.\n   * - `'paged'` — leave the view still until the playhead leaves it, then\n   *   jump forward by one full view span.\n   * - `'off'` — never auto-scroll; user manages the view.\n   * @default 'smooth'\n   */\n  followMode?: 'smooth' | 'paged' | 'off';\n\n  /**\n   * Adds a thin dedicated **loop strip** directly under the time ruler. A\n   * plain drag on the strip creates / re-draws the loop region (no Alt\n   * needed); the strip also makes loop edges easier to grab. The main ruler\n   * keeps its scrub behaviour. @default false\n   */\n  loopStrip?: boolean;\n\n  /**\n   * Visual style for the loop region's edge markers.\n   * - `'edges'` — full-height vertical bars on each loop edge (default).\n   * - `'brackets'` — `[ ]` bracket markers in the chrome (ruler / loop\n   *   strip) with serifs at the top and bottom, no full-height bars. Bigger\n   *   pick targets, less visual noise across the track area.\n   * @default 'edges'\n   */\n  loopHandles?: 'edges' | 'brackets';\n\n  /** Track groups (collapsible). Tracks join a group via `groupId`. */\n  groups?: ReadonlyArray<TimelineGroup>;\n  /** Fires when a group is collapsed / expanded via its header. */\n  onGroupsChange?: (groups: TimelineGroup[]) => void;\n\n  /** Default row height in CSS px. @default 28 */\n  trackHeight?: number;\n  /** Row height for a graph-expanded track in CSS px. @default 96 */\n  expandedTrackHeight?: number;\n  /** Group header row height in CSS px. @default 22 */\n  groupHeaderHeight?: number;\n  /** Show the time ruler. @default true */\n  showRuler?: boolean;\n  /** Show the playhead. @default true */\n  showPlayhead?: boolean;\n  /** Width of the left track-header column in CSS px. @default 160 */\n  trackHeaderWidth?: number;\n  /** Fill the parent container (ResizeObserver). @default true */\n  responsive?: boolean;\n  /** Fixed height in CSS px (ignored when `responsive`). */\n  height?: number;\n\n  /** Playhead line color. Defaults to theme accent. */\n  playheadColor?: string;\n  /** Background color. Defaults to theme `--etui-color-bg-secondary`. */\n  backgroundColor?: string;\n\n  /**\n   * Per-track value scale on graph / expanded-track lanes (axis line + min/max\n   * labels, optional midpoint + gridlines). Omit to hide the scale entirely.\n   */\n  trackScale?: TimelineTrackScaleProps;\n\n  /** Custom canvas pass, drawn after built-in content, before the playhead. */\n  renderOverlay?: (\n    ctx: CanvasRenderingContext2D,\n    info: TimelineDrawInfo\n  ) => void;\n  /** Custom track-header renderer. Falls back to a built-in header. */\n  renderTrackHeader?: (\n    track: TimelineTrack,\n    info: TimelineTrackHeaderInfo\n  ) => React.ReactNode;\n  /** Ruler label formatter. Defaults to `HH:MM:SS:FF` timecode. */\n  formatTime?: (frame: number, fps: number) => string;\n\n  /** @default 'Timeline' */\n  ariaLabel?: string;\n\n  /**\n   * Slot children: `<Timeline.Toolbar>`, `<Timeline.Footer>`. Unrecognised\n   * children render as a free-form overlay layer.\n   */\n  children?: React.ReactNode;\n\n  /** Imperative handle. */\n  ref?: React.Ref<TimelineHandle>;\n}\n\nexport type TimelineProps = Prettify<TimelineBaseProps>;\n\n// ─── Subcomponent props ───\n\nexport interface TimelineToolbarProps {\n  children?: React.ReactNode;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\nexport interface TimelineFooterProps {\n  children?: React.ReactNode;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\nexport interface TimelineTrackScaleProps {\n  /**\n   * Which side of the lane the scale axis is drawn on.\n   * @default 'start'\n   */\n  position?: 'start' | 'end';\n  /**\n   * Custom value formatter. Receives the raw value and returns the label.\n   * @default `(v) => Number(v.toFixed(2)).toString()`\n   */\n  format?: (value: number) => string;\n  /**\n   * Draw a tick + label at the midpoint of the range too. @default false\n   */\n  showMidpoint?: boolean;\n  /**\n   * Draw thin horizontal gridlines across the whole lane width at each tick\n   * (`min` / `max`, plus midpoint when `showMidpoint` is on). @default false\n   */\n  gridlines?: boolean;\n  /**\n   * Lanes shorter than this (CSS px) skip the scale, so the labels never\n   * overlap into an unreadable blob on a short / collapsed graph lane.\n   * @default 48\n   */\n  minLaneHeight?: number;\n  /**\n   * Override the axis / label color. Defaults to the muted text colour.\n   */\n  color?: string;\n}\n\nexport interface TimelineMinimapProps {\n  /**\n   * Tracks to summarize as keyframe markers in the minimap.\n   * Pass the same array you pass to `<Timeline tracks={...} />`.\n   */\n  tracks: ReadonlyArray<TimelineTrack>;\n  /** Strip height in CSS px. @default 40 */\n  height?: number;\n  /** Override the keyframe marker color. */\n  markerColor?: string;\n  /** Override the viewport rectangle color. */\n  viewportColor?: string;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\n// ─── Context value ───\n\n/**\n * Live state available to children of a `<Timeline>` via\n * `useTimelineContext()`. Prefer the per-slice hooks for perf-conscious\n * consumers — each subscribes to a single slice.\n */\nexport interface TimelineContextValue {\n  view: TimelineView;\n  size: ViewportSize;\n  startFrame: number;\n  endFrame: number;\n  fps: number;\n  frame: number;\n  playing: boolean;\n  mode: TimelineMode;\n  selection: TimelineSelection;\n  frameToX: (frame: number) => number;\n  xToFrame: (x: number) => number;\n}\n"],"names":[],"mappings":"AAyGA;AAEA;;;;AAIG;AACI,MAAM,aAAa,GAAkB,MAAM,CAAC,GAAG,CAAC,oBAAoB;;;;"}

package/dist/esm/components/editor/Timeline/TimelineContext.js

@@ -0,0 +1,69 @@
+"use client";
+import { createContext, useSyncExternalStore, useContext, useMemo, useCallback } from 'react';
+import { selectedTangentMode, setSelectedTangentMode } from './timelineEdits.js';
+
+const TimelineStoreContext = createContext(null);
+function useTimelineStoreInternal() {
+    const store = useContext(TimelineStoreContext);
+    if (!store) {
+        throw new Error('useTimeline* hooks must be called inside a <Timeline> component');
+    }
+    return store;
+}
+/**
+ * Subscribe to **all** Timeline state. Convenient catch-all but re-renders on
+ * every store mutation. For perf-sensitive consumers, prefer the slice hooks
+ * (`useTimelineGeometry`, `useTimelinePlayhead`, `useTimelineSelection`).
+ */
+function useTimelineContext() {
+    const store = useTimelineStoreInternal();
+    return useSyncExternalStore(store.subscribe, store.getSnapshot);
+}
+/** Subscribe to the geometry slice (view / sizes / range / mode). */
+function useTimelineGeometry() {
+    const store = useTimelineStoreInternal();
+    return useSyncExternalStore(store.subscribeGeometry, store.getGeometry);
+}
+/** Subscribe to the playhead slice (frame / playing). */
+function useTimelinePlayhead() {
+    const store = useTimelineStoreInternal();
+    return useSyncExternalStore(store.subscribePlayhead, store.getPlayhead);
+}
+/** Subscribe to the selection slice. */
+function useTimelineSelection() {
+    const store = useTimelineStoreInternal();
+    return useSyncExternalStore(store.subscribeSelection, store.getSelection);
+}
+/**
+ * Convenience hook for building a tangent-mode toggle UI (the six modes:
+ * `auto` / `linear` / `step` / `aligned` / `mirrored` / `free`). Reads the
+ * current selection from the Timeline store, exposes the unified mode (or
+ * `'mixed'`), and applies a chosen mode to every selected keyframe via the
+ * caller's `onTracksChange`.
+ *
+ * @example
+ * ```tsx
+ * function TangentBar({ tracks, onTracksChange }) {
+ *   const t = useTimelineSelectedTangentMode(tracks, onTracksChange);
+ *   if (t.current === null) return null;
+ *   return (
+ *     <>
+ *       <button onClick={() => t.set('auto')} aria-pressed={t.current === 'auto'}>auto</button>
+ *       <button onClick={() => t.set('aligned')} aria-pressed={t.current === 'aligned'}>aligned</button>
+ *       …
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+function useTimelineSelectedTangentMode(tracks, onTracksChange) {
+    const selection = useTimelineSelection();
+    const current = useMemo(() => selectedTangentMode(tracks, selection), [tracks, selection]);
+    const set = useCallback((mode) => {
+        onTracksChange(setSelectedTangentMode(tracks, selection, mode));
+    }, [tracks, selection, onTracksChange]);
+    return { current, set };
+}
+
+export { TimelineStoreContext, useTimelineContext, useTimelineGeometry, useTimelinePlayhead, useTimelineSelectedTangentMode, useTimelineSelection };
+//# sourceMappingURL=TimelineContext.js.map

package/dist/esm/components/editor/Timeline/TimelineContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimelineContext.js","sources":["src/components/editor/Timeline/TimelineContext.ts"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useCallback,\n  useContext,\n  useMemo,\n  useSyncExternalStore,\n} from 'react';\n\nimport { selectedTangentMode, setSelectedTangentMode } from './timelineEdits';\n\nimport type {\n  TimelineContextValue,\n  TimelineSelection,\n  TimelineTrack,\n} from './Timeline.types';\nimport type {\n  TimelineGeometryState,\n  TimelinePlayheadState,\n  TimelineStore,\n} from './TimelineStore';\nimport type { TangentMode } from '@/types/keyframe';\n\nexport const TimelineStoreContext = createContext<TimelineStore | null>(null);\n\nfunction useTimelineStoreInternal(): TimelineStore {\n  const store = useContext(TimelineStoreContext);\n  if (!store) {\n    throw new Error(\n      'useTimeline* hooks must be called inside a <Timeline> component'\n    );\n  }\n  return store;\n}\n\n/**\n * Subscribe to **all** Timeline state. Convenient catch-all but re-renders on\n * every store mutation. For perf-sensitive consumers, prefer the slice hooks\n * (`useTimelineGeometry`, `useTimelinePlayhead`, `useTimelineSelection`).\n */\nexport function useTimelineContext(): TimelineContextValue {\n  const store = useTimelineStoreInternal();\n  return useSyncExternalStore(store.subscribe, store.getSnapshot);\n}\n\n/** Subscribe to the geometry slice (view / sizes / range / mode). */\nexport function useTimelineGeometry(): TimelineGeometryState {\n  const store = useTimelineStoreInternal();\n  return useSyncExternalStore(store.subscribeGeometry, store.getGeometry);\n}\n\n/** Subscribe to the playhead slice (frame / playing). */\nexport function useTimelinePlayhead(): TimelinePlayheadState {\n  const store = useTimelineStoreInternal();\n  return useSyncExternalStore(store.subscribePlayhead, store.getPlayhead);\n}\n\n/** Subscribe to the selection slice. */\nexport function useTimelineSelection(): TimelineSelection {\n  const store = useTimelineStoreInternal();\n  return useSyncExternalStore(store.subscribeSelection, store.getSelection);\n}\n\nexport interface TimelineSelectedTangentMode {\n  /**\n   * The tangent mode shared by all selected keyframes; `'mixed'` if they\n   * disagree; `null` when nothing applicable is selected.\n   */\n  current: TangentMode | 'mixed' | null;\n  /** Apply a tangent mode to every selected keyframe. */\n  set: (mode: TangentMode) => void;\n}\n\n/**\n * Convenience hook for building a tangent-mode toggle UI (the six modes:\n * `auto` / `linear` / `step` / `aligned` / `mirrored` / `free`). Reads the\n * current selection from the Timeline store, exposes the unified mode (or\n * `'mixed'`), and applies a chosen mode to every selected keyframe via the\n * caller's `onTracksChange`.\n *\n * @example\n * ```tsx\n * function TangentBar({ tracks, onTracksChange }) {\n *   const t = useTimelineSelectedTangentMode(tracks, onTracksChange);\n *   if (t.current === null) return null;\n *   return (\n *     <>\n *       <button onClick={() => t.set('auto')} aria-pressed={t.current === 'auto'}>auto</button>\n *       <button onClick={() => t.set('aligned')} aria-pressed={t.current === 'aligned'}>aligned</button>\n *       …\n *     </>\n *   );\n * }\n * ```\n */\nexport function useTimelineSelectedTangentMode(\n  tracks: ReadonlyArray<TimelineTrack>,\n  onTracksChange: (next: TimelineTrack[]) => void\n): TimelineSelectedTangentMode {\n  const selection = useTimelineSelection();\n  const current = useMemo(\n    () => selectedTangentMode(tracks, selection),\n    [tracks, selection]\n  );\n  const set = useCallback(\n    (mode: TangentMode): void => {\n      onTracksChange(setSelectedTangentMode(tracks, selection, mode));\n    },\n    [tracks, selection, onTracksChange]\n  );\n  return { current, set };\n}\n"],"names":[],"mappings":";;;;;AA0BA;AACE;;AAEE;;AAIF;AACF;AAEA;;;;AAIG;;AAED;;AAEF;AAEA;;AAEE;;AAEF;AAEA;;AAEE;;AAEF;AAEA;;AAEE;;AAEF;AAYA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG;AAIJ;;AAKA;;;AAMA;AACF;;"}

package/dist/esm/components/editor/Timeline/TimelineFooter.js

@@ -0,0 +1,16 @@
+import { TIMELINE_SLOT } from './Timeline.types.js';
+
+/**
+ * Footer strip rendered below the timeline body (status bar — selected
+ * keyframe info, current frame / timecode). Picked out of `<Timeline>`
+ * children by the `TIMELINE_SLOT` symbol — its position in the child tree
+ * does not affect placement.
+ */
+const TimelineFooterImpl = () => null;
+const TimelineFooter = Object.assign(TimelineFooterImpl, {
+    displayName: 'Timeline.Footer',
+    [TIMELINE_SLOT]: 'footer',
+});
+
+export { TimelineFooter };
+//# sourceMappingURL=TimelineFooter.js.map

package/dist/esm/components/editor/Timeline/TimelineFooter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimelineFooter.js","sources":["src/components/editor/Timeline/TimelineFooter.tsx"],"sourcesContent":["import { TIMELINE_SLOT } from './Timeline.types';\n\nimport type { TimelineFooterProps } from './Timeline.types';\n\n/**\n * Footer strip rendered below the timeline body (status bar — selected\n * keyframe info, current frame / timecode). Picked out of `<Timeline>`\n * children by the `TIMELINE_SLOT` symbol — its position in the child tree\n * does not affect placement.\n */\nconst TimelineFooterImpl: (props: TimelineFooterProps) => null = () => null;\n\nexport const TimelineFooter = Object.assign(TimelineFooterImpl, {\n  displayName: 'Timeline.Footer',\n  [TIMELINE_SLOT]: 'footer' as const,\n});\n"],"names":[],"mappings":";;AAIA;;;;;AAKG;AACH,MAAM,kBAAkB,GAAyC,MAAM,IAAI;MAE9D,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE;AAC9D,IAAA,WAAW,EAAE,iBAAiB;IAC9B,CAAC,aAAa,GAAG,QAAiB;AACnC,CAAA;;;;"}