@hyperframes/studio 0.8.110 → 0.8.112

package/src/player/components/timelineTrackInsertLayout.test.ts

@@ -0,0 +1,249 @@
+import { expect, it, vi } from "vitest";
+import { buildTimelineTrackInsertLayout } from "./timelineTrackInsertLayout";
+import { computeDragPreview } from "./timelineClipDragPreview";
+import { commitDraggedClipMove } from "./timelineClipDragCommit";
+import { timelineAudioRow, resolveZoneDropPlacement } from "./timelineCollision";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineElement } from "../store/playerStore";
+import type { DraggedClipState } from "./timelineClipDragTypes";
+
+it.each([
+  { order: [0, 0.5, 1, 3, 2, 4], seam: 4 },
+  { order: [0, 0.5, 2, 4], seam: 2 },
+])(
+  "inserts below an expanded or collapsed group block in displayed order ($seam)",
+  async ({ order, seam }) => {
+    const layout = buildTimelineTrackInsertLayout(order, [
+      { anchorKey: 0.5, memberTracks: [1, 3] },
+    ]);
+    const elements: TimelineElement[] = [0, 1, 2, 3, 4].map((track) => ({
+      id: `clip-${track}`,
+      domId: `clip-${track}`,
+      tag: "audio",
+      start: 0,
+      duration: 1,
+      track,
+      audioGroup: track === 1 || track === 3 ? "group" : undefined,
+    }));
+    elements.push({ id: "tail", domId: "tail", tag: "audio", start: 3, duration: 1, track: 4 });
+    const hero = elements[4];
+    const drag: DraggedClipState = {
+      pointerId: 1,
+      element: hero,
+      originClientX: 100,
+      originClientY: 48 + order.indexOf(hero.track) * 48,
+      originScrollLeft: 0,
+      originScrollTop: 0,
+      pointerClientX: 100,
+      pointerClientY: 48 + order.indexOf(hero.track) * 48,
+      pointerOffsetX: 0,
+      pointerOffsetY: 0,
+      previewStart: 0,
+      previewTrack: 4,
+      desiredTrack: 4,
+      insertRow: null,
+      snapTime: null,
+      snapType: null,
+      started: true,
+    };
+    const geometry = createTimelineRowGeometry(
+      order,
+      order.map(() => 48),
+      { top: 0 },
+    );
+    const context = {
+      scroll: null,
+      pps: 100,
+      duration: 10,
+      trackOrder: order,
+      rowGeometry: geometry,
+      elements,
+      selectedKeys: new Set<string>(),
+      buildSnapTargets: () => [],
+      allowedInsertRows: layout.allowedRows,
+      groupTracks: layout.groupTracks,
+    };
+    const ontoHeader = computeDragPreview(drag, 100, geometry.getRowTop(1) + 24, context);
+    expect(ontoHeader.insertRow).toBeNull();
+    expect(ontoHeader.previewTrack).toBe(order.length === 6 ? 1 : 4);
+    if (order.length === 6) {
+      expect(layout.allowedRows.has(2)).toBe(false);
+      expect(layout.allowedRows.has(3)).toBe(false);
+      const ontoMember = computeDragPreview(drag, 100, 130, context);
+      expect(ontoMember.insertRow).toBeNull();
+      expect(ontoMember.previewTrack).toBe(1);
+    }
+    const preview = computeDragPreview(drag, 100, geometry.getRowTop(seam), context);
+    expect(preview.insertRow).toBe(seam);
+    const moved = new Map(elements.map((element) => [element.id, element]));
+    const persist = vi.fn();
+    commitDraggedClipMove(preview, {
+      elements,
+      trackOrder: order,
+      trackInsertLayout: layout,
+      updateElement: (id, updates) => {
+        moved.set(id, { ...moved.get(id)!, ...updates });
+      },
+      onMoveElements: persist,
+    });
+    await Promise.resolve();
+    expect(persist).toHaveBeenCalledOnce();
+    expect(moved.get("clip-1")?.track).toBe(1);
+    expect(moved.get("clip-3")?.track).toBe(2);
+    expect(moved.get("clip-4")?.track).toBe(3);
+    expect(moved.get("clip-2")?.track).toBe(4);
+  },
+);
+
+it.each([{ order: [0, 0.5] }, { order: [0, 0.5, 2] }])(
+  "keeps a collapsed audio group at the zone boundary ($order)",
+  ({ order }) => {
+    const layout = buildTimelineTrackInsertLayout(order, [
+      { anchorKey: 0.5, memberTracks: [1, 3] },
+    ]);
+    expect(timelineAudioRow(order, new Set([1, 3, 2]), layout.groupTracks)).toBe(1);
+  },
+);
+
+it.each([
+  { insertRow: 0, target: 0 },
+  { insertRow: null, target: 2 },
+])(
+  "detaches only new-track drops, retaining member-track behavior ($insertRow)",
+  async ({ insertRow, target }) => {
+    const hero: TimelineElement = {
+      id: "hero",
+      domId: "hero",
+      tag: "audio",
+      start: 0,
+      duration: 1,
+      track: 1,
+      audioGroup: "voice",
+    };
+    const member: TimelineElement = {
+      id: "member",
+      domId: "member",
+      tag: "audio",
+      start: 2,
+      duration: 1,
+      track: 2,
+      audioGroup: "voice",
+    };
+    const elements = [hero, member];
+    const order = [0.5, 1, 2];
+    const layout = buildTimelineTrackInsertLayout(order, [
+      { anchorKey: 0.5, memberTracks: [1, 2] },
+    ]);
+    const moved = new Map(elements.map((element) => [element.id, element]));
+    const persist = vi.fn();
+    commitDraggedClipMove(
+      {
+        pointerId: null,
+        element: hero,
+        insertRow,
+        started: true,
+        originClientX: 0,
+        originClientY: 0,
+        originScrollLeft: 0,
+        originScrollTop: 0,
+        pointerClientX: 0,
+        pointerClientY: 0,
+        pointerOffsetX: 0,
+        pointerOffsetY: 0,
+        previewStart: 0,
+        previewTrack: target,
+        desiredTrack: target,
+        snapTime: null,
+        snapType: null,
+      },
+      {
+        elements,
+        trackOrder: order,
+        trackInsertLayout: layout,
+        onMoveElements: persist,
+        updateElement: (id, updates) => {
+          moved.set(id, { ...moved.get(id)!, ...updates });
+        },
+      },
+    );
+    await Promise.resolve();
+    expect(moved.get("hero")?.audioGroup).toBe(insertRow === null ? "voice" : undefined);
+    expect(moved.get("hero")?.track).toBe(target);
+    expect(moved.get("member")?.audioGroup).toBe("voice");
+    const edit = persist.mock.calls[0][0].find(
+      (edit: { element: TimelineElement }) => edit.element.id === "hero",
+    );
+    expect(edit.updates.audioGroup).toBe(insertRow === null ? undefined : null);
+  },
+);
+
+it("creates the first visual lane above an all-audio timeline", () => {
+  expect(
+    resolveZoneDropPlacement({
+      order: [0, 1],
+      audioTracks: new Set([0, 1]),
+      elements: [],
+      desiredTrack: 0,
+      deliberateInsertRow: null,
+      start: 2,
+      duration: 1,
+      dragKey: "new-visual",
+      isAudio: false,
+    }),
+  ).toEqual({ track: 0, insertRow: 0, start: 2 });
+});
+
+it("keeps audible-video groups in the visual zone for header drops and edge inserts", () => {
+  const order = [0, 0.5, 1, 2];
+  const layout = buildTimelineTrackInsertLayout(order, [{ anchorKey: 0.5, memberTracks: [1] }]);
+  const input = {
+    order,
+    audioTracks: new Set<number>(),
+    groupTracks: layout.groupTracks,
+    allowedInsertRows: layout.allowedRows,
+    elements: [],
+    desiredTrack: 0.5,
+    deliberateInsertRow: null,
+    start: 2,
+    duration: 1,
+    dragKey: "video",
+    isAudio: false,
+    origin: { track: 2, start: 2 },
+  };
+  expect(timelineAudioRow(order, input.audioTracks, layout.groupTracks)).toBe(-1);
+  expect(resolveZoneDropPlacement(input)).toEqual({ track: 1, insertRow: null, start: 2 });
+  expect(resolveZoneDropPlacement({ ...input, deliberateInsertRow: 3 })).toEqual({
+    track: 0.5,
+    insertRow: 3,
+    start: 2,
+  });
+});
+
+it.each([
+  { isAudio: false, target: 1 },
+  { isAudio: true, target: 3 },
+])(
+  "maps a mixed-kind group header to its first visible member of the clip kind ($isAudio)",
+  ({ isAudio, target }) => {
+    const order = [0, 0.5, 1, 3, 2];
+    const layout = buildTimelineTrackInsertLayout(order, [
+      { anchorKey: 0.5, memberTracks: [1, 3] },
+    ]);
+    expect(
+      resolveZoneDropPlacement({
+        order,
+        audioTracks: new Set([3]),
+        groupTracks: layout.groupTracks,
+        allowedInsertRows: layout.allowedRows,
+        elements: [],
+        desiredTrack: 0.5,
+        deliberateInsertRow: null,
+        start: 2,
+        duration: 1,
+        dragKey: "clip",
+        isAudio,
+        origin: { track: 2, start: 2 },
+      }),
+    ).toEqual({ track: target, insertRow: null, start: 2 });
+  },
+);

