@hyperframes/studio 0.7.92 → 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/useTimelineLogicalFocus.ts

@@ -0,0 +1,80 @@
+import type { RefObject } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+import { usePlayerStore } from "../store/playerStore";
+import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
+import { useTimelineRowVirtualization } from "./useTimelineRowVirtualization";
+
+interface TimelineLogicalFocusInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
+  layout: { displayTrackOrder: readonly number[]; rowGeometry: TimelineRowGeometry };
+  laneCounts: ReadonlyMap<string, number>;
+  selectedElementId: string | null;
+  selectedElementIds: ReadonlySet<string>;
+  gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
+  elements: readonly TimelineElement[];
+  pixelsPerSecond: number;
+  contentOrigin: number;
+  allowHorizontal: boolean;
+  viewport: TimelineScrollViewportSnapshot;
+  sessionEpoch: number;
+  draggedRowKey?: number;
+  resizingElementIds?: readonly string[];
+  clipContextMenuRowKey?: number;
+  keyframeContextMenuRowKey?: number;
+  lastScrollLeftRef: RefObject<number>;
+  syncScrollViewport: (element: HTMLDivElement) => void;
+}
+
+export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
+  const expandedClipIds = usePlayerStore((state) => state.expandedClipIds);
+  const projectId = usePlayerStore((state) => state.timelineProjectId);
+  const logicalRows = useTimelineLogicalRows({
+    tracks: input.tracks,
+    displayTrackOrder: input.layout.displayTrackOrder,
+    laneCounts: input.laneCounts,
+    selectedElementId: input.selectedElementId,
+    selectedElementIds: input.selectedElementIds,
+    expandedClipIds,
+    gsapAnimations: input.gsapAnimations,
+  });
+  const focus = useTimelineFocusCoordinator({
+    scrollRef: input.scrollRef,
+    logicalRows,
+    elements: input.elements,
+    rowGeometry: input.layout.rowGeometry,
+    pixelsPerSecond: input.pixelsPerSecond,
+    contentOrigin: input.contentOrigin,
+    allowHorizontal: input.allowHorizontal,
+    viewportVersion: input.viewport,
+    projectId,
+    sessionEpoch: input.sessionEpoch,
+    syncScrollViewport: input.syncScrollViewport,
+  });
+  const rows = useTimelineRowVirtualization({
+    scrollRef: input.scrollRef,
+    viewport: input.viewport,
+    rowGeometry: input.layout.rowGeometry,
+    sessionEpoch: input.sessionEpoch,
+    elements: input.elements,
+    selectedElementId: input.selectedElementId,
+    focusedRowKey: focus.focusedRowKey,
+    draggedRowKey: input.draggedRowKey,
+    resizingElementIds: input.resizingElementIds,
+    clipContextMenuRowKey: input.clipContextMenuRowKey,
+    keyframeContextMenuRowKey: input.keyframeContextMenuRowKey,
+    lastScrollLeftRef: input.lastScrollLeftRef,
+    syncScrollViewport: input.syncScrollViewport,
+  });
+  return {
+    logicalRows,
+    ...focus,
+    rowVirtualizationActive: rows.enabled,
+    virtualRows: rows.virtualRows,
+    timelineFocusProps: rows.timelineFocusProps,
+  };
+}

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

@@ -0,0 +1,57 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { useTimelineLogicalRows } from "./useTimelineLogicalRows";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const tracks = Array.from(
+  { length: 1_000 },
+  (_, track) =>
+    [
+      track,
+      [{ id: `clip-${track}`, tag: "div", track, start: track, duration: 1 }],
+    ] as const satisfies readonly [number, readonly TimelineElement[]],
+);
+const displayTrackOrder = tracks.map(([track]) => track);
+const laneCounts = new Map<string, number>();
+const selectedElementIds = new Set<string>();
+const expandedClipIds = new Set<string>();
+const gsapAnimations = new Map();
+
+function Harness({ snapshots }: { snapshots: Array<readonly TimelineLogicalRow[]> }) {
+  usePlayerStore((state) => state.requestedSeekTime);
+  const logicalRows = useTimelineLogicalRows({
+    tracks,
+    displayTrackOrder,
+    laneCounts,
+    selectedElementId: null,
+    selectedElementIds,
+    expandedClipIds,
+    gsapAnimations,
+  });
+  snapshots.push(logicalRows);
+  return null;
+}
+
+afterEach(() => usePlayerStore.getState().reset());
+
+describe("useTimelineLogicalRows", () => {
+  it("preserves the dense logical model across an unrelated store update", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const snapshots: Array<readonly TimelineLogicalRow[]> = [];
+    act(() => root.render(<Harness snapshots={snapshots} />));
+    const first = snapshots.at(-1);
+
+    act(() => usePlayerStore.setState({ requestedSeekTime: 1 }));
+
+    expect(snapshots.at(-1)).toBe(first);
+    act(() => root.unmount());
+  });
+});

package/src/player/components/useTimelineLogicalRows.ts

@@ -0,0 +1,47 @@
+import { useMemo } from "react";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { TimelineElement } from "../store/playerStore";
+import { buildTimelineLogicalRows } from "./timelineKeyboardNavigation";
+
+interface TimelineLogicalRowsInput {
+  tracks: readonly (readonly [number, readonly TimelineElement[]])[];
+  displayTrackOrder: readonly number[];
+  laneCounts: ReadonlyMap<string, number>;
+  selectedElementId: string | null;
+  selectedElementIds: ReadonlySet<string>;
+  expandedClipIds: ReadonlySet<string>;
+  gsapAnimations: ReadonlyMap<string, readonly GsapAnimation[]>;
+}
+
+/** Shared by rendering and focus coordination; stable input refs preserve memo identity. */
+export function useTimelineLogicalRows({
+  tracks,
+  displayTrackOrder,
+  laneCounts,
+  selectedElementId,
+  selectedElementIds,
+  expandedClipIds,
+  gsapAnimations,
+}: TimelineLogicalRowsInput) {
+  return useMemo(
+    () =>
+      buildTimelineLogicalRows({
+        tracks,
+        displayTrackOrder,
+        laneCounts,
+        selectedElementId,
+        selectedElementIds,
+        expandedClipIds,
+        gsapAnimations,
+      }),
+    [
+      displayTrackOrder,
+      expandedClipIds,
+      gsapAnimations,
+      laneCounts,
+      selectedElementId,
+      selectedElementIds,
+      tracks,
+    ],
+  );
+}