(
))}
diff --git a/packages/studio/src/player/components/TimelineTrackRow.tsx b/packages/studio/src/player/components/TimelineTrackRow.tsx
index de1865a41..d360edb20 100644
--- a/packages/studio/src/player/components/TimelineTrackRow.tsx
+++ b/packages/studio/src/player/components/TimelineTrackRow.tsx
@@ -1,14 +1,19 @@
import type { ReactNode } from "react";
+import { timelineLogicalRowCellId } from "./timelineNavigationIdentity";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
interface TimelineTrackRowProps {
index: number;
rowKey: number;
- rowCount: number;
+ logicalRow: TimelineLogicalRow;
+ propertyRows: readonly TimelineLogicalRow[];
+ lanesId: string;
top: number;
height: number;
virtualized: boolean;
background: string;
borderColor: string;
+ rovingTargetId?: string | null;
children: ReactNode;
}
@@ -16,23 +21,24 @@ interface TimelineTrackRowProps {
export function TimelineTrackRow({
index,
rowKey,
- rowCount,
+ logicalRow,
+ propertyRows,
+ lanesId,
top,
height,
virtualized,
background,
borderColor,
+ rovingTargetId = null,
children,
}: TimelineTrackRowProps) {
return (
- {children}
+
+ {children}
+
+ {propertyRows.map((row) => {
+ const group = row.propertyGroup;
+ const keyframeCount = row.items.filter((item) => item.kind === "keyframe").length;
+ const easeCount = row.items.filter((item) => item.kind === "ease").length;
+ return (
+ // ponytail: aria-owns maps this hidden logical row onto the two visible
+ // property-lane cells without duplicating interactive controls.
+
+
+ {group}
+
+
+ {keyframeCount} keyframes, {easeCount} ease controls
+
+
+ );
+ })}
);
}
diff --git a/packages/studio/src/player/components/timelineDiamondTypes.ts b/packages/studio/src/player/components/timelineDiamondTypes.ts
index f4a437830..78a40f485 100644
--- a/packages/studio/src/player/components/timelineDiamondTypes.ts
+++ b/packages/studio/src/player/components/timelineDiamondTypes.ts
@@ -29,7 +29,7 @@ export interface TimelineClipDiamondsProps {
keyframesData: KeyframeCacheEntry;
clipWidthPx: number;
clipHeightPx: number;
- /** Needed to compare the playhead to keyframes in output-frame time. */
+ /** Needed to compare the playhead to keyframes and voice their absolute time. */
clipDuration: number;
/** Beat-dot strip is shown on this track → shrink diamonds + drop them into
* the bottom half so they clear the strip at the top. */
@@ -38,7 +38,11 @@ export interface TimelineClipDiamondsProps {
isSelected: boolean;
currentPercentage: number;
elementId: string;
+ /** Absolute clip start, used only to voice a keyframe's time in its label. */
+ clipStart?: number;
selectedKeyframes: ReadonlySet
;
+ /** Focus id of the one timeline control currently in the tab order. */
+ rovingTargetId?: string | null;
onClickKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
onShiftClickKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget) => void;
onContextMenuKeyframe?: (
@@ -86,12 +90,15 @@ export interface TimelineDiamondLaneProps extends Omit<
}
export const DIAMOND_RATIO = 0.8;
-// Percentage tolerance for rendering keyframes near clip boundaries. Keyframes
-// slightly outside [0, 100] (from rounding or stale cache during the async
-// persist → reload cycle) are still rendered (the clip is overflow-visible) at
-// their true position rather than hidden.
-export const KF_MIN_PCT = -5;
-export const KF_MAX_PCT = 105;
+
+/** Absolute time of a keyframe, for the screen-reader label. */
+export function keyframeTimeLabel(
+ clipStart: number,
+ clipDuration: number,
+ percentage: number,
+): string {
+ return `${Number((clipStart + (clipDuration * percentage) / 100).toFixed(2))}s`;
+}
/**
* The full identity of a diamond, used by every callback and by the selection
diff --git a/packages/studio/src/player/components/timelineKeyboardNavigation.test.ts b/packages/studio/src/player/components/timelineKeyboardNavigation.test.ts
index 7495a6754..041f2a8f6 100644
--- a/packages/studio/src/player/components/timelineKeyboardNavigation.test.ts
+++ b/packages/studio/src/player/components/timelineKeyboardNavigation.test.ts
@@ -5,9 +5,8 @@ import {
buildTimelineLogicalRows,
resolveTimelineFocusFallback,
resolveTimelineNavigationTarget,
- timelineClipFocusId,
- timelineTrackRowId,
} from "./timelineKeyboardNavigation";
+import { timelineClipFocusId, timelineTrackRowId } from "./timelineNavigationIdentity";
function clip(id: string, track: number, start: number, duration = 2): TimelineElement {
return { id, track, start, duration, tag: "div" };
@@ -74,18 +73,31 @@ describe("buildTimelineLogicalRows", () => {
const rows = model();
expect(
- rows.map(({ physicalTrackKey, logicalIndex, level, parentId }) => ({
+ rows.map(({ physicalTrackKey, logicalIndex, level, parentId, expandable }) => ({
physicalTrackKey,
logicalIndex,
level,
parentId,
+ expandable,
})),
).toEqual([
- { physicalTrackKey: 1, logicalIndex: 0, level: 1, parentId: null },
- { physicalTrackKey: 1, logicalIndex: 1, level: 2, parentId: timelineTrackRowId(1) },
- { physicalTrackKey: 1, logicalIndex: 2, level: 2, parentId: timelineTrackRowId(1) },
- { physicalTrackKey: 2, logicalIndex: 3, level: 1, parentId: null },
- { physicalTrackKey: 3, logicalIndex: 4, level: 1, parentId: null },
+ { physicalTrackKey: 1, logicalIndex: 0, level: 1, parentId: null, expandable: true },
+ {
+ physicalTrackKey: 1,
+ logicalIndex: 1,
+ level: 2,
+ parentId: timelineTrackRowId(1),
+ expandable: false,
+ },
+ {
+ physicalTrackKey: 1,
+ logicalIndex: 2,
+ level: 2,
+ parentId: timelineTrackRowId(1),
+ expandable: false,
+ },
+ { physicalTrackKey: 2, logicalIndex: 3, level: 1, parentId: null, expandable: false },
+ { physicalTrackKey: 3, logicalIndex: 4, level: 1, parentId: null, expandable: false },
]);
expect(rows[0]?.expanded).toBe(true);
expect(rows[3]?.items).toEqual([]);
@@ -156,6 +168,12 @@ describe("resolveTimelineNavigationTarget", () => {
expect(
resolveTimelineNavigationTarget(rows, timelineClipFocusId("late"), "ArrowRight")?.id,
).toBe(timelineClipFocusId("late"));
+ expect(resolveTimelineNavigationTarget(rows, timelineTrackRowId(1), "ArrowRight")?.id).toBe(
+ timelineClipFocusId("early"),
+ );
+ expect(
+ resolveTimelineNavigationTarget(rows, timelineClipFocusId("early"), "ArrowLeft")?.id,
+ ).toBe(timelineTrackRowId(1));
expect(resolveTimelineNavigationTarget(rows, activeId, "Home")?.id).toBe(timelineTrackRowId(1));
expect(resolveTimelineNavigationTarget(rows, timelineTrackRowId(1), "End")?.id).toBe(
timelineClipFocusId("late"),
@@ -203,7 +221,16 @@ describe("resolveTimelineNavigationTarget", () => {
).toBe(timelineTrackRowId(1));
expect(
resolveTimelineNavigationTarget(rows, current, "End", { timelineBoundary: true })?.id,
- ).toBe(timelineClipFocusId("right"));
+ ).toBe(timelineTrackRowId(3));
+ });
+
+ it("returns from a property row to its parent with ArrowLeft", () => {
+ const rows = model();
+ const property = rows.find((row) => row.propertyGroup === "position")!;
+
+ expect(resolveTimelineNavigationTarget(rows, property.id, "ArrowLeft")?.id).toBe(
+ timelineTrackRowId(1),
+ );
});
it("breaks equal-distance vertical ties by time then stable identity", () => {
diff --git a/packages/studio/src/player/components/timelineKeyboardNavigation.ts b/packages/studio/src/player/components/timelineKeyboardNavigation.ts
index b4eac8f25..7ba14a824 100644
--- a/packages/studio/src/player/components/timelineKeyboardNavigation.ts
+++ b/packages/studio/src/player/components/timelineKeyboardNavigation.ts
@@ -5,6 +5,13 @@ import {
timelineKeyframeSelectionKey,
type TimelineKeyframeTarget,
} from "./timelineKeyframeIdentity";
+import {
+ timelineClipFocusId,
+ timelineEaseFocusId,
+ timelineKeyframeFocusId,
+ timelinePropertyRowId,
+ timelineTrackRowId,
+} from "./timelineNavigationIdentity";
import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
export type TimelineNavigationKey =
@@ -17,6 +24,21 @@ export type TimelineNavigationKey =
| "PageUp"
| "PageDown";
+const NAVIGATION_KEYS: ReadonlySet = new Set([
+ "ArrowLeft",
+ "ArrowRight",
+ "ArrowUp",
+ "ArrowDown",
+ "Home",
+ "End",
+ "PageUp",
+ "PageDown",
+]);
+
+export function isTimelineNavigationKey(key: string): key is TimelineNavigationKey {
+ return NAVIGATION_KEYS.has(key);
+}
+
export interface TimelineLogicalItem {
id: string;
kind: "clip" | "keyframe" | "ease";
@@ -34,6 +56,8 @@ export interface TimelineLogicalRow {
logicalIndex: number;
level: 1 | 2;
parentId: string | null;
+ elementId: string | null;
+ expandable: boolean;
expanded: boolean;
propertyGroup?: PropertyGroupName;
items: readonly TimelineLogicalItem[];
@@ -58,31 +82,6 @@ export interface TimelineNavigationOptions {
timelineBoundary?: boolean;
}
-function stableId(kind: string, ...parts: Array): string {
- // Attribute-safe by construction; callers embedding it in CSS selectors must use CSS.escape.
- return JSON.stringify(["timeline", kind, ...parts]);
-}
-
-export function timelineTrackRowId(track: number): string {
- return stableId("track", track);
-}
-
-function timelinePropertyRowId(elementId: string, group: PropertyGroupName): string {
- return stableId("property", elementId, group);
-}
-
-export function timelineClipFocusId(elementId: string): string {
- return stableId("clip", elementId);
-}
-
-function timelineKeyframeFocusId(elementId: string, target: TimelineKeyframeTarget): string {
- return stableId("keyframe", timelineKeyframeSelectionKey(elementId, target));
-}
-
-function timelineEaseFocusId(elementId: string, target: TimelineKeyframeTarget): string {
- return stableId("ease", timelineKeyframeSelectionKey(elementId, target));
-}
-
function elementId(element: TimelineElement): string {
return element.key ?? element.id;
}
@@ -205,6 +204,8 @@ export function buildTimelineLogicalRows({
logicalIndex: rows.length,
level: 1,
parentId: null,
+ elementId: activeId,
+ expandable: lanes.length > 0,
expanded,
items: clipItems(trackId, elements),
});
@@ -218,6 +219,8 @@ export function buildTimelineLogicalRows({
logicalIndex: rows.length,
level: 2,
parentId: trackId,
+ elementId: activeId,
+ expandable: false,
expanded: false,
propertyGroup: lane.group,
items: propertyItems(rowId, activeClip, lane.keyframes),
@@ -227,7 +230,7 @@ export function buildTimelineLogicalRows({
return rows;
}
-function locateTarget(rows: readonly TimelineLogicalRow[], id: string) {
+export function locateTimelineLogicalTarget(rows: readonly TimelineLogicalRow[], id: string) {
for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
const row = rows[rowIndex]!;
if (row.id === id) return { row, rowIndex, itemIndex: -1, target: row };
@@ -261,17 +264,21 @@ export function resolveTimelineNavigationTarget(
key: TimelineNavigationKey,
options: TimelineNavigationOptions = {},
): TimelineLogicalTarget | null {
- const current = locateTarget(rows, currentId);
+ const current = locateTimelineLogicalTarget(rows, currentId);
if (!current) return null;
const { row, rowIndex, itemIndex, target } = current;
if (key === "Home" || key === "End") {
const boundaryRow = options.timelineBoundary ? (key === "Home" ? rows[0] : rows.at(-1)) : row;
if (!boundaryRow) return target;
+ if (options.timelineBoundary) return boundaryRow;
return key === "Home" ? boundaryRow : (boundaryRow.items.at(-1) ?? boundaryRow);
}
if (key === "ArrowLeft") {
- if (itemIndex < 0) return row;
+ if (itemIndex < 0) {
+ if (!row.parentId) return row;
+ return locateTimelineLogicalTarget(rows, row.parentId)?.target ?? row;
+ }
return itemIndex === 0 ? row : row.items[itemIndex - 1]!;
}
if (key === "ArrowRight") {
@@ -304,26 +311,26 @@ export function resolveTimelineFocusFallback(
nextRows: readonly TimelineLogicalRow[],
currentId: string,
): TimelineLogicalTarget | null {
- const unchanged = locateTarget(nextRows, currentId);
+ const unchanged = locateTimelineLogicalTarget(nextRows, currentId);
if (unchanged) return unchanged.target;
- const previous = locateTarget(previousRows, currentId);
+ const previous = locateTimelineLogicalTarget(previousRows, currentId);
if (!previous) return null;
if (previous.itemIndex >= 0) {
for (let index = previous.itemIndex - 1; index >= 0; index -= 1) {
- const candidate = locateTarget(nextRows, previous.row.items[index]!.id);
+ const candidate = locateTimelineLogicalTarget(nextRows, previous.row.items[index]!.id);
if (candidate) return candidate.target;
}
for (let index = previous.itemIndex + 1; index < previous.row.items.length; index += 1) {
- const candidate = locateTarget(nextRows, previous.row.items[index]!.id);
+ const candidate = locateTimelineLogicalTarget(nextRows, previous.row.items[index]!.id);
if (candidate) return candidate.target;
}
}
- const survivingRow = locateTarget(nextRows, previous.row.id);
+ const survivingRow = locateTimelineLogicalTarget(nextRows, previous.row.id);
if (survivingRow) return survivingRow.target;
if (previous.row.parentId) {
- const parent = locateTarget(nextRows, previous.row.parentId);
+ const parent = locateTimelineLogicalTarget(nextRows, previous.row.parentId);
if (parent) return parent.target;
}
return nextRows[previous.rowIndex] ?? nextRows[previous.rowIndex - 1] ?? null;
diff --git a/packages/studio/src/player/components/timelineLaneProps.ts b/packages/studio/src/player/components/timelineLaneProps.ts
index b16a03b3b..e6c192526 100644
--- a/packages/studio/src/player/components/timelineLaneProps.ts
+++ b/packages/studio/src/player/components/timelineLaneProps.ts
@@ -9,6 +9,7 @@ import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./us
import type { TimelineClipIndex, TimelineTimeRange } from "../lib/timelineClipIndex";
import type { TimelineRowGeometry } from "./timelineLayout";
import type { TimelineVirtualRow } from "./useTimelineVirtualRows";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
/**
* Props shared by the scroll container ({@link import("./TimelineCanvas")}) and
@@ -27,6 +28,8 @@ export interface TimelineLaneBaseProps {
rowHeights: readonly number[];
rowGeometry: TimelineRowGeometry;
virtualRows: readonly TimelineVirtualRow[];
+ logicalRows: readonly TimelineLogicalRow[];
+ focusedTargetId: string | null;
rowsVirtualized: boolean;
clipIndex: TimelineClipIndex;
renderTimeRange: TimelineTimeRange;
diff --git a/packages/studio/src/player/components/timelineNavigationIdentity.ts b/packages/studio/src/player/components/timelineNavigationIdentity.ts
new file mode 100644
index 000000000..2641190b7
--- /dev/null
+++ b/packages/studio/src/player/components/timelineNavigationIdentity.ts
@@ -0,0 +1,38 @@
+import type { PropertyGroupName } from "@hyperframes/core/gsap-parser";
+import {
+ timelineKeyframeSelectionKey,
+ type TimelineKeyframeTarget,
+} from "./timelineKeyframeIdentity";
+
+function stableId(kind: string, ...parts: Array): string {
+ // Attribute-safe by construction; callers embedding it in CSS selectors must use CSS.escape.
+ return JSON.stringify(["timeline", kind, ...parts]);
+}
+
+export function timelineTrackRowId(track: number): string {
+ return stableId("track", track);
+}
+
+export function timelinePropertyRowId(elementId: string, group: PropertyGroupName): string {
+ return stableId("property", elementId, group);
+}
+
+export function timelineLogicalRowCellId(
+ lanesId: string,
+ rowId: string,
+ cell: "header" | "content",
+): string {
+ return `${lanesId}-${stableId("cell", rowId, cell)}`;
+}
+
+export function timelineClipFocusId(elementId: string): string {
+ return stableId("clip", elementId);
+}
+
+export function timelineKeyframeFocusId(elementId: string, target: TimelineKeyframeTarget): string {
+ return stableId("keyframe", timelineKeyframeSelectionKey(elementId, target));
+}
+
+export function timelineEaseFocusId(elementId: string, target: TimelineKeyframeTarget): string {
+ return stableId("ease", timelineKeyframeSelectionKey(elementId, target));
+}
diff --git a/packages/studio/src/player/components/useTimelineClipRenderWindow.ts b/packages/studio/src/player/components/useTimelineClipRenderWindow.ts
index e5bf746f5..f48941a40 100644
--- a/packages/studio/src/player/components/useTimelineClipRenderWindow.ts
+++ b/packages/studio/src/player/components/useTimelineClipRenderWindow.ts
@@ -1,10 +1,7 @@
-import { useMemo, type RefObject } from "react";
+import { useMemo } from "react";
import { createTimelineClipIndex } from "../lib/timelineClipIndex";
-import type { TimelineElement } from "../store/playerStore";
import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
-import type { TimelineRowGeometry } from "./timelineLayout";
import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
-import { useTimelineRevealClip } from "./useTimelineRevealClip";
interface UseTimelineClipRenderWindowInput {
tracks: Parameters[0];
@@ -15,17 +12,10 @@ interface UseTimelineClipRenderWindowInput {
selectedElementId?: string;
draggedElementId?: string;
resizingElementIds?: readonly string[];
- revealElementId?: string;
+ focusedElementId?: string;
focusedEaseElementId?: string;
clipContextMenuElementId?: string;
keyframeContextMenuElementId?: string;
- focusedElementId?: string;
- scrollRef: RefObject;
- elements: readonly TimelineElement[];
- rowGeometry: TimelineRowGeometry;
- allowHorizontalReveal: boolean;
- rowVirtualizationActive: boolean;
- sessionEpoch: number;
}
export function useTimelineClipRenderWindow({
@@ -37,17 +27,10 @@ export function useTimelineClipRenderWindow({
selectedElementId,
draggedElementId,
resizingElementIds,
- revealElementId,
+ focusedElementId,
focusedEaseElementId,
clipContextMenuElementId,
keyframeContextMenuElementId,
- focusedElementId,
- scrollRef,
- elements,
- rowGeometry,
- allowHorizontalReveal,
- rowVirtualizationActive,
- sessionEpoch,
}: UseTimelineClipRenderWindowInput) {
const clipIndex = useMemo(() => createTimelineClipIndex(tracks), [tracks]);
const renderTimeRange = useMemo(
@@ -61,11 +44,10 @@ export function useTimelineClipRenderWindow({
selectedElementId,
draggedElementId,
...(resizingElementIds ?? []),
- revealElementId,
+ focusedElementId,
focusedEaseElementId,
clipContextMenuElementId,
keyframeContextMenuElementId,
- focusedElementId,
].filter((identity): identity is string => identity !== undefined),
),
[
@@ -75,21 +57,8 @@ export function useTimelineClipRenderWindow({
focusedElementId,
keyframeContextMenuElementId,
resizingElementIds,
- revealElementId,
selectedElementId,
],
);
- useTimelineRevealClip({
- scrollRef,
- elements,
- rowGeometry,
- pixelsPerSecond,
- contentOrigin,
- allowHorizontal: allowHorizontalReveal,
- deferFocusUntilViewportUpdate: rowVirtualizationActive,
- focusedElementId,
- viewportVersion: viewport,
- sessionEpoch,
- });
return { clipIndex, renderTimeRange, pinnedClipIdentities };
}
diff --git a/packages/studio/src/player/components/useTimelineFocusCoordinator.test.tsx b/packages/studio/src/player/components/useTimelineFocusCoordinator.test.tsx
new file mode 100644
index 000000000..32439881c
--- /dev/null
+++ b/packages/studio/src/player/components/useTimelineFocusCoordinator.test.tsx
@@ -0,0 +1,174 @@
+// @vitest-environment happy-dom
+
+import React, { act, useMemo, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { timelineClipFocusId, timelineTrackRowId } from "./timelineNavigationIdentity";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const element = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+const elements = [element];
+const syncScrollViewport = () => {};
+const clipId = timelineClipFocusId("hero");
+const rowId = timelineTrackRowId(1);
+const rows: readonly TimelineLogicalRow[] = [
+ {
+ id: rowId,
+ kind: "row",
+ physicalTrackKey: 1,
+ logicalIndex: 0,
+ level: 1,
+ parentId: null,
+ elementId: null,
+ expandable: false,
+ expanded: false,
+ items: [{ id: clipId, kind: "clip", rowId, elementId: "hero", time: 21 }],
+ },
+];
+
+function Harness({
+ mountedId,
+ logicalRows = rows,
+ projectId = "project-a",
+}: {
+ mountedId?: string;
+ logicalRows?: readonly TimelineLogicalRow[];
+ projectId?: string;
+}) {
+ const scrollRef = useRef(null);
+ const rowGeometry = useMemo(() => {
+ const rowKeys = [...new Set(logicalRows.map((row) => row.physicalTrackKey))];
+ return createTimelineRowGeometry(
+ rowKeys,
+ rowKeys.map(() => 48),
+ );
+ }, [logicalRows]);
+ const focus = useTimelineFocusCoordinator({
+ scrollRef,
+ logicalRows,
+ elements,
+ rowGeometry,
+ pixelsPerSecond: 100,
+ contentOrigin: 32,
+ allowHorizontal: true,
+ viewportVersion: mountedId,
+ projectId,
+ sessionEpoch: 1,
+ syncScrollViewport,
+ });
+ return (
+ {
+ scrollRef.current = node;
+ if (node) {
+ Object.defineProperty(node, "clientWidth", { configurable: true, value: 300 });
+ Object.defineProperty(node, "clientHeight", { configurable: true, value: 100 });
+ }
+ }}
+ data-focus={`${focus.focusedRowKey}:${focus.pinnedElementId}`}
+ >
+ {mountedId &&
}
+
+ {logicalRows
+ .flatMap((row) => [row, ...row.items])
+ .map((target) =>
+ target.kind === "row" ? (
+
+ {target.id}
+
+
+ ) : (
+
+ ),
+ )}
+
{
- scrollRef.current = node;
- if (node) {
- Object.defineProperty(node, "clientWidth", { configurable: true, value: width });
- Object.defineProperty(node, "clientHeight", { configurable: true, value: height });
- }
- }}
- >
- {mounted &&
}
-