package/src/player/components/timelineTrackInsertLayout.ts

@@ -0,0 +1,71 @@
+import type { TimelineTrackGroupInfo } from "./useTimelineTrackDerivations";
+import { timelineAudioRow, isInsertAllowedForZone } from "./timelineCollision";
+
+export function timelineTrackOrderChanged(
+  previous: readonly number[],
+  current: readonly number[],
+): boolean {
+  return current.length !== previous.length || current.some((key, row) => key !== previous[row]);
+}
+
+export interface TimelineTrackInsertLayout {
+  allowedRows: ReadonlySet<number>;
+  trackOrder: number[];
+  topologyRows: number[];
+  groupTracks: ReadonlyMap<number, readonly number[]>;
+}
+
+export function keyboardPickupInsertRow(
+  row: number,
+  allowed: ReadonlySet<number> | undefined,
+): number {
+  while (row > 0 && allowed && !allowed.has(row)) row--;
+  return row;
+}
+
+export function nextKeyboardInsertRow(input: {
+  current: number;
+  step: -1 | 1;
+  order: number[];
+  layout: TimelineTrackInsertLayout | undefined;
+  audioTracks: ReadonlySet<number>;
+  isAudio: boolean;
+}): number | null {
+  const { current, step, order, layout, audioTracks, isAudio } = input;
+  let row = Math.max(0, Math.min(order.length, current + step));
+  const allowed = layout?.allowedRows;
+  while (allowed?.has(row) === false) {
+    row += step;
+    if (row < 0 || row > order.length) return null;
+  }
+  const audioRow = timelineAudioRow(order, audioTracks, layout?.groupTracks);
+  return isInsertAllowedForZone(row, audioRow, isAudio, allowed) ? row : null;
+}
+
+/** Groups own one contiguous insertion block, including their collapsed members. */
+export function buildTimelineTrackInsertLayout(
+  order: number[],
+  groups: readonly Pick<TimelineTrackGroupInfo, "anchorKey" | "memberTracks">[],
+): TimelineTrackInsertLayout {
+  const allowedRows = new Set(Array.from({ length: order.length + 1 }, (_, row) => row));
+  const anchors = new Map(groups.map((group) => [group.anchorKey, group.memberTracks]));
+  const positions = new Map(order.map((key, row) => [key, row]));
+  for (const group of groups) {
+    const anchor = positions.get(group.anchorKey);
+    if (anchor === undefined) continue;
+    const end = Math.max(anchor, ...group.memberTracks.map((key) => positions.get(key) ?? anchor));
+    for (let row = anchor + 1; row <= end; row++) allowedRows.delete(row);
+  }
+  const tracks = new Set<number>();
+  const topologyRows = [0];
+  for (const key of order) {
+    for (const track of anchors.get(key) ?? [key]) tracks.add(track);
+    topologyRows.push(tracks.size);
+  }
+  return {
+    allowedRows,
+    trackOrder: [...tracks],
+    topologyRows,
+    groupTracks: anchors,
+  };
+}

