Skip to content

Commit 0c5a3e1

Browse files
committed
feat(studio): expose timeline treegrid semantics
1 parent 2981a48 commit 0c5a3e1

13 files changed

Lines changed: 279 additions & 87 deletions

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

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -244,6 +244,25 @@ describe("Timeline provider boundary", () => {
244244
expect(propertyLane.style.background).toBe("");
245245
expect(propertyLane.style.border).toBe("");
246246
expect(propertyLane.style.borderRadius).toBe("");
247+
const treegrid = host.querySelector<HTMLElement>('[role="treegrid"]');
248+
const semanticRows = treegrid?.querySelectorAll<HTMLElement>('[role="row"]') ?? [];
249+
expect(treegrid?.getAttribute("aria-rowcount")).toBe("3");
250+
expect([...semanticRows].map((row) => row.getAttribute("aria-rowindex"))).toEqual([
251+
"1",
252+
"2",
253+
"3",
254+
]);
255+
expect(semanticRows[0]?.getAttribute("aria-level")).toBe("1");
256+
expect(semanticRows[0]?.getAttribute("aria-expanded")).toBe("true");
257+
expect(semanticRows[1]?.getAttribute("aria-level")).toBe("2");
258+
expect(semanticRows[1]?.textContent).toContain("position");
259+
expect(semanticRows[1]?.querySelector('[role="rowheader"]')?.getAttribute("aria-owns")).toBe(
260+
headerLane.id,
261+
);
262+
expect(semanticRows[1]?.querySelector('[role="gridcell"]')?.getAttribute("aria-owns")).toBe(
263+
propertyLane.id,
264+
);
265+
expect(semanticRows[2]?.hasAttribute("aria-expanded")).toBe(false);
247266
expect(trackHeader.style.width).toBe(`${LABEL_COL_W}px`);
248267
expect(rulerOrigin.style.width).toBe(`${LABEL_COL_W + GUTTER}px`);
249268
expect(playhead.style.left).toBe(`${LABEL_COL_W + GUTTER + 1000 - PLAYHEAD_HEAD_W / 2}px`);
@@ -295,12 +314,12 @@ describe("Timeline provider boundary", () => {
295314
const root = createRoot(host);
296315
act(() => root.render(React.createElement(Timeline)));
297316

298-
const list = host.querySelector<HTMLElement>('[role="list"]');
299-
const rows = list?.querySelectorAll('[role="listitem"]') ?? [];
317+
const treegrid = host.querySelector<HTMLElement>('[role="treegrid"]');
318+
const rows = treegrid?.querySelectorAll('[role="row"]') ?? [];
300319
expect(rows).toHaveLength(12);
301-
expect(rows[0]?.getAttribute("aria-posinset")).toBe("1");
302-
expect(rows[0]?.getAttribute("aria-setsize")).toBe("12");
303-
expect(rows[11]?.getAttribute("aria-posinset")).toBe("12");
320+
expect(treegrid?.getAttribute("aria-rowcount")).toBe("12");
321+
expect(rows[0]?.getAttribute("aria-rowindex")).toBe("1");
322+
expect(rows[11]?.getAttribute("aria-rowindex")).toBe("12");
304323

305324
act(() => root.unmount());
306325
});

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

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
132132

133133
const { host, root } = await mountTimeline(React.createElement(Timeline, { sessionEpoch: 2 }));
134134

135-
const rows = host.querySelectorAll('[role="listitem"]');
135+
const rows = host.querySelectorAll("[data-timeline-row]");
136136
expect(rows.length).toBeGreaterThan(0);
137137
expect(rows.length).toBeLessThanOrEqual(16);
138138

@@ -201,16 +201,15 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
201201

202202
await settleUntil(
203203
() =>
204-
(host.querySelector('[role="list"]')?.querySelectorAll('[role="listitem"]').length ?? 0) >
205-
0,
204+
(host.querySelector('[role="treegrid"]')?.querySelectorAll('[role="row"]').length ?? 0) > 0,
206205
);
207-
const list = host.querySelector<HTMLElement>('[role="list"]');
208-
const rows = list?.querySelectorAll('[role="listitem"]') ?? [];
206+
const treegrid = host.querySelector<HTMLElement>('[role="treegrid"]');
207+
const rows = treegrid?.querySelectorAll('[role="row"]') ?? [];
209208
expect(rows.length).toBeGreaterThan(0);
210209
expect(rows.length).toBeLessThanOrEqual(16);
211-
expect(rows[0]?.getAttribute("aria-posinset")).toBe("1");
212-
expect(rows[0]?.getAttribute("aria-setsize")).toBe("1000");
213-
expect(list?.parentElement?.style.height).toBe(
210+
expect(rows[0]?.getAttribute("aria-rowindex")).toBe("1");
211+
expect(treegrid?.getAttribute("aria-rowcount")).toBe("1000");
212+
expect(treegrid?.parentElement?.style.height).toBe(
214213
`${getTimelineCanvasHeight(Array.from({ length: 1_000 }, () => TRACK_H))}px`,
215214
);
216215

@@ -226,7 +225,7 @@ describe("Timeline row virtualization", { timeout: 30_000 }, () => {
226225
scroller.dispatchEvent(new Event("scroll"));
227226
});
228227
}
229-
expect(list?.querySelector('[data-timeline-row-key="0"]')).not.toBeNull();
228+
expect(treegrid?.querySelector('[data-timeline-row-key="0"]')).not.toBeNull();
230229
expect(document.activeElement).toBe(focusedControl);
231230

232231
act(() => root.unmount());

‎packages/studio/src/player/components/TimelineLanes.test.tsx‎

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,17 @@ afterEach(() => {
2626
const TRACK_A = 1 / 6;
2727
const TRACK_B = 0.5;
2828

29+
/** Every string a screen reader or a sighted user actually reads. */
30+
function visibleText(host: HTMLElement): string {
31+
return host.textContent ?? "";
32+
}
33+
34+
function ariaLabels(host: HTMLElement): string {
35+
return Array.from(host.querySelectorAll("[aria-label]"))
36+
.map((el) => el.getAttribute("aria-label") ?? "")
37+
.join(" ");
38+
}
39+
2940
function element(id: string, track: number): TimelineElement {
3041
return { id, label: id, tag: "div", start: 0, duration: 2, track };
3142
}
@@ -152,7 +163,11 @@ describe("TimelineLanes track numbering", () => {
152163

153164
expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
154165
expect(view.host.querySelectorAll("[data-timeline-row]")).toHaveLength(2);
155-
expect(view.host.innerHTML).not.toContain("0.16666666666666666");
166+
// Only what a user reads. The fractional key still identifies the row in
167+
// `id` / `data-` attributes, which is exactly where an opaque sort key
168+
// belongs.
169+
expect(visibleText(view.host)).not.toContain("0.16666666666666666");
170+
expect(ariaLabels(view.host)).not.toContain("0.16666666666666666");
156171
act(() => view.root.unmount());
157172
});
158173

@@ -179,11 +194,12 @@ describe("TimelineLanes track numbering", () => {
179194
onContextMenuLane,
180195
});
181196

182-
// Row children: [sticky header column, time-mapped track content]. The rows
183-
// sit inside the lanes list, which is what carries the virtualization
184-
// positioning context.
185-
const rows = Array.from(view.host.querySelectorAll('[role="listitem"]'));
186-
const secondTrackContent = rows[1]?.children.item(1);
197+
// The lane's own content cell: the track row's second child, after the
198+
// sticky header column.
199+
const secondTrackContent = view.host
200+
.querySelectorAll("[data-timeline-row]")[1]
201+
?.querySelector('[role="row"]')
202+
?.children.item(1);
187203
act(() => {
188204
secondTrackContent?.dispatchEvent(
189205
new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 100 }),
@@ -238,9 +254,25 @@ describe("TimelineLanes disclosure target", () => {
238254
);
239255
const firstIds = idsFor(first.host);
240256
const secondIds = idsFor(second.host);
257+
const cellIdsFor = (host: HTMLElement) =>
258+
new Set(
259+
Array.from(host.querySelectorAll<HTMLElement>("[data-property-group][id]"), (cell) =>
260+
cell.getAttribute("id"),
261+
).filter((id): id is string => id !== null),
262+
);
263+
const ownedIdsFor = (host: HTMLElement) =>
264+
Array.from(host.querySelectorAll("[aria-owns]"), (owner) =>
265+
owner.getAttribute("aria-owns"),
266+
).filter((id): id is string => id !== null);
267+
const firstCellIds = cellIdsFor(first.host);
268+
const secondCellIds = cellIdsFor(second.host);
241269

242270
expect(firstIds.length).toBeGreaterThan(0);
243271
expect(firstIds.some((id) => secondIds.includes(id))).toBe(false);
272+
expect(firstCellIds.size).toBeGreaterThan(0);
273+
expect([...firstCellIds].some((id) => secondCellIds.has(id))).toBe(false);
274+
expect(ownedIdsFor(first.host).every((id) => firstCellIds.has(id))).toBe(true);
275+
expect(ownedIdsFor(second.host).every((id) => secondCellIds.has(id))).toBe(true);
244276
// Still a legal CSS id selector: the aria-controls lookups above use `#id`.
245277
for (const id of [...firstIds, ...secondIds]) {
246278
expect(id).toMatch(/^[A-Za-z][\w-]*$/);

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

Lines changed: 28 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import { TimelineTrackRow } from "./TimelineTrackRow";
2727
import { isTimelineClipActive } from "./useTimelineActiveClips";
2828
import { queryTimelineClipIndex } from "../lib/timelineClipIndex";
2929
import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
30+
import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
3031

3132
interface TimelineLanesProps extends TimelineLaneBaseProps {
3233
/** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
@@ -99,14 +100,20 @@ export function TimelineLanes({
99100
onRazorSplit,
100101
onRazorSplitAll,
101102
}: TimelineLanesProps) {
102-
// Per-INSTANCE, so two timelines on one page (a mini-timeline in a modal
103-
// beside the main one) cannot both mint `...-track-0` and have every caret's
104-
// aria-controls resolve to whichever mounted first. React's useId embeds
105-
// colons, which are legal in an id and in aria-controls but need escaping in
106-
// a CSS `#id` selector, so they come out here and the prefix stays plain.
103+
// ponytail: One per-instance namespace prevents aria-controls and aria-owns
104+
// from resolving into a second timeline that renders the same logical rows.
107105
const lanesIdPrefix = `timeline-lanes${useId().replaceAll(":", "")}`;
108106
const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
109107
const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
108+
const { logicalRows, logicalRowsByTrack } = useTimelineLogicalRows({
109+
tracks,
110+
displayTrackOrder,
111+
laneCounts,
112+
selectedElementId,
113+
selectedElementIds,
114+
expandedClipIds,
115+
gsapAnimations,
116+
});
110117
const toggleClipExpandedTracked = (key: string) => {
111118
const willExpand = !expandedClipIds.has(key);
112119
trackStudioKeyframeLaneExpand({ expanded: willExpand });
@@ -130,8 +137,10 @@ export function TimelineLanes({
130137
: [];
131138
return (
132139
<div
133-
role="list"
140+
role="treegrid"
134141
aria-label="Timeline tracks"
142+
aria-multiselectable="true"
143+
aria-rowcount={logicalRows.length}
135144
className={rowsVirtualized ? "absolute inset-0" : undefined}
136145
>
137146
{
@@ -140,6 +149,9 @@ export function TimelineLanes({
140149
const trackNum = displayTrackOrder[row];
141150
if (trackNum === undefined) return null;
142151
const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
152+
const trackLogicalRows = logicalRowsByTrack.get(trackNum) ?? [];
153+
const logicalRow = trackLogicalRows[0];
154+
if (!logicalRow) return null;
143155
const rowHeight = rowGeometry.getRowHeight(row);
144156
const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
145157
const renderElements = rowsVirtualized
@@ -156,19 +168,15 @@ export function TimelineLanes({
156168
draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
157169
// All lanes use the same uniform color — no alternating stripes.
158170
const rowBackground = theme.rowBackground;
159-
// The beat-dot strip occupies the top of this track's lane (active track,
160-
// or the music track when nothing is selected). When shown, keyframe
161-
// diamonds shrink + drop to the bottom half so they don't collide with it.
171+
// Keep diamonds below the beat strip on the active/music track.
162172
const beatStripOnTrack =
163173
(beatAnalysis?.beatTimes?.length ?? 0) >= 2 &&
164174
(selectedElementId
165175
? els.some((e) => (e.key ?? e.id) === selectedElementId)
166176
: els.some(isMusicTrack));
167177
const isTrackHidden = els.length > 0 && els.every((element) => element.hidden === true);
168178
const isAudioTrack = els.length > 0 && els.some(isAudioTimelineElement);
169-
// The one keyframed element this track shows lanes for (selected, else
170-
// most lanes). A track can hold several elements; scoping to one keeps
171-
// their keyframes from cramming into a single row.
179+
// Only the selected/most-keyframed clip owns expanded lanes on a shared track.
172180
const keyframeClip = resolveTrackKeyframeClip(
173181
els,
174182
laneCounts,
@@ -178,17 +186,16 @@ export function TimelineLanes({
178186
const keyframeClipKey = keyframeClip?.key ?? keyframeClip?.id;
179187
const keyframeClipExpanded =
180188
keyframeClipKey != null && expandedClipIds.has(keyframeClipKey);
181-
// Minted here because this is the only place that sees BOTH ends of
182-
// the disclosure: the caret in the sticky header and the diamond lanes
183-
// on the canvas. Keyed by display row, not by `trackNum`, which is a
184-
// fractional sort key and would mint ids like `...-0.16666666666666666`.
189+
// Link the sticky caret to the canvas lanes with a stable display-row id.
185190
const lanesId = `${lanesIdPrefix}-track-${row}`;
186191
return (
187192
<TimelineTrackRow
188193
key={rowKey}
189194
index={row}
190195
rowKey={rowKey}
191-
rowCount={displayTrackOrder.length}
196+
logicalRow={logicalRow}
197+
propertyRows={trackLogicalRows.slice(1)}
198+
lanesId={lanesId}
192199
top={rowGeometry.getRowTop(row)}
193200
height={rowHeight}
194201
virtualized={rowsVirtualized}
@@ -226,6 +233,7 @@ export function TimelineLanes({
226233
onSeek={onSeek}
227234
/>
228235
<div
236+
role="gridcell"
229237
style={{
230238
width: trackContentWidth,
231239
marginLeft: contentGutter, // room for a 0% diamond left of t=0
@@ -502,12 +510,8 @@ export function TimelineLanes({
502510
)}
503511
</TimelineClip>
504512
);
505-
// Mounted for the track's keyframe clip in BOTH disclosure
506-
// states, so the header caret's aria-controls resolves while
507-
// collapsed too; collapsed just feeds it no animations, so
508-
// the wrapper renders empty. The key is stable across a
509-
// multi-drag: without it the passenger branch below remounts
510-
// this subtree and interrupts the gesture.
513+
// Keep this shell mounted while collapsed so aria-controls stays valid
514+
// and multi-drag cannot remount the subtree mid-gesture.
511515
const propertyLanes = isTrackKeyframeClip && (
512516
<TimelinePropertyLanes
513517
key={`${clipKey}-property-lanes`}
@@ -544,10 +548,7 @@ export function TimelineLanes({
544548
suppressClickRef={suppressClickRef}
545549
/>
546550
);
547-
// Keep one keyed top-level child per element. Returning an
548-
// array here makes React reconcile the outer array by
549-
// position, so a window shift remounts otherwise stable
550-
// clip keys and can tear down focus mid-reveal.
551+
// One keyed child prevents window shifts from remounting focused clips.
551552
if (!isPassenger) {
552553
return (
553554
<Fragment key={clipKey}>

‎packages/studio/src/player/components/TimelinePropertyLanes.test.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ function renderPropertyLanes(overrides: Partial<TimelinePropertyLanesProps> = {}
7070
act(() => {
7171
root.render(
7272
<TimelinePropertyLanes
73+
id="timeline-property-lanes-test"
7374
animations={[]}
7475
clipStart={0}
7576
clipDuration={1}
@@ -367,6 +368,7 @@ describe("TimelinePropertyLanes", () => {
367368
act(() => {
368369
root.render(
369370
<TimelinePropertyLanes
371+
id="timeline-property-lanes-selected-test"
370372
animations={animations}
371373
clipStart={0}
372374
clipDuration={1}
@@ -417,6 +419,7 @@ describe("TimelinePropertyLanes", () => {
417419
act(() => {
418420
root.render(
419421
<TimelinePropertyLanes
422+
id="timeline-property-lanes-unselected-test"
420423
animations={animations}
421424
clipStart={0}
422425
clipDuration={1}

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,15 @@ import { synthesizeFlatTweenKeyframes } from "../../hooks/gsapTweenSynth";
99
import { TimelineDiamondLane, type TimelineDiamondKeyframe } from "./TimelineClipDiamonds";
1010
import { LANE_H, getTimelineLaneTop } from "./timelineLayout";
1111
import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
12+
import { timelineLogicalRowCellId, timelinePropertyRowId } from "./timelineNavigationIdentity";
1213

1314
export interface TimelinePropertyLanesProps {
1415
/**
1516
* Id of the wrapper below, so the layer's disclosure caret can point
1617
* `aria-controls` at the lanes a sighted user sees it reveal. Minted by
1718
* TimelineLanes, which owns both this subtree and the caret's.
1819
*/
19-
id?: string;
20+
id: string;
2021
animations: readonly GsapAnimation[];
2122
clipStart: number;
2223
clipDuration: number;
@@ -223,6 +224,7 @@ export function TimelinePropertyLanes({
223224
{laneData.map(({ group, keyframesData }, laneIndex) => (
224225
<div
225226
key={group}
227+
id={timelineLogicalRowCellId(id, timelinePropertyRowId(elementId, group), "content")}
226228
role="group"
227229
aria-label={`${group} keyframes`}
228230
data-property-group={group}

‎packages/studio/src/player/components/TimelineTrackHeader.test.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,7 @@ describe("TimelineTrackHeader", () => {
379379
act(() => {
380380
lanesRoot.render(
381381
<TimelinePropertyLanes
382+
id="timeline-property-lanes-alignment-test"
382383
animations={animations}
383384
clipStart={0}
384385
clipDuration={2}

0 commit comments

Comments
 (0)