Skip to content

Commit 0641921

Browse files
feat(studio): expose composable timeline parts (#4229)
* feat(studio): expose composable timeline parts * refactor(studio): split timeline overlay parts * fix(studio): resolve timeline fallow findings * fix(studio): clarify timeline part contracts * style(studio): trim timeline drag comment
1 parent 952e922 commit 0641921

14 files changed

Lines changed: 570 additions & 272 deletions

‎packages/studio/src/contexts/TimelineEditContext.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ export function useTimelineEditContextOptional(): TimelineEditCallbacks {
2121
return useContext(TimelineEditContext) ?? {};
2222
}
2323

24+
export function useTimelineEditContextValue(): TimelineEditCallbacks | null {
25+
return useContext(TimelineEditContext);
26+
}
27+
2428
export function TimelineEditProvider({
2529
value,
2630
children,

‎packages/studio/src/index.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,22 @@ export type {
6060
TimelineElement,
6161
TimelineTimeRange,
6262
} from "./player";
63+
export {
64+
TimelineFrame,
65+
TimelineLanes,
66+
TimelineOverlays,
67+
TimelinePlayhead,
68+
TimelineRazorGuide,
69+
TimelineRuler,
70+
TimelineEmptyStatePart,
71+
TimelineEditPopover,
72+
TimelineClipMenu,
73+
TimelineGapMenu,
74+
TimelineKeyframeMenu,
75+
TimelineShortcutHint,
76+
} from "./player/components/TimelineParts";
77+
export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
78+
export type { TimelineTheme } from "./player/components/timelineTheme";
6379

6480
// Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
6581
export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

‎packages/studio/src/player/components/Timeline.test.ts‎

Lines changed: 22 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,26 @@ function renderBasicTimeline() {
135135
return { host, root };
136136
}
137137

138+
function renderSharedAutomationTimeline(selectedElementId?: string) {
139+
const host = createSizedTimelineHost(720);
140+
const automation = JSON.stringify({
141+
version: 1,
142+
lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
143+
});
144+
usePlayerStore.setState({
145+
duration: 8,
146+
timelineReady: true,
147+
...(selectedElementId ? { selectedElementId } : {}),
148+
elements: [
149+
{ id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
150+
{ id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
151+
],
152+
});
153+
const root = createRoot(host);
154+
act(() => root.render(React.createElement(Timeline)));
155+
return { host, root };
156+
}
157+
138158
describe("Timeline provider boundary", () => {
139159
it("keeps all-collapsed horizontal positions at the gutter plus the pre-t=0 pad", () => {
140160
usePlayerStore.setState({
@@ -621,21 +641,7 @@ describe("Timeline provider boundary", () => {
621641
// clip left the row's state depending on the selection, and a collapse that
622642
// only dropped the active clip left the row stuck open.
623643
it("expands and collapses every clip on a shared track together", () => {
624-
const host = createSizedTimelineHost(720);
625-
const automation = JSON.stringify({
626-
version: 1,
627-
lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
628-
});
629-
usePlayerStore.setState({
630-
duration: 8,
631-
timelineReady: true,
632-
elements: [
633-
{ id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
634-
{ id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
635-
],
636-
});
637-
const root = createRoot(host);
638-
act(() => root.render(React.createElement(Timeline)));
644+
const { host, root } = renderSharedAutomationTimeline();
639645

640646
const row = host.querySelector<HTMLElement>('[data-el-id="narration-1"]')?.parentElement
641647
?.parentElement;
@@ -668,22 +674,7 @@ describe("Timeline provider boundary", () => {
668674
// a lane to select its clip therefore made the handles vanish under the
669675
// pointer, which is the one gesture the read-only lane exists to support.
670676
it("keeps the automation lanes mounted when the selection moves along the row", () => {
671-
const host = createSizedTimelineHost(720);
672-
const automation = JSON.stringify({
673-
version: 1,
674-
lanes: [{ target: "volume", points: [{ t: 0, v: 1 }] }],
675-
});
676-
usePlayerStore.setState({
677-
duration: 8,
678-
timelineReady: true,
679-
selectedElementId: "narration-2",
680-
elements: [
681-
{ id: "narration-1", tag: "audio", start: 0, duration: 4, track: 0, automation },
682-
{ id: "narration-2", tag: "audio", start: 4, duration: 4, track: 0, automation },
683-
],
684-
});
685-
const root = createRoot(host);
686-
act(() => root.render(React.createElement(Timeline)));
677+
const { host, root } = renderSharedAutomationTimeline("narration-2");
687678
act(() => host.querySelector<HTMLButtonElement>('button[aria-label$=" lanes"]')?.click());
688679

689680
const before = [...host.querySelectorAll(".hf-automation-lane")];

‎packages/studio/src/player/components/Timeline.tsx‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,20 @@
11
import { memo } from "react";
22
import type { TimelineProps } from "./TimelineTypes";
3-
import { TimelineEmptyState } from "./TimelineEmptyState";
4-
import { TimelineCanvas } from "./TimelineCanvas";
5-
import { TimelineOverlays } from "./TimelineOverlays";
63
import { TimelineProvider, useTimelineContext } from "./TimelineProvider";
4+
import {
5+
TimelineEmptyStatePart,
6+
TimelineEditPopover,
7+
TimelineClipMenu,
8+
TimelineFrame,
9+
TimelineGapMenu,
10+
TimelineKeyframeMenu,
11+
TimelineLanes,
12+
TimelineOverlays,
13+
TimelinePlayhead,
14+
TimelineRazorGuide,
15+
TimelineRuler,
16+
TimelineShortcutHint,
17+
} from "./TimelineParts";
718

819
export * from "./TimelineProvider";
920
export {
@@ -28,23 +39,39 @@ function TimelineView() {
2839
const { state, meta } = useTimelineContext();
2940
const { timelineReady, elements } = state;
3041
if (!timelineReady || elements.length === 0) {
31-
return <TimelineEmptyState {...meta.emptyState} />;
42+
return <TimelineEmptyStatePart />;
3243
}
3344
return (
3445
<div {...meta.containerProps}>
3546
<div {...meta.viewportProps}>
36-
<TimelineCanvas />
37-
{meta.razorGuide}
47+
<TimelineFrame />
48+
<TimelineRazorGuide />
3849
</div>
3950
<TimelineOverlays />
4051
</div>
4152
);
4253
}
4354

44-
export const Timeline = memo(function Timeline(props: TimelineProps = {}) {
55+
const TimelineComposed = memo(function TimelineComposed(props: TimelineProps = {}) {
4556
return (
4657
<TimelineProvider {...props}>
4758
<TimelineView />
4859
</TimelineProvider>
4960
);
5061
});
62+
63+
export const Timeline = Object.assign(TimelineComposed, {
64+
Provider: TimelineProvider,
65+
Frame: TimelineFrame,
66+
Ruler: TimelineRuler,
67+
Lanes: TimelineLanes,
68+
Playhead: TimelinePlayhead,
69+
RazorGuide: TimelineRazorGuide,
70+
ShortcutHint: TimelineShortcutHint,
71+
EditPopover: TimelineEditPopover,
72+
ClipMenu: TimelineClipMenu,
73+
KeyframeMenu: TimelineKeyframeMenu,
74+
GapMenu: TimelineGapMenu,
75+
EmptyState: TimelineEmptyStatePart,
76+
Overlays: TimelineOverlays,
77+
});

‎packages/studio/src/player/components/TimelineCanvas.tsx‎

Lines changed: 10 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { memo } from "react";
2-
import { TimelineRuler } from "./TimelineRuler";
2+
import { TimelineRulerPart } from "./TimelineRulerPart";
33
import { PlayheadIndicator } from "./PlayheadIndicator";
44
import {
55
RULER_H,
@@ -12,12 +12,8 @@ import {
1212
getTimelineRowTop,
1313
getTimelineRowHeight,
1414
} from "./timelineLayout";
15-
import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
16-
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
1715
import { TimelineLanes } from "./TimelineLanes";
18-
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
1916
import { TimelineGestureOverlay } from "./TimelineGestureOverlay";
20-
import { resolveSnapGuide } from "./timelineSnapping";
2117
import { useTimelineContext } from "./TimelineProvider";
2218

2319
// A dropped clip's length is unknown until it lands; the preview shows a default.
@@ -26,8 +22,7 @@ const DROP_PREVIEW_SECONDS = 3;
2622
export const TimelineCanvas = memo(function TimelineCanvas() {
2723
const { state, actions } = useTimelineContext();
2824
const props = state.canvas;
29-
const { draggedClip, resizingClip, scrollRef, selectedElementIds, displayTrackOrder } = props;
30-
const snapGuide = resolveSnapGuide(draggedClip, resizingClip);
25+
const { draggedClip, scrollRef, displayTrackOrder } = props;
3126
const draggedRowIndex =
3227
draggedClip?.started === true ? displayTrackOrder.indexOf(draggedClip.previewTrack) : -1;
3328
const dropTrackIndex = props.dropPreview
@@ -43,55 +38,14 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
4338
// ghost and drop placeholder must clamp to it or they stretch to the full
4439
// expanded row height and stop matching the clip being dragged.
4540
const draggedClipHeight = Math.min(draggedRowHeight, TRACK_H) - CLIP_Y * 2;
46-
const {
47-
onResizeElement,
48-
onMoveElement,
49-
onToggleTrackHidden,
50-
onTogglePropertyGroupKeyframe,
51-
onRazorSplit,
52-
onRazorSplitAll,
53-
} = useTimelineEditContextOptional();
5441
const beatDragging = props.beatDragging;
55-
const draggedElement = draggedClip?.element ?? null;
56-
const draggedElementIdentity = draggedElement ? getTimelineElementIdentity(draggedElement) : null;
57-
// The drag ghost follows the cursor freely (both axes) — CapCut-style. The
58-
// "magnetic" affordance is a highlight on the destination lane (draggedRowIndex),
59-
// which flips at the MAGNETIC_TRACK_THRESHOLD point; the clip drops into it.
60-
// Live multi-selection drag: while a selected clip is dragged, ALL selected
61-
// clips move together as one rigid formation. The GRABBED clip is the free
62-
// ghost below; its co-selected "passengers" slide by the SAME group-clamped
63-
// delta (cheap translateX, no re-layout) — the delta is derived from the
64-
// grabbed clip's ALREADY-clamped previewStart, so the whole formation stops at
65-
// the wall together and never deforms. Matches what the commit will do — see
66-
// timelineMultiDragPreview + commit.
67-
const multiDragPreview: MultiDragPreviewInput | null =
68-
draggedClip?.started === true && draggedElement && draggedElementIdentity
69-
? {
70-
dragStarted: true,
71-
draggedKey: draggedElementIdentity,
72-
draggedOriginStart: draggedElement.start,
73-
draggedPreviewStart: draggedClip.previewStart,
74-
selectedKeys: selectedElementIds,
75-
}
76-
: null;
42+
const { draggedElement, snapGuide, multiDragPreview } = props;
7743
return (
7844
<div
7945
className="relative"
8046
style={{ height: props.totalH, width: props.contentOrigin + props.trackContentWidth }}
8147
>
82-
<TimelineRuler
83-
major={props.major}
84-
minor={props.minor}
85-
pps={props.pps}
86-
trackContentWidth={props.trackContentWidth}
87-
totalH={props.totalH}
88-
effectiveDuration={props.effectiveDuration}
89-
majorTickInterval={props.majorTickInterval}
90-
theme={props.theme}
91-
beatAnalysis={props.beatAnalysis}
92-
contentOrigin={props.contentOrigin}
93-
renderTimeRange={props.rowsVirtualized ? props.renderTimeRange : undefined}
94-
/>
48+
<TimelineRulerPart />
9549

9650
{/* Breathing room between the sticky ruler and the first track lane — the
9751
top half of the CapCut-style padding (see TRACKS_TOP_PAD). */}
@@ -104,12 +58,12 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
10458
snapGuide={snapGuide}
10559
draggedElement={draggedElement}
10660
multiDragPreview={multiDragPreview}
107-
onToggleTrackHidden={onToggleTrackHidden}
108-
onTogglePropertyGroupKeyframe={onTogglePropertyGroupKeyframe}
109-
onResizeElement={onResizeElement}
110-
onMoveElement={onMoveElement}
111-
onRazorSplit={onRazorSplit}
112-
onRazorSplitAll={onRazorSplitAll}
61+
onToggleTrackHidden={props.onToggleTrackHidden}
62+
onTogglePropertyGroupKeyframe={props.onTogglePropertyGroupKeyframe}
63+
onResizeElement={props.onResizeElement}
64+
onMoveElement={props.onMoveElement}
65+
onRazorSplit={props.onRazorSplit}
66+
onRazorSplitAll={props.onRazorSplitAll}
11367
/>
11468

11569
{/* Breathing room below the last track lane (~1.5 track heights) — a real

0 commit comments

Comments
 (0)