package/src/player/components/timelineZMirror.ts

@@ -3,6 +3,7 @@ import { classifyZone } from "./timelineZones";
 import { isLaneFree, timeRangesOverlap } from "./timelineCollision";
 import { authoredTrackForLane, sameSourceFile } from "./timelineAuthoredTrack";
 import { samePaintScope } from "./timelineStackingSync";
+import { timelineTrackOrder } from "./timelineTrackDisplay";
 
 /**
  * Mirror a canvas z-order action (Bring to Front / Bring Forward / Send Backward /
@@ -111,13 +112,6 @@ function expandedChildAllowedLanes(
   );
 }
 
-/** Ascending unique display lanes of `elements` — identical to how Timeline.tsx
- *  builds `trackOrder`, so `insertRow` indexes the same boundary space. Exported
- *  so the mirror wiring can hand commitZMirrorLaneMove the matching trackOrder. */
-export function displayTrackOrder(elements: TimelineElement[]): number[] {
-  return [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);
-}
-
 /**
  * Resolve the timeline lane move that mirrors a z-order action on `element`.
  * Returns null when no timeline mirror applies: audio / zero-length clips, no
@@ -146,8 +140,8 @@ export function resolveZMirrorLaneMove(input: ZMirrorInput): ZMirrorLaneMove {
   const referenceLane = resolveReferenceLane(input, overlapSet, up);
   if (referenceLane == null) return null;
 
-  const order = displayTrackOrder(elements);
-  const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
+  const order = timelineTrackOrder(elements);
+  const visualLanes = timelineTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
   const refIdx = visualLanes.indexOf(referenceLane);
   if (refIdx === -1) return null; // reference is not a visual lane — no mirror
 
@@ -251,8 +245,8 @@ export function resolveRepositionLaneMove(input: ZRepositionInput): ZMirrorLaneM
   }
   if (aboveLane == null && belowLane == null) return null;
 
-  const order = displayTrackOrder(elements);
-  const visualLanes = displayTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
+  const order = timelineTrackOrder(elements);
+  const visualLanes = timelineTrackOrder(elements.filter((el) => classifyZone(el) === "visual"));
   const allowedLanes = expandedChildAllowedLanes(element, elements);
   const args = {
     elements,

package/src/player/components/useTimelineClipDrag.keyboard.test.tsx

@@ -0,0 +1,163 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import { useTimelineClipDrag } from "./useTimelineClipDrag";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { configureTimelineTestViewport } from "./timelineTestViewport";
+import { buildTimelineTrackInsertLayout } from "./timelineTrackInsertLayout";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+function mount(order = [0, 1, 2]) {
+  const elements: TimelineElement[] = [
+    { id: "top", tag: "div", start: 0, duration: 3, track: 0 },
+    { id: "hero", domId: "hero", tag: "div", start: 2, duration: 3, track: 1 },
+    { id: "tail", tag: "div", start: 6, duration: 3, track: 1 },
+    { id: "bottom", tag: "div", start: 0, duration: 3, track: 2 },
+  ];
+  const groups = order.includes(0.5) ? [{ anchorKey: 0.5, memberTracks: [1, 3] }] : [];
+  if (groups.length) {
+    for (const element of elements) element.tag = "audio";
+    elements[1].audioGroup = "voice";
+    elements[2].audioGroup = "voice";
+    elements.push({
+      id: "member",
+      tag: "audio",
+      start: 0,
+      duration: 2,
+      track: 3,
+      audioGroup: "voice",
+    });
+    elements.push({ id: "extra", tag: "audio", start: 0, duration: 2, track: 4 });
+  }
+  for (const element of elements) element.domId = element.id;
+  usePlayerStore.getState().setElements(elements);
+  const scroll = document.createElement("div");
+  configureTimelineTestViewport(scroll, 400);
+  const clip = document.createElement("div");
+  clip.dataset.elId = "hero";
+  clip.dataset.timelineFocusId = "clip-hero";
+  clip.tabIndex = 0;
+  scroll.append(clip);
+  document.body.append(scroll);
+  const host = document.createElement("div");
+  const root = createRoot(host);
+  const onMoveElements = vi.fn();
+  const trackOrderRef = { current: order };
+  const trackInsertLayoutRef = { current: buildTimelineTrackInsertLayout(order, groups) };
+  let state: ReturnType<typeof useTimelineClipDrag>;
+  function Probe() {
+    state = useTimelineClipDrag({
+      scrollRef: { current: scroll },
+      ppsRef: { current: 100 },
+      durationRef: { current: 12 },
+      trackOrderRef,
+      trackInsertLayoutRef,
+      rowGeometryRef: {
+        current: createTimelineRowGeometry(
+          trackOrderRef.current,
+          trackOrderRef.current.map(() => 48),
+          { top: 0 },
+        ),
+      },
+      onMoveElement: vi.fn(),
+      onMoveElements,
+      setShowPopover: () => {},
+      setRangeSelectionRef: { current: null },
+    });
+    return null;
+  }
+  act(() => root.render(<Probe />));
+  clip.focus();
+  const key = (key: string) =>
+    act(() => {
+      clip.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
+    });
+  return {
+    key,
+    clip,
+    onMoveElements,
+    root,
+    elements,
+    changeOrder(next: number[]) {
+      trackOrderRef.current = next;
+      trackInsertLayoutRef.current = buildTimelineTrackInsertLayout(next, groups);
+      act(() => root.render(<Probe />));
+    },
+    get drag() {
+      return state.draggedClip;
+    },
+  };
+}
+
+function expectCanceledPickup(view: ReturnType<typeof mount>) {
+  expect(view.drag).toBeNull();
+  expect(view.onMoveElements).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().elements).toEqual(view.elements);
+}
+
+it("cancels pickup when collapsing a group changes the displayed seam", () => {
+  const view = mount([0, 0.5, 1, 3, 2, 4]);
+  view.key(" ");
+  view.key("ArrowDown");
+  expect(view.drag?.insertRow).toBe(4);
+  view.changeOrder([0, 0.5, 2, 4]);
+  expect(view.drag).toBeNull();
+  view.key("Enter");
+  expectCanceledPickup(view);
+  act(() => view.root.unmount());
+});
+
+it("picks up with Space, chooses a seam, then commits at that index once with Enter", async () => {
+  const view = mount();
+  view.key(" ");
+  expect(view.drag).toMatchObject({
+    pointerId: null,
+    started: true,
+    insertRow: 1,
+    previewStart: 2,
+  });
+  view.key("ArrowUp");
+  expect(view.drag?.insertRow).toBe(0);
+  await act(async () => view.key("Enter"));
+  expect(view.drag).toBeNull();
+  expect(view.onMoveElements).toHaveBeenCalledTimes(1);
+  const moved = usePlayerStore.getState().elements;
+  expect(moved.find((e) => e.id === "hero")?.track).toBe(0);
+  expect(moved.find((e) => e.id === "top")?.track).toBe(1);
+  view.key("Enter");
+  expect(view.onMoveElements).toHaveBeenCalledTimes(1);
+  act(() => view.root.unmount());
+});
+
+it("Escape cancels the opened lane without moving a clip or adding a track", () => {
+  const view = mount();
+  view.key(" ");
+  view.key("ArrowDown");
+  expect(view.drag?.insertRow).toBe(2);
+  view.key("Escape");
+  expectCanceledPickup(view);
+  act(() => view.root.unmount());
+});
+
+it("leaves Space on a nested fade slider to the slider", () => {
+  const view = mount();
+  const slider = document.createElement("div");
+  slider.setAttribute("role", "slider");
+  slider.tabIndex = 0;
+  view.clip.append(slider);
+  slider.focus();
+  const event = new KeyboardEvent("keydown", { key: " ", bubbles: true, cancelable: true });
+  act(() => {
+    slider.dispatchEvent(event);
+  });
+  expect(view.drag).toBeNull();
+  expect(event.defaultPrevented).toBe(false);
+  act(() => view.root.unmount());
+});