Skip to content

Commit 2981a48

Browse files
committed
feat(studio): model logical timeline navigation
1 parent 1be5a1f commit 2981a48

2 files changed

Lines changed: 590 additions & 0 deletions

File tree

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
2+
import { describe, expect, it } from "vitest";
3+
import type { TimelineElement } from "../store/playerStore";
4+
import {
5+
buildTimelineLogicalRows,
6+
resolveTimelineFocusFallback,
7+
resolveTimelineNavigationTarget,
8+
timelineClipFocusId,
9+
timelineTrackRowId,
10+
} from "./timelineKeyboardNavigation";
11+
12+
function clip(id: string, track: number, start: number, duration = 2): TimelineElement {
13+
return { id, track, start, duration, tag: "div" };
14+
}
15+
16+
function fallbackTracks(firstTrack: TimelineElement[]): [number, TimelineElement[]][] {
17+
return [
18+
[1, firstTrack],
19+
[2, []],
20+
[3, [clip("right", 3, 18), clip("left", 3, 2)]],
21+
];
22+
}
23+
24+
function animation(
25+
id: string,
26+
group: PropertyGroupName,
27+
percentages: readonly number[],
28+
resolvedStart = 10,
29+
): GsapAnimation {
30+
return {
31+
id,
32+
targetSelector: "#active",
33+
method: "to",
34+
position: 0,
35+
resolvedStart,
36+
duration: 10,
37+
properties: {},
38+
propertyGroup: group,
39+
keyframes: {
40+
format: "percentage",
41+
keyframes: percentages.map((percentage) => ({
42+
percentage,
43+
properties: group === "position" ? { x: percentage } : { opacity: percentage / 100 },
44+
})),
45+
},
46+
};
47+
}
48+
49+
function model(overrides: Partial<Parameters<typeof buildTimelineLogicalRows>[0]> = {}) {
50+
const active = clip("active", 1, 10, 10);
51+
return buildTimelineLogicalRows({
52+
tracks: [
53+
[1, [clip("late", 1, 20), active, clip("early", 1, 0)]],
54+
[2, []],
55+
[3, [clip("right", 3, 18), clip("left", 3, 2)]],
56+
],
57+
displayTrackOrder: [1, 2, 3],
58+
laneCounts: new Map([["active", 2]]),
59+
selectedElementId: "active",
60+
selectedElementIds: new Set(),
61+
expandedClipIds: new Set(["active"]),
62+
gsapAnimations: new Map([
63+
[
64+
"active",
65+
[animation("position", "position", [0, 50, 100]), animation("visual", "visual", [25, 75])],
66+
],
67+
]),
68+
...overrides,
69+
});
70+
}
71+
72+
describe("buildTimelineLogicalRows", () => {
73+
it("projects tracks, empty tracks, and expanded property rows with continuous indices", () => {
74+
const rows = model();
75+
76+
expect(
77+
rows.map(({ physicalTrackKey, logicalIndex, level, parentId }) => ({
78+
physicalTrackKey,
79+
logicalIndex,
80+
level,
81+
parentId,
82+
})),
83+
).toEqual([
84+
{ physicalTrackKey: 1, logicalIndex: 0, level: 1, parentId: null },
85+
{ physicalTrackKey: 1, logicalIndex: 1, level: 2, parentId: timelineTrackRowId(1) },
86+
{ physicalTrackKey: 1, logicalIndex: 2, level: 2, parentId: timelineTrackRowId(1) },
87+
{ physicalTrackKey: 2, logicalIndex: 3, level: 1, parentId: null },
88+
{ physicalTrackKey: 3, logicalIndex: 4, level: 1, parentId: null },
89+
]);
90+
expect(rows[0]?.expanded).toBe(true);
91+
expect(rows[3]?.items).toEqual([]);
92+
expect(rows[0]?.items.map((item) => item.elementId)).toEqual(["early", "active", "late"]);
93+
});
94+
95+
it("orders keyframes and their segment ease controls deterministically", () => {
96+
const rows = model({
97+
gsapAnimations: new Map([
98+
[
99+
"active",
100+
[
101+
animation("z-animation", "position", [100, 0, 50]),
102+
animation("a-animation", "position", [50]),
103+
],
104+
],
105+
]),
106+
});
107+
const position = rows.find((row) => row.propertyGroup === "position")!;
108+
109+
expect(
110+
position.items.map((item) => [item.kind, item.time, item.keyframeTarget?.animationId]),
111+
).toEqual([
112+
["keyframe", 10, "z-animation"],
113+
["ease", 12.5, "a-animation"],
114+
["keyframe", 15, "a-animation"],
115+
["keyframe", 15, "z-animation"],
116+
["ease", 17.5, "z-animation"],
117+
["keyframe", 20, "z-animation"],
118+
]);
119+
});
120+
121+
it("uses the selected keyframed clip as the sole expanded-lane owner", () => {
122+
const other = clip("other", 1, 0, 4);
123+
const rows = model({
124+
tracks: [[1, [other, clip("active", 1, 10, 10)]]],
125+
displayTrackOrder: [1],
126+
laneCounts: new Map([
127+
["active", 1],
128+
["other", 1],
129+
]),
130+
selectedElementId: "other",
131+
expandedClipIds: new Set(["other", "active"]),
132+
gsapAnimations: new Map([
133+
["active", [animation("active-position", "position", [0, 100])]],
134+
["other", [animation("other-visual", "visual", [0, 100], 0)]],
135+
]),
136+
});
137+
138+
expect(rows.map((row) => row.propertyGroup).filter(Boolean)).toEqual(["visual"]);
139+
});
140+
});
141+
142+
describe("resolveTimelineNavigationTarget", () => {
143+
it("navigates horizontal items plus row Home and End", () => {
144+
const rows = model();
145+
const activeId = timelineClipFocusId("active");
146+
147+
expect(resolveTimelineNavigationTarget(rows, activeId, "ArrowLeft")?.id).toBe(
148+
timelineClipFocusId("early"),
149+
);
150+
expect(resolveTimelineNavigationTarget(rows, activeId, "ArrowRight")?.id).toBe(
151+
timelineClipFocusId("late"),
152+
);
153+
expect(resolveTimelineNavigationTarget(rows, activeId, "Home")?.id).toBe(timelineTrackRowId(1));
154+
expect(resolveTimelineNavigationTarget(rows, timelineTrackRowId(1), "End")?.id).toBe(
155+
timelineClipFocusId("late"),
156+
);
157+
});
158+
159+
it("navigates every logical row including properties and empty tracks", () => {
160+
const rows = model();
161+
const activeId = timelineClipFocusId("active");
162+
const propertyTarget = resolveTimelineNavigationTarget(rows, activeId, "ArrowDown")!;
163+
164+
expect(propertyTarget.kind).toBe("keyframe");
165+
expect(propertyTarget.time).toBe(15);
166+
expect(
167+
resolveTimelineNavigationTarget(rows, propertyTarget.id, "PageDown", { pageSize: 2 })?.id,
168+
).toBe(timelineTrackRowId(2));
169+
expect(resolveTimelineNavigationTarget(rows, timelineTrackRowId(2), "ArrowDown")?.id).toBe(
170+
timelineTrackRowId(3),
171+
);
172+
});
173+
174+
it("uses a caller-supplied page size and ignores invalid page commands", () => {
175+
const rows = model();
176+
const current = timelineTrackRowId(1);
177+
178+
expect(resolveTimelineNavigationTarget(rows, current, "PageDown")?.id).toBe(current);
179+
expect(resolveTimelineNavigationTarget(rows, current, "PageDown", { pageSize: 3 })?.id).toBe(
180+
timelineTrackRowId(2),
181+
);
182+
});
183+
184+
it("supports modified Home and End across the whole logical model", () => {
185+
const rows = model();
186+
const current = timelineTrackRowId(2);
187+
188+
expect(
189+
resolveTimelineNavigationTarget(rows, current, "Home", { timelineBoundary: true })?.id,
190+
).toBe(timelineTrackRowId(1));
191+
expect(
192+
resolveTimelineNavigationTarget(rows, current, "End", { timelineBoundary: true })?.id,
193+
).toBe(timelineClipFocusId("right"));
194+
});
195+
196+
it("breaks equal-distance vertical ties by time then stable identity", () => {
197+
const rows = buildTimelineLogicalRows({
198+
tracks: [
199+
[1, [clip("current", 1, 9, 2)]],
200+
[2, [clip("later", 2, 14, 2), clip("earlier-z", 2, 4, 2), clip("earlier-a", 2, 4, 2)]],
201+
],
202+
displayTrackOrder: [1, 2],
203+
laneCounts: new Map(),
204+
selectedElementId: null,
205+
selectedElementIds: new Set(),
206+
expandedClipIds: new Set(),
207+
gsapAnimations: new Map(),
208+
});
209+
210+
expect(
211+
resolveTimelineNavigationTarget(rows, timelineClipFocusId("current"), "ArrowDown")?.id,
212+
).toBe(timelineClipFocusId("earlier-a"));
213+
});
214+
});
215+
216+
describe("resolveTimelineFocusFallback", () => {
217+
it("chooses previous, then next, then the containing row after deletion", () => {
218+
const before = model({ expandedClipIds: new Set() });
219+
const withoutActive = model({
220+
expandedClipIds: new Set(),
221+
tracks: fallbackTracks([clip("early", 1, 0), clip("late", 1, 20)]),
222+
});
223+
expect(
224+
resolveTimelineFocusFallback(before, withoutActive, timelineClipFocusId("active"))?.id,
225+
).toBe(timelineClipFocusId("early"));
226+
227+
const onlyNext = model({
228+
expandedClipIds: new Set(),
229+
tracks: fallbackTracks([clip("late", 1, 20)]),
230+
});
231+
expect(resolveTimelineFocusFallback(before, onlyNext, timelineClipFocusId("active"))?.id).toBe(
232+
timelineClipFocusId("late"),
233+
);
234+
235+
const onlyActive = model({
236+
expandedClipIds: new Set(),
237+
tracks: [[1, [clip("active", 1, 10, 10)]]],
238+
displayTrackOrder: [1],
239+
});
240+
const empty = model({
241+
expandedClipIds: new Set(),
242+
tracks: [[1, []]],
243+
displayTrackOrder: [1],
244+
});
245+
expect(resolveTimelineFocusFallback(onlyActive, empty, timelineClipFocusId("active"))?.id).toBe(
246+
timelineTrackRowId(1),
247+
);
248+
});
249+
250+
it("falls back from a collapsed property row to its parent track", () => {
251+
const before = model();
252+
const property = before.find((row) => row.propertyGroup === "position")!;
253+
const after = model({ expandedClipIds: new Set() });
254+
255+
expect(resolveTimelineFocusFallback(before, after, property.items[0]!.id)?.id).toBe(
256+
timelineTrackRowId(1),
257+
);
258+
});
259+
260+
it("returns null for an identity absent from the previous model", () => {
261+
expect(resolveTimelineFocusFallback(model(), model(), "missing")).toBeNull();
262+
});
263+
});

0 commit comments

Comments
 (0)