Skip to content

Commit 1faa0cb

Browse files
committed
fix(studio): announce real track numbers and point aria-controls at the lanes
The timeline's track key is a fractional z-order sort value, and the header built its visibility label straight from it, so screen readers announced "Hide track 0.16666666666666666". A track's 1-based display row is now passed alongside the key: the row number goes in every label, the key keeps routing every callback (visibility toggle, lane context menu). The same fix covers the `Track N` fallback used when a track holds no labelled element. The layer disclosure caret's aria-controls named a div in the sticky label column. That subtree is not empty, it holds the per-lane keyframe controls, but its children are all absolutely positioned so the div computes to 0x0, and the diamonds the caret visibly reveals live on the canvas instead. The caret expands two disjoint subtrees and was naming the less useful one. TimelinePropertyLanes now renders one static wrapper (static, not relative, so it establishes no containing block and the absolutely-positioned lanes keep resolving against the track-content div with identical geometry) and takes the id. TimelineLanes mints that id, since it is the only place that sees both ends of the disclosure, and mounts the wrapper for the track's keyframe clip in both disclosure states so the reference still resolves while collapsed. TimelineLaneBaseProps moves to its own module: it is the contract shared by TimelineCanvas and TimelineLanes, and lifting it out keeps TimelineLanes.tsx well under the 600-line cap instead of pushing past it.
1 parent f04cdb7 commit 1faa0cb

10 files changed

