Skip to content

Commit 3869327

Browse files
committed
feat(studio): expose timeline treegrid semantics
1 parent 61e5b35 commit 3869327

11 files changed

Lines changed: 246 additions & 86 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: 22 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 }),

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

Lines changed: 26 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,19 @@ 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+
// One stable id namespace per timeline instance links sticky headers to canvas lanes.
107104
const lanesIdPrefix = `timeline-lanes${useId().replaceAll(":", "")}`;
108105
const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
109106
const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
107+
const { logicalRows, logicalRowsByTrack } = useTimelineLogicalRows({
108+
tracks,
109+
displayTrackOrder,
110+
laneCounts,
111+
selectedElementId,
112+
selectedElementIds,
113+
expandedClipIds,
114+
gsapAnimations,
115+
});
110116
const toggleClipExpandedTracked = (key: string) => {
111117
const willExpand = !expandedClipIds.has(key);
112118
trackStudioKeyframeLaneExpand({ expanded: willExpand });
@@ -130,8 +136,10 @@ export function TimelineLanes({
130136
: [];
131137
return (
132138
<div
133-
role="list"
139+
role="treegrid"
134140
aria-label="Timeline tracks"
141+
aria-multiselectable="true"
142+
aria-rowcount={logicalRows.length}
135143
className={rowsVirtualized ? "absolute inset-0" : undefined}
136144
>
137145
{
@@ -140,6 +148,9 @@ export function TimelineLanes({
140148
const trackNum = displayTrackOrder[row];
141149
if (trackNum === undefined) return null;
142150
const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
151+
const trackLogicalRows = logicalRowsByTrack.get(trackNum) ?? [];
152+
const logicalRow = trackLogicalRows[0];
153+
if (!logicalRow) return null;
143154
const rowHeight = rowGeometry.getRowHeight(row);
144155
const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
145156
const renderElements = rowsVirtualized
@@ -156,19 +167,15 @@ export function TimelineLanes({
156167
draggedClip?.started === true && !trackOrder.includes(trackNum) && els.length === 0;
157168
// All lanes use the same uniform color — no alternating stripes.
158169
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.
170+
// Keep diamonds below the beat strip on the active/music track.
162171
const beatStripOnTrack =
163172
(beatAnalysis?.beatTimes?.length ?? 0) >= 2 &&
164173
(selectedElementId
165174
? els.some((e) => (e.key ?? e.id) === selectedElementId)
166175
: els.some(isMusicTrack));
167176
const isTrackHidden = els.length > 0 && els.every((element) => element.hidden === true);
168177
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.
178+
// Only the selected/most-keyframed clip owns expanded lanes on a shared track.
172179
const keyframeClip = resolveTrackKeyframeClip(
173180
els,
174181
laneCounts,
@@ -178,17 +185,15 @@ export function TimelineLanes({
178185
const keyframeClipKey = keyframeClip?.key ?? keyframeClip?.id;
179186
const keyframeClipExpanded =
180187
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`.
188+
// Link the sticky caret to the canvas lanes with a stable display-row id.
185189
const lanesId = `${lanesIdPrefix}-track-${row}`;
186190
return (
187191
<TimelineTrackRow
188192
key={rowKey}
189193
index={row}
190194
rowKey={rowKey}
191-
rowCount={displayTrackOrder.length}
195+
logicalRow={logicalRow}
196+
propertyRows={trackLogicalRows.slice(1)}
192197
top={rowGeometry.getRowTop(row)}
193198
height={rowHeight}
194199
virtualized={rowsVirtualized}
@@ -226,6 +231,7 @@ export function TimelineLanes({
226231
onSeek={onSeek}
227232
/>
228233
<div
234+
role="gridcell"
229235
style={{
230236
width: trackContentWidth,
231237
marginLeft: contentGutter, // room for a 0% diamond left of t=0
@@ -502,12 +508,8 @@ export function TimelineLanes({
502508
)}
503509
</TimelineClip>
504510
);
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.
511+
// Keep this shell mounted while collapsed so aria-controls stays valid
512+
// and multi-drag cannot remount the subtree mid-gesture.
511513
const propertyLanes = isTrackKeyframeClip && (
512514
<TimelinePropertyLanes
513515
key={`${clipKey}-property-lanes`}
@@ -544,10 +546,7 @@ export function TimelineLanes({
544546
suppressClickRef={suppressClickRef}
545547
/>
546548
);
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.
549+
// One keyed child prevents window shifts from remounting focused clips.
551550
if (!isPassenger) {
552551
return (
553552
<Fragment key={clipKey}>

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ 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
/**
@@ -223,6 +224,7 @@ export function TimelinePropertyLanes({
223224
{laneData.map(({ group, keyframesData }, laneIndex) => (
224225
<div
225226
key={group}
227+
id={timelineLogicalRowCellId(timelinePropertyRowId(elementId, group), "content")}
226228
role="group"
227229
aria-label={`${group} keyframes`}
228230
data-property-group={group}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
} from "./trackHeaderLaneState";
1717
import { valueReadout } from "./trackHeaderLaneValues";
1818
import { trackDisplaySuffix } from "./timelineTrackDisplay";
19+
import { timelineLogicalRowCellId, timelinePropertyRowId } from "./timelineNavigationIdentity";
1920

2021
interface TimelineTrackHeaderProps {
2122
/** The track's real key: a FRACTIONAL z-order sort value. Routes callbacks;
@@ -221,6 +222,10 @@ function PropertyGroupHeaderRow({
221222

222223
return (
223224
<div
225+
id={timelineLogicalRowCellId(
226+
timelinePropertyRowId(expandedElement.key ?? expandedElement.id, lane.group),
227+
"header",
228+
)}
224229
data-property-group={lane.group}
225230
data-timeline-lane-top={getTimelineLaneTop(laneIndex)}
226231
className="absolute left-0 flex items-center gap-1 overflow-hidden px-1.5 text-[10px] text-white/65"
@@ -314,6 +319,7 @@ export function TimelineTrackHeader({
314319

315320
return (
316321
<div
322+
role="rowheader"
317323
className={`sticky left-0 z-[12] shrink-0 ${
318324
!isKeyframeLayer
319325
? showTrackLabel
Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
import type { ReactNode } from "react";
2+
import { timelineLogicalRowCellId } from "./timelineNavigationIdentity";
3+
import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
24

35
interface TimelineTrackRowProps {
46
index: number;
57
rowKey: number;
6-
rowCount: number;
8+
logicalRow: TimelineLogicalRow;
9+
propertyRows: readonly TimelineLogicalRow[];
710
top: number;
811
height: number;
912
virtualized: boolean;
@@ -16,7 +19,8 @@ interface TimelineTrackRowProps {
1619
export function TimelineTrackRow({
1720
index,
1821
rowKey,
19-
rowCount,
22+
logicalRow,
23+
propertyRows,
2024
top,
2125
height,
2226
virtualized,
@@ -26,21 +30,52 @@ export function TimelineTrackRow({
2630
}: TimelineTrackRowProps) {
2731
return (
2832
<div
29-
role="listitem"
30-
aria-posinset={index + 1}
31-
aria-setsize={rowCount}
33+
role="rowgroup"
3234
data-index={index}
3335
data-timeline-row={index}
3436
data-timeline-row-key={rowKey}
35-
className={`${virtualized ? "absolute left-0 right-0" : "relative"} flex`}
37+
className={virtualized ? "absolute left-0 right-0" : "relative"}
3638
style={{
3739
top: virtualized ? top : undefined,
3840
height,
3941
background,
4042
borderBottom: `1px solid ${borderColor}`,
4143
}}
4244
>
43-
{children}
45+
<div
46+
role="row"
47+
aria-rowindex={logicalRow.logicalIndex + 1}
48+
aria-level={logicalRow.level}
49+
aria-expanded={logicalRow.expandable ? logicalRow.expanded : undefined}
50+
data-timeline-logical-row-id={logicalRow.id}
51+
className="flex"
52+
style={{ height }}
53+
>
54+
{children}
55+
</div>
56+
{propertyRows.map((row) => {
57+
const group = row.propertyGroup;
58+
const keyframeCount = row.items.filter((item) => item.kind === "keyframe").length;
59+
const easeCount = row.items.filter((item) => item.kind === "ease").length;
60+
return (
61+
<div
62+
key={row.id}
63+
role="row"
64+
aria-rowindex={row.logicalIndex + 1}
65+
aria-level={row.level}
66+
data-property-group={group}
67+
data-timeline-logical-row-id={row.id}
68+
className="sr-only"
69+
>
70+
<div role="rowheader" aria-owns={timelineLogicalRowCellId(row.id, "header")}>
71+
{group}
72+
</div>
73+
<div role="gridcell" aria-owns={timelineLogicalRowCellId(row.id, "content")}>
74+
{keyframeCount} keyframes, {easeCount} ease controls
75+
</div>
76+
</div>
77+
);
78+
})}
4479
</div>
4580
);
4681
}

0 commit comments

Comments
 (0)