@hyperframes/studio 0.7.90 → 0.7.93

package/src/player/components/useTimelineKeyboardActor.test.tsx

@@ -0,0 +1,267 @@
+// @vitest-environment happy-dom
+
+import React, { act, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
+const rows: readonly TimelineLogicalRow[] = [
+  {
+    id: "track-1",
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: "clip-1",
+    expandable: true,
+    expanded: false,
+    items: [{ id: "clip-1", kind: "clip", rowId: "track-1", elementId: "clip-1", time: 1 }],
+  },
+  {
+    id: "track-2",
+    kind: "row",
+    physicalTrackKey: 2,
+    logicalIndex: 1,
+    level: 1,
+    parentId: null,
+    elementId: "clip-2",
+    expandable: false,
+    expanded: false,
+    items: [{ id: "clip-2", kind: "clip", rowId: "track-2", elementId: "clip-2", time: 2 }],
+  },
+  {
+    id: "track-3",
+    kind: "row",
+    physicalTrackKey: 3,
+    logicalIndex: 2,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [],
+  },
+];
+
+interface HarnessProps {
+  focusedTargetId?: string | null;
+  logicalRows?: readonly TimelineLogicalRow[];
+  rowHeights?: readonly number[];
+  onToggleRow?: (target: TimelineLogicalRow) => void;
+}
+
+function Harness({
+  focusedTargetId = null,
+  logicalRows = rows,
+  rowHeights = logicalRows.map(() => 48),
+  onToggleRow = vi.fn(),
+}: HarnessProps) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const keyboard = useTimelineKeyboardActor({
+    logicalRows,
+    focusedTargetId,
+    rowGeometry: createTimelineRowGeometry(
+      [...new Set(logicalRows.map((row) => row.physicalTrackKey))],
+      rowHeights,
+    ),
+    scrollRef,
+    onToggleRow,
+  });
+  return (
+    <div ref={scrollRef} onFocus={keyboard.onFocus} onKeyDown={keyboard.onKeyDown}>
+      {logicalRows
+        .flatMap((row) => [row, ...row.items])
+        .map((target) =>
+          target.kind === "row" ? (
+            <div
+              key={target.id}
+              data-timeline-focus-id={target.id}
+              tabIndex={target.id === keyboard.rovingTargetId ? 0 : -1}
+            >
+              {target.id}
+              <button data-native-control={target.id} type="button">
+                Action
+              </button>
+            </div>
+          ) : (
+            <button
+              key={target.id}
+              data-timeline-focus-id={target.id}
+              tabIndex={target.id === keyboard.rovingTargetId ? 0 : -1}
+            >
+              {target.id}
+            </button>
+          ),
+        )}
+    </div>
+  );
+}
+
+function renderHarness(props: React.ComponentProps<typeof Harness> = {}) {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => root.render(<Harness {...props} />));
+  return { host, root };
+}
+
+function key(target: Element, value: string, init: KeyboardEventInit = {}) {
+  const event = new KeyboardEvent("keydown", {
+    bubbles: true,
+    cancelable: true,
+    key: value,
+    ...init,
+  });
+  act(() => target.dispatchEvent(event));
+  return event;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ timelineFocus: null, timelineFocusNonce: 0 });
+});
+
+describe("useTimelineKeyboardActor", () => {
+  it("exposes exactly one roving target and persists focused logical identity", () => {
+    const { host, root } = renderHarness({ focusedTargetId: "clip-2" });
+    expect(host.querySelectorAll('[data-timeline-focus-id][tabindex="0"]')).toHaveLength(1);
+    expect(host.querySelectorAll("[data-native-control]")).toHaveLength(3);
+    expect(
+      [...host.querySelectorAll<HTMLElement>("[data-native-control]")].every(
+        (el) => el.tabIndex === 0,
+      ),
+    ).toBe(true);
+    const target = host.querySelector<HTMLElement>('[data-timeline-focus-id="track-3"]')!;
+    act(() => target.focus());
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe("track-3");
+    act(() => root.unmount());
+  });
+
+  it("requests navigation focus without clicking or seeking", () => {
+    const { host, root } = renderHarness({ focusedTargetId: "clip-1" });
+    const target = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
+    const click = vi.fn();
+    target.addEventListener("click", click);
+    const event = key(target, "ArrowDown");
+    expect(event.defaultPrevented).toBe(true);
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe("clip-2");
+    expect(usePlayerStore.getState().requestedSeekTime).toBeNull();
+    expect(click).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("supports modified timeline boundaries and viewport-sized paging", () => {
+    const { host, root } = renderHarness({ focusedTargetId: "clip-2" });
+    const viewport = host.firstElementChild as HTMLDivElement;
+    Object.defineProperty(viewport, "clientHeight", { configurable: true, value: 48 });
+    const target = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-2"]')!;
+    key(target, "End", { metaKey: true });
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe("track-3");
+    key(target, "PageUp");
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe("clip-1");
+    act(() => root.unmount());
+  });
+
+  it("sizes paging around off-screen focus instead of the current viewport", () => {
+    const logicalRows: readonly TimelineLogicalRow[] = [
+      rows[0]!,
+      {
+        ...rows[0]!,
+        id: "property-1",
+        logicalIndex: 1,
+        level: 2,
+        parentId: "track-1",
+        expandable: false,
+        items: [],
+      },
+      {
+        ...rows[0]!,
+        id: "property-2",
+        logicalIndex: 2,
+        level: 2,
+        parentId: "track-1",
+        expandable: false,
+        items: [],
+      },
+      { ...rows[1]!, logicalIndex: 3 },
+      { ...rows[2]!, logicalIndex: 4 },
+    ];
+    const { host, root } = renderHarness({
+      focusedTargetId: "track-3",
+      logicalRows,
+      rowHeights: [104, 48, 48],
+    });
+    const viewport = host.firstElementChild as HTMLDivElement;
+    Object.defineProperty(viewport, "clientHeight", { configurable: true, value: 47 });
+    const target = host.querySelector<HTMLElement>('[data-timeline-focus-id="track-3"]')!;
+    key(target, "PageUp");
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe("track-2");
+    act(() => root.unmount());
+  });
+
+  it("supports APG disclosure arrows plus Enter and Space", () => {
+    const onToggleRow = vi.fn();
+    const { host, root } = renderHarness({ focusedTargetId: "track-1", onToggleRow });
+    const row = host.querySelector<HTMLElement>('[data-timeline-focus-id="track-1"]')!;
+    const clip = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
+    const nativeClick = vi.fn();
+    clip.addEventListener("click", nativeClick);
+    expect(key(row, "ArrowRight").defaultPrevented).toBe(true);
+    expect(onToggleRow).toHaveBeenCalledWith(rows[0]);
+    expect(key(row, " ").defaultPrevented).toBe(true);
+    expect(onToggleRow).toHaveBeenCalledWith(rows[0]);
+    const enter = key(clip, "Enter");
+    expect(enter.defaultPrevented).toBe(false);
+    // dispatchEvent does not synthesize a browser default action, so model it explicitly.
+    if (!enter.defaultPrevented) act(() => clip.click());
+    expect(nativeClick).toHaveBeenCalledOnce();
+    expect(onToggleRow).toHaveBeenCalledTimes(2);
+    act(() => root.unmount());
+  });
+
+  it("collapses expanded rows and leaves native header controls to the browser", () => {
+    const onToggleRow = vi.fn();
+    const expandedRows = [{ ...rows[0]!, expanded: true }, ...rows.slice(1)];
+    const { host, root } = renderHarness({
+      focusedTargetId: "track-1",
+      logicalRows: expandedRows,
+      onToggleRow,
+    });
+    const row = host.querySelector<HTMLElement>('[data-timeline-focus-id="track-1"]')!;
+    expect(key(row, "ArrowLeft").defaultPrevented).toBe(true);
+    expect(onToggleRow).toHaveBeenCalledWith(expandedRows[0]);
+
+    usePlayerStore.setState({ timelineFocus: null, timelineFocusNonce: 0 });
+    const control = host.querySelector<HTMLElement>('[data-native-control="track-1"]')!;
+    const nativeClick = vi.fn();
+    control.addEventListener("click", nativeClick);
+    act(() => control.focus());
+    expect(usePlayerStore.getState().timelineFocus).toBeNull();
+    const enter = key(control, "Enter");
+    expect(enter.defaultPrevented).toBe(false);
+    // dispatchEvent does not synthesize a browser default action, so model it explicitly.
+    if (!enter.defaultPrevented) act(() => control.click());
+    expect(nativeClick).toHaveBeenCalledOnce();
+    expect(onToggleRow).toHaveBeenCalledOnce();
+    act(() => root.unmount());
+  });
+
+  it("dispatches the existing scoped context-menu callback", () => {
+    const { host, root } = renderHarness({ focusedTargetId: "clip-1" });
+    const target = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
+    const context = vi.fn((event: Event) => event.preventDefault());
+    target.addEventListener("contextmenu", context);
+    key(target, "F10", { shiftKey: true });
+    expect(context).toHaveBeenCalledOnce();
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineKeyboardActor.ts

@@ -0,0 +1,147 @@
+import { useCallback, useMemo, type FocusEvent, type KeyboardEvent, type RefObject } from "react";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import {
+  isTimelineNavigationKey,
+  locateTimelineLogicalTarget,
+  resolveTimelineNavigationTarget,
+  type TimelineLogicalRow,
+} from "./timelineKeyboardNavigation";
+
+interface TimelineKeyboardActorInput {
+  logicalRows: readonly TimelineLogicalRow[];
+  focusedTargetId: string | null;
+  rowGeometry: TimelineRowGeometry;
+  scrollRef: RefObject<HTMLDivElement | null>;
+  onToggleRow: (target: TimelineLogicalRow) => void;
+}
+
+function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
+  if (!(event.target instanceof Element)) return null;
+  // Header actions stay native Tab stops because they have no row-level shortcut.
+  // The nearest interactive ancestor wins so their events never masquerade as row events.
+  const target = event.target.closest<HTMLElement>(
+    "button, input, select, textarea, a[href], [contenteditable], [data-timeline-focus-id]",
+  );
+  return target?.dataset.timelineFocusId && event.currentTarget.contains(target) ? target : null;
+}
+
+function viewportPageSize(
+  logicalRowCountByTrack: ReadonlyMap<number, number>,
+  focusedTrackKey: number,
+  geometry: TimelineRowGeometry,
+  viewport: HTMLDivElement | null,
+): number {
+  if (!viewport || logicalRowCountByTrack.size === 0) return 1;
+  const focusedRow = geometry.getRowIndex(focusedTrackKey);
+  const first = Math.max(
+    0,
+    focusedRow >= 0 ? focusedRow : Math.floor(geometry.getRowFromY(viewport.scrollTop)),
+  );
+  const pageTop = focusedRow >= 0 ? geometry.getRowTop(focusedRow) : viewport.scrollTop;
+  // Stay just inside the viewport so an exact row boundary does not count the next row.
+  const last = Math.min(
+    geometry.rowKeys.length - 1,
+    Math.floor(geometry.getRowFromY(pageTop + Math.max(0, viewport.clientHeight - 0.001))),
+  );
+  let count = 0;
+  for (let index = first; index <= last; index += 1) {
+    count += logicalRowCountByTrack.get(geometry.rowKeys[index]!) ?? 0;
+  }
+  return Math.max(1, count);
+}
+
+function openContextMenu(target: HTMLElement): void {
+  const bounds = target.getBoundingClientRect();
+  target.dispatchEvent(
+    new MouseEvent("contextmenu", {
+      bubbles: true,
+      cancelable: true,
+      clientX: bounds.left + bounds.width / 2,
+      clientY: bounds.top + bounds.height / 2,
+    }),
+  );
+}
+
+/** The timeline's sole keyboard actor; controls only describe their logical identity. */
+export function useTimelineKeyboardActor({
+  logicalRows,
+  focusedTargetId,
+  rowGeometry,
+  scrollRef,
+  onToggleRow,
+}: TimelineKeyboardActorInput) {
+  const rovingTargetId =
+    (focusedTargetId && locateTimelineLogicalTarget(logicalRows, focusedTargetId)?.target.id) ??
+    logicalRows[0]?.id ??
+    null;
+  const logicalRowCountByTrack = useMemo(() => {
+    const counts = new Map<number, number>();
+    for (const row of logicalRows) {
+      counts.set(row.physicalTrackKey, (counts.get(row.physicalTrackKey) ?? 0) + 1);
+    }
+    return counts;
+  }, [logicalRows]);
+
+  const onFocus = useCallback(
+    (event: FocusEvent<HTMLElement>) => {
+      const id = eventTarget(event)?.dataset.timelineFocusId;
+      if (id && id !== focusedTargetId) usePlayerStore.getState().requestTimelineFocus(id);
+    },
+    // ponytail: This closure must see the current id or coordinator-driven focus bumps the nonce twice.
+    [focusedTargetId],
+  );
+
+  const onKeyDown = useCallback(
+    // One handler owns navigation, context-menu, and disclosure keyboard semantics.
+    // fallow-ignore-next-line complexity
+    (event: KeyboardEvent<HTMLElement>) => {
+      const targetElement = eventTarget(event);
+      const id = targetElement?.dataset.timelineFocusId;
+      if (!targetElement || !id) return;
+      const located = locateTimelineLogicalTarget(logicalRows, id);
+      if (!located) return;
+
+      if (isTimelineNavigationKey(event.key)) {
+        if (
+          located.target.kind === "row" &&
+          ((event.key === "ArrowRight" && located.target.expandable && !located.target.expanded) ||
+            (event.key === "ArrowLeft" && located.target.expandable && located.target.expanded))
+        ) {
+          event.preventDefault();
+          onToggleRow(located.target);
+          return;
+        }
+        const next = resolveTimelineNavigationTarget(logicalRows, id, event.key, {
+          pageSize: viewportPageSize(
+            logicalRowCountByTrack,
+            located.row.physicalTrackKey,
+            rowGeometry,
+            scrollRef.current,
+          ),
+          timelineBoundary: event.ctrlKey || event.metaKey,
+        });
+        event.preventDefault();
+        if (next && next.id !== id) usePlayerStore.getState().requestTimelineFocus(next.id);
+        return;
+      }
+      if (event.key === "ContextMenu" || (event.key === "F10" && event.shiftKey)) {
+        event.preventDefault();
+        openContextMenu(targetElement);
+        return;
+      }
+      if (
+        (event.key !== "Enter" && event.key !== " ") ||
+        located.target.kind !== "row" ||
+        !located.target.expandable
+      ) {
+        return;
+      }
+      event.preventDefault();
+      onToggleRow(located.target);
+    },
+    [logicalRowCountByTrack, logicalRows, onToggleRow, rowGeometry, scrollRef],
+  );
+
+  return { rovingTargetId, onFocus, onKeyDown };
+}

package/src/player/components/useTimelineKeyframeHandlers.test.tsx

@@ -5,14 +5,12 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
 import type { TimelineElement } from "../store/playerStore";
 import { usePlayerStore } from "../store/playerStore";
+import * as telemetry from "../../telemetry/events";
 import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
 import { useTimelineKeyframeHandlers } from "./useTimelineKeyframeHandlers";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-const trackStudioSegmentEaseEdit = vi.hoisted(() => vi.fn());
-vi.mock("../../telemetry/events", () => ({ trackStudioSegmentEaseEdit }));
-
 const ELEMENT: TimelineElement = {
   id: "clip-1",
   label: "Hero card",
@@ -46,8 +44,8 @@ const COLLIDING_TARGET: TimelineKeyframeTarget = {
 
 afterEach(() => {
   document.body.innerHTML = "";
-  trackStudioSegmentEaseEdit.mockClear();
-  usePlayerStore.setState({ focusedEaseSegment: null });
+  vi.restoreAllMocks();
+  usePlayerStore.setState({ focusedEaseSegment: null, timelineSessionEpoch: 0 });
 });
 
 /**
@@ -78,6 +76,9 @@ function mountHandlers(options: Partial<Parameters<typeof useTimelineKeyframeHan
 
 describe("useTimelineKeyframeHandlers", () => {
   it("tracks opening the segment ease editor when a timeline segment is selected", () => {
+    const trackStudioSegmentEaseEdit = vi
+      .spyOn(telemetry, "trackStudioSegmentEaseEdit")
+      .mockImplementation(() => {});
     const { root, handlers } = mountHandlers();
     act(() => handlers.onSelectSegment?.(ELEMENT.id, TARGET));
 
@@ -90,7 +91,7 @@ describe("useTimelineKeyframeHandlers", () => {
     const { root, handlers } = mountHandlers();
     act(() => handlers.onSelectSegment?.(ELEMENT.id, COLLIDING_TARGET));
 
-    expect(usePlayerStore.getState().focusedEaseSegment).toEqual({
+    expect(usePlayerStore.getState().focusedEaseSegment).toMatchObject({
       animationId: "position-tween",
       collidingAnimationTargets: [
         { animationId: "position-tween", tweenPercentage: 100 },
@@ -111,7 +112,7 @@ describe("useTimelineKeyframeHandlers", () => {
     // Selecting a segment must NOT move the playhead.
     act(() => handlers.onSelectSegment?.(ELEMENT.id, FLAT_TWEEN_TARGET));
     expect(onSeek).not.toHaveBeenCalled();
-    expect(usePlayerStore.getState().focusedEaseSegment).toEqual({
+    expect(usePlayerStore.getState().focusedEaseSegment).toMatchObject({
       animationId: "position-tween",
       tweenPercentage: 100,
       elementId: ELEMENT.id,
@@ -125,4 +126,39 @@ describe("useTimelineKeyframeHandlers", () => {
     expect(onSeek).toHaveBeenCalledExactlyOnceWith(2);
     act(() => root.unmount());
   });
+
+  it("scopes a keyframe context target to the opening timeline session", () => {
+    const setKfContextMenu = vi.fn();
+    usePlayerStore.setState({ timelineSessionEpoch: 4 });
+
+    function Harness() {
+      const { onContextMenuKeyframe } = useTimelineKeyframeHandlers({
+        expandedElements: [ELEMENT],
+        keyframeCache: new Map(),
+        setSelectedElementId: vi.fn(),
+        setKfContextMenu,
+        toggleSelectedKeyframe: vi.fn(),
+      });
+      return (
+        <button
+          type="button"
+          onContextMenu={(event) => onContextMenuKeyframe(event, ELEMENT.id, TARGET)}
+        />
+      );
+    }
+
+    const root = mountReactHarness(<Harness />);
+    const button = document.querySelector("button");
+    expect(button).not.toBeNull();
+    act(() => {
+      button?.dispatchEvent(
+        new MouseEvent("contextmenu", { bubbles: true, clientX: 10, clientY: 20 }),
+      );
+    });
+
+    expect(setKfContextMenu).toHaveBeenCalledWith(
+      expect.objectContaining({ elementId: ELEMENT.id, sessionEpoch: 4, x: 14, y: 22 }),
+    );
+    act(() => root.unmount());
+  });
 });