Lines changed: 524 additions & 127 deletions

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@ export function LayerDisclosureRow({
2222
/** Same adaptive width the lane rows use: a narrowed header column must not
2323
* leave this row hanging over the clips it labels. */
2424
columnWidth: number;
25-
/** Id of the element holding the lanes this row's caret expands. */
25+
/** Id of the CANVAS-side element holding the diamond lanes this row's caret
26+
* expands (see TimelinePropertyLanes). The caret also reveals the per-lane
27+
* control rows in this column, but the diamonds are what following the
28+
* reference should land on. */
2629
lanesId: string;
2730
onToggleClipExpanded: () => void;
2831
/** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -293,7 +293,9 @@ describe("Timeline provider boundary", () => {
293293
// mounted before we query it.
294294
act(() => {});
295295

296-
const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 0"]');
296+
// "1", not "0": the label carries the 1-based display row, while the
297+
// callback below still routes by the track's own key.
298+
const button = host.querySelector<HTMLButtonElement>('button[aria-label="Show track 1"]');
297299
expect(button).not.toBeNull();
298300
if (!button) throw new Error("Expected a track visibility toggle");
299301

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
2020
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
2121
import type { Rect } from "../../utils/marqueeGeometry";
2222
import { TimelineClip } from "./TimelineClip";
23-
import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
23+
import { TimelineLanes } from "./TimelineLanes";
24+
import type { TimelineLaneBaseProps } from "./timelineLaneProps";
2425
import { renderClipChildren } from "./timelineClipChildren";
2526
import { useTimelineRevealClip } from "./useTimelineRevealClip";
2627
import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
// @vitest-environment happy-dom
2+
3+
import React, { act, createRef } from "react";
4+
import { createRoot, type Root } from "react-dom/client";
5+
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
6+
import { afterEach, describe, expect, it, vi } from "vitest";
7+
import { TimelineLanes } from "./TimelineLanes";
8+
import { getTrackStyle } from "./timelineIcons";
9+
import { defaultTimelineTheme } from "./timelineTheme";
10+
import { TRACK_H } from "./timelineLayout";
11+
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
12+
import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
13+
import type { TimelineEditCallbacks } from "./timelineCallbacks";
14+
import type { DraggedClipState, BlockedClipState } from "./useTimelineClipDrag";
15+
16+
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
17+
18+
afterEach(() => {
19+
document.body.innerHTML = "";
20+
usePlayerStore.getState().reset();
21+
});
22+
23+
/** The z-order sort keys really are fractional: a clip nudged between two lanes
24+
* lands on the midpoint. These are the values that used to reach aria-label. */
25+
const TRACK_A = 1 / 6;
26+
const TRACK_B = 0.5;
27+
28+
function element(id: string, track: number): TimelineElement {
29+
return { id, label: id, tag: "div", start: 0, duration: 2, track };
30+
}
31+
32+
function positionTween(id: string): GsapAnimation {
33+
return {
34+
id: `${id}-tween`,
35+
targetSelector: `#${id}`,
36+
method: "to",
37+
position: 0,
38+
duration: 2,
39+
properties: {},
40+
propertyGroup: "position",
41+
keyframes: {
42+
format: "percentage",
43+
keyframes: [
44+
{ percentage: 0, properties: { x: 0 } },
45+
{ percentage: 100, properties: { x: 100 } },
46+
],
47+
},
48+
};
49+
}
50+
51+
interface RenderLanesOptions {
52+
elements?: TimelineElement[];
53+
animations?: Map<string, GsapAnimation[]>;
54+
expandedClipIds?: string[];
55+
selectedElementIds?: Set<string>;
56+
multiDragPreview?: MultiDragPreviewInput | null;
57+
draggedClip?: DraggedClipState | null;
58+
onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
59+
onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
60+
}
61+
62+
function renderLanes(options: RenderLanesOptions = {}): {
63+
host: HTMLDivElement;
64+
root: Root;
65+
rerender: (next: RenderLanesOptions) => void;
66+
} {
67+
const host = document.createElement("div");
68+
document.body.append(host);
69+
const root = createRoot(host);
70+
const render = (next: RenderLanesOptions) => {
71+
const elements = next.elements ?? [element("clip-a", TRACK_A)];
72+
const gsapAnimations = next.animations ?? new Map<string, GsapAnimation[]>();
73+
const displayTrackOrder = [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);
74+
const tracks: [number, TimelineElement[]][] = displayTrackOrder.map((track) => [
75+
track,
76+
elements.filter((el) => el.track === track),
77+
]);
78+
const laneCounts = new Map(
79+
elements.map((el) => [el.id, (gsapAnimations.get(el.id) ?? []).length]),
80+
);
81+
act(() => {
82+
usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
83+
root.render(
84+
<TimelineLanes
85+
pps={100}
86+
contentOrigin={232}
87+
contentGutter={32}
88+
trackContentWidth={800}
89+
theme={defaultTimelineTheme}
90+
displayTrackOrder={displayTrackOrder}
91+
rowHeights={displayTrackOrder.map(() => TRACK_H)}
92+
trackOrder={displayTrackOrder}
93+
tracks={tracks}
94+
trackStyles={new Map()}
95+
laneCounts={laneCounts}
96+
selectedElementId={null}
97+
selectedElementIds={next.selectedElementIds ?? new Set()}
98+
hoveredClip={null}
99+
draggedClip={next.draggedClip ?? null}
100+
draggedElement={null}
101+
multiDragPreview={next.multiDragPreview ?? null}
102+
blockedClipRef={createRef<BlockedClipState | null>()}
103+
suppressClickRef={{ current: false }}
104+
scrollRef={createRef<HTMLDivElement>()}
105+
setHoveredClip={vi.fn()}
106+
setShowPopover={vi.fn()}
107+
setRangeSelection={vi.fn()}
108+
setResizingClip={vi.fn()}
109+
setDraggedClip={vi.fn()}
110+
setSelectedElementId={vi.fn()}
111+
syncClipDragAutoScroll={vi.fn()}
112+
shiftClickClipRef={createRef()}
113+
getPreviewElement={(el) => el}
114+
getTrackStyle={getTrackStyle}
115+
gsapAnimations={gsapAnimations}
116+
selectedKeyframes={new Set()}
117+
currentTime={0}
118+
onContextMenuLane={next.onContextMenuLane}
119+
onToggleTrackHidden={next.onToggleTrackHidden}
120+
onTogglePropertyGroupKeyframe={vi.fn()}
121+
onResizeElement={vi.fn()}
122+
onMoveElement={vi.fn()}
123+
onRazorSplit={vi.fn()}
124+
onRazorSplitAll={vi.fn()}
125+
/>,
126+
);
127+
});
128+
};
129+
render(options);
130+
return { host, root, rerender: render };
131+
}
132+
133+
function visibilityLabels(host: HTMLElement): (string | null)[] {
134+
return Array.from(host.querySelectorAll("button[aria-label^='Hide track ']")).map((button) =>
135+
button.getAttribute("aria-label"),
136+
);
137+
}
138+
139+
describe("TimelineLanes track numbering", () => {
140+
// Screen readers literally announced "Hide track 0.16666666666666666".
141+
it("numbers tracks contiguously from 1 regardless of the fractional sort keys", () => {
142+
const view = renderLanes({
143+
elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
144+
});
145+
146+
expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
147+
expect(view.host.innerHTML).not.toContain("0.16666666666666666");
148+
act(() => view.root.unmount());
149+
});
150+
151+
it("hands the visibility toggle the real track key, not the display index", () => {
152+
const onToggleTrackHidden = vi.fn();
153+
const view = renderLanes({
154+
elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
155+
onToggleTrackHidden,
156+
});
157+
158+
const second = view.host.querySelector<HTMLButtonElement>('button[aria-label="Hide track 2"]');
159+
act(() => second?.click());
160+
161+
expect(onToggleTrackHidden).toHaveBeenCalledWith(TRACK_B, true);
162+
act(() => view.root.unmount());
163+
});
164+
165+
// The gap menu inserts at the track it is given, so a display index here would
166+
// drop the new clip on the wrong lane.
167+
it("hands the lane context menu the real track key, not the display index", () => {
168+
const onContextMenuLane = vi.fn();
169+
const view = renderLanes({
170+
elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
171+
onContextMenuLane,
172+
});
173+
174+
// Row children: [sticky header column, time-mapped track content].
175+
const rows = Array.from(view.host.children);
176+
const secondTrackContent = rows[1]?.children.item(1);
177+
act(() => {
178+
secondTrackContent?.dispatchEvent(
179+
new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 100 }),
180+
);
181+
});
182+
183+
expect(onContextMenuLane).toHaveBeenCalledOnce();
184+
expect(onContextMenuLane.mock.calls[0]?.[1]).toBe(TRACK_B);
185+
act(() => view.root.unmount());
186+
});
187+
});
188+
189+
describe("TimelineLanes disclosure target", () => {
190+
const ANIMATIONS = new Map([["clip-a", [positionTween("clip-a")]]]);
191+
192+
function ariaControlsTarget(host: HTMLElement): HTMLElement | null {
193+
const caret = host.querySelector("button[aria-controls]");
194+
const id = caret?.getAttribute("aria-controls");
195+
return id ? host.querySelector<HTMLElement>(`#${id}`) : null;
196+
}
197+
198+
// aria-controls used to name a div in the sticky label column: it computed to
199+
// 0x0 and held no diamonds at all.
200+
it("resolves the caret's aria-controls to an element holding the property lanes", () => {
201+
const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
202+
const target = ariaControlsTarget(view.host);
203+
204+
expect(target).not.toBeNull();
205+
expect(target?.querySelectorAll("[data-timeline-property-lane]").length).toBeGreaterThan(0);
206+
act(() => view.root.unmount());
207+
});
208+
209+
it("still resolves the caret's aria-controls while the layer is collapsed", () => {
210+
const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: [] });
211+
const target = ariaControlsTarget(view.host);
212+
213+
expect(target).not.toBeNull();
214+
expect(target?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0);
215+
act(() => view.root.unmount());
216+
});
217+
218+
// The passenger branch wraps [clip, lanes] in a transformed div that re-renders
219+
// on every pointer move. An unstable key there remounts the lanes and drops the
220+
// in-flight drag.
221+
it("does not remount the lanes while a multi-clip drag slides the formation", () => {
222+
const elements = [element("clip-a", TRACK_A), element("clip-b", TRACK_A)];
223+
const selectedElementIds = new Set(["clip-a", "clip-b"]);
224+
const preview = (draggedPreviewStart: number): MultiDragPreviewInput => ({
225+
dragStarted: true,
226+
draggedKey: "clip-b",
227+
draggedOriginStart: 0,
228+
draggedPreviewStart,
229+
selectedKeys: selectedElementIds,
230+
});
231+
const view = renderLanes({
232+
elements,
233+
animations: ANIMATIONS,
234+
expandedClipIds: ["clip-a"],
235+
selectedElementIds,
236+
multiDragPreview: preview(0.25),
237+
});
238+
239+
const before = ariaControlsTarget(view.host);
240+
const beforeLane = before?.querySelector("[data-timeline-property-lane]");
241+
expect(before).not.toBeNull();
242+
expect(beforeLane).not.toBeNull();
243+
244+
view.rerender({
245+
elements,
246+
animations: ANIMATIONS,
247+
expandedClipIds: ["clip-a"],
248+
selectedElementIds,
249+
multiDragPreview: preview(0.75),
250+
});
251+
252+
// Node identity, not just presence: a remount replaces these nodes.
253+
expect(ariaControlsTarget(view.host)).toBe(before);
254+
expect(before?.querySelector("[data-timeline-property-lane]")).toBe(beforeLane);
255+
act(() => view.root.unmount());
256+
});
257+
});

0 commit comments

Comments
 (0)