@hyperframes/studio 0.7.77 → 0.7.79

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

@@ -0,0 +1,281 @@
+// @vitest-environment happy-dom
+
+import React, { act, createRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimelineLanes } from "./TimelineLanes";
+import { getTrackStyle } from "./timelineIcons";
+import { defaultTimelineTheme } from "./timelineTheme";
+import { TRACK_H } from "./timelineLayout";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
+import type { TimelineEditCallbacks } from "./timelineCallbacks";
+import type { DraggedClipState, BlockedClipState } from "./useTimelineClipDrag";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.getState().reset();
+});
+
+/** The z-order sort keys really are fractional: a clip nudged between two lanes
+ *  lands on the midpoint. These are the values that used to reach aria-label. */
+const TRACK_A = 1 / 6;
+const TRACK_B = 0.5;
+
+function element(id: string, track: number): TimelineElement {
+  return { id, label: id, tag: "div", start: 0, duration: 2, track };
+}
+
+function positionTween(id: string): GsapAnimation {
+  return {
+    id: `${id}-tween`,
+    targetSelector: `#${id}`,
+    method: "to",
+    position: 0,
+    duration: 2,
+    properties: {},
+    propertyGroup: "position",
+    keyframes: {
+      format: "percentage",
+      keyframes: [
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: 100 } },
+      ],
+    },
+  };
+}
+
+interface RenderLanesOptions {
+  elements?: TimelineElement[];
+  animations?: Map<string, GsapAnimation[]>;
+  expandedClipIds?: string[];
+  selectedElementIds?: Set<string>;
+  multiDragPreview?: MultiDragPreviewInput | null;
+  draggedClip?: DraggedClipState | null;
+  onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
+  onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
+}
+
+function renderLanes(options: RenderLanesOptions = {}): {
+  host: HTMLDivElement;
+  root: Root;
+  rerender: (next: RenderLanesOptions) => void;
+} {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const render = (next: RenderLanesOptions) => {
+    const elements = next.elements ?? [element("clip-a", TRACK_A)];
+    const gsapAnimations = next.animations ?? new Map<string, GsapAnimation[]>();
+    const displayTrackOrder = [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);
+    const tracks: [number, TimelineElement[]][] = displayTrackOrder.map((track) => [
+      track,
+      elements.filter((el) => el.track === track),
+    ]);
+    const laneCounts = new Map(
+      elements.map((el) => [el.id, (gsapAnimations.get(el.id) ?? []).length]),
+    );
+    act(() => {
+      usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
+      root.render(
+        <TimelineLanes
+          pps={100}
+          contentOrigin={232}
+          contentGutter={32}
+          trackContentWidth={800}
+          theme={defaultTimelineTheme}
+          displayTrackOrder={displayTrackOrder}
+          rowHeights={displayTrackOrder.map(() => TRACK_H)}
+          trackOrder={displayTrackOrder}
+          tracks={tracks}
+          trackStyles={new Map()}
+          laneCounts={laneCounts}
+          selectedElementId={null}
+          selectedElementIds={next.selectedElementIds ?? new Set()}
+          hoveredClip={null}
+          draggedClip={next.draggedClip ?? null}
+          draggedElement={null}
+          multiDragPreview={next.multiDragPreview ?? null}
+          blockedClipRef={createRef<BlockedClipState | null>()}
+          suppressClickRef={{ current: false }}
+          scrollRef={createRef<HTMLDivElement>()}
+          setHoveredClip={vi.fn()}
+          setShowPopover={vi.fn()}
+          setRangeSelection={vi.fn()}
+          setResizingClip={vi.fn()}
+          setDraggedClip={vi.fn()}
+          setSelectedElementId={vi.fn()}
+          syncClipDragAutoScroll={vi.fn()}
+          shiftClickClipRef={createRef()}
+          getPreviewElement={(el) => el}
+          getTrackStyle={getTrackStyle}
+          gsapAnimations={gsapAnimations}
+          selectedKeyframes={new Set()}
+          currentTime={0}
+          onContextMenuLane={next.onContextMenuLane}
+          onToggleTrackHidden={next.onToggleTrackHidden}
+          onTogglePropertyGroupKeyframe={vi.fn()}
+          onResizeElement={vi.fn()}
+          onMoveElement={vi.fn()}
+          onRazorSplit={vi.fn()}
+          onRazorSplitAll={vi.fn()}
+        />,
+      );
+    });
+  };
+  render(options);
+  return { host, root, rerender: render };
+}
+
+function visibilityLabels(host: HTMLElement): (string | null)[] {
+  return Array.from(host.querySelectorAll("button[aria-label^='Hide track ']")).map((button) =>
+    button.getAttribute("aria-label"),
+  );
+}
+
+describe("TimelineLanes track numbering", () => {
+  // Screen readers literally announced "Hide track 0.16666666666666666".
+  it("numbers tracks contiguously from 1 regardless of the fractional sort keys", () => {
+    const view = renderLanes({
+      elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+    });
+
+    expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
+    expect(view.host.innerHTML).not.toContain("0.16666666666666666");
+    act(() => view.root.unmount());
+  });
+
+  it("hands the visibility toggle the real track key, not the display index", () => {
+    const onToggleTrackHidden = vi.fn();
+    const view = renderLanes({
+      elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+      onToggleTrackHidden,
+    });
+
+    const second = view.host.querySelector<HTMLButtonElement>('button[aria-label="Hide track 2"]');
+    act(() => second?.click());
+
+    expect(onToggleTrackHidden).toHaveBeenCalledWith(TRACK_B, true);
+    act(() => view.root.unmount());
+  });
+
+  // The gap menu inserts at the track it is given, so a display index here would
+  // drop the new clip on the wrong lane.
+  it("hands the lane context menu the real track key, not the display index", () => {
+    const onContextMenuLane = vi.fn();
+    const view = renderLanes({
+      elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+      onContextMenuLane,
+    });
+
+    // Row children: [sticky header column, time-mapped track content].
+    const rows = Array.from(view.host.children);
+    const secondTrackContent = rows[1]?.children.item(1);
+    act(() => {
+      secondTrackContent?.dispatchEvent(
+        new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 100 }),
+      );
+    });
+
+    expect(onContextMenuLane).toHaveBeenCalledOnce();
+    expect(onContextMenuLane.mock.calls[0]?.[1]).toBe(TRACK_B);
+    act(() => view.root.unmount());
+  });
+});
+
+describe("TimelineLanes disclosure target", () => {
+  const ANIMATIONS = new Map([["clip-a", [positionTween("clip-a")]]]);
+
+  function ariaControlsTarget(host: HTMLElement): HTMLElement | null {
+    const caret = host.querySelector("button[aria-controls]");
+    const id = caret?.getAttribute("aria-controls");
+    return id ? host.querySelector<HTMLElement>(`#${id}`) : null;
+  }
+
+  // aria-controls used to name a div in the sticky label column: it computed to
+  // 0x0 and held no diamonds at all.
+  it("resolves the caret's aria-controls to an element holding the property lanes", () => {
+    const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+    const target = ariaControlsTarget(view.host);
+
+    expect(target).not.toBeNull();
+    expect(target?.querySelectorAll("[data-timeline-property-lane]").length).toBeGreaterThan(0);
+    act(() => view.root.unmount());
+  });
+
+  it("still resolves the caret's aria-controls while the layer is collapsed", () => {
+    const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: [] });
+    const target = ariaControlsTarget(view.host);
+
+    expect(target).not.toBeNull();
+    expect(target?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0);
+    act(() => view.root.unmount());
+  });
+
+  // Two timelines on one page (a mini-timeline in a modal beside the main one)
+  // both minted `timeline-lanes-track-0`, so every caret's aria-controls
+  // resolved to whichever instance mounted first.
+  it("mints lane ids that do not collide with a second TimelineLanes on the page", () => {
+    const first = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+    const second = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+
+    const idsFor = (host: HTMLElement) =>
+      Array.from(host.querySelectorAll("button[aria-controls]")).map((caret) =>
+        caret.getAttribute("aria-controls"),
+      );
+    const firstIds = idsFor(first.host);
+    const secondIds = idsFor(second.host);
+
+    expect(firstIds.length).toBeGreaterThan(0);
+    expect(firstIds.some((id) => secondIds.includes(id))).toBe(false);
+    // Still a legal CSS id selector: the aria-controls lookups above use `#id`.
+    for (const id of [...firstIds, ...secondIds]) {
+      expect(id).toMatch(/^[A-Za-z][\w-]*$/);
+    }
+    act(() => first.root.unmount());
+    act(() => second.root.unmount());
+  });
+
+  // The passenger branch wraps [clip, lanes] in a transformed div that re-renders
+  // on every pointer move. An unstable key there remounts the lanes and drops the
+  // in-flight drag.
+  it("does not remount the lanes while a multi-clip drag slides the formation", () => {
+    const elements = [element("clip-a", TRACK_A), element("clip-b", TRACK_A)];
+    const selectedElementIds = new Set(["clip-a", "clip-b"]);
+    const preview = (draggedPreviewStart: number): MultiDragPreviewInput => ({
+      dragStarted: true,
+      draggedKey: "clip-b",
+      draggedOriginStart: 0,
+      draggedPreviewStart,
+      selectedKeys: selectedElementIds,
+    });
+    const view = renderLanes({
+      elements,
+      animations: ANIMATIONS,
+      expandedClipIds: ["clip-a"],
+      selectedElementIds,
+      multiDragPreview: preview(0.25),
+    });
+
+    const before = ariaControlsTarget(view.host);
+    const beforeLane = before?.querySelector("[data-timeline-property-lane]");
+    expect(before).not.toBeNull();
+    expect(beforeLane).not.toBeNull();
+
+    view.rerender({
+      elements,
+      animations: ANIMATIONS,
+      expandedClipIds: ["clip-a"],
+      selectedElementIds,
+      multiDragPreview: preview(0.75),
+    });
+
+    // Node identity, not just presence: a remount replaces these nodes.
+    expect(ariaControlsTarget(view.host)).toBe(before);
+    expect(before?.querySelector("[data-timeline-property-lane]")).toBe(beforeLane);
+    act(() => view.root.unmount());
+  });
+});

package/src/player/components/TimelineLanes.tsx

@@ -1,28 +1,21 @@
-import { type ReactNode } from "react";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { useId } from "react";
 import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
 import { TimelineClip } from "./TimelineClip";
 import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
 import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
 import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
-import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
-import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
+import { trackDisplayNumber, trackDisplaySuffix } from "./timelineTrackDisplay";
+import { clipTimingStart } from "../../hooks/gsapShared";
 import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
-import type { TimelineTheme } from "./timelineTheme";
 import { CLIP_Y, CLIP_HANDLE_W, TRACK_H, getTimelineRowHeight } from "./timelineLayout";
-import {
-  usePlayerStore,
-  type TimelineElement,
-  type KeyframeCacheEntry,
-} from "../store/playerStore";
-import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import {
   isMultiDragPassenger,
   multiDragPassengerOffsetPx,
   type MultiDragPreviewInput,
 } from "./timelineMultiDragPreview";
-import type { TrackVisualStyle } from "./timelineIcons";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
 import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
@@ -30,83 +23,6 @@ import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
 import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
 import { renderClipChildren } from "./timelineClipChildren";
 
-/**
- * Props shared by the scroll container ({@link TimelineCanvas}) and the lane
- * renderer below. TimelineCanvas passes these straight through via spread, so
- * they are declared once here and both prop types compose from this base — no
- * duplicated prop list.
- */
-export interface TimelineLaneBaseProps {
-  pps: number;
-  contentOrigin: number;
-  contentGutter: number;
-  trackContentWidth: number;
-  theme: TimelineTheme;
-  displayTrackOrder: number[];
-  rowHeights: readonly number[];
-  trackOrder: number[];
-  tracks: [number, TimelineElement[]][];
-  trackStyles: Map<number, TrackVisualStyle>;
-  laneCounts: ReadonlyMap<string, number>;
-  selectedElementId: string | null;
-  selectedElementIds: Set<string>;
-  hoveredClip: string | null;
-  draggedClip: DraggedClipState | null;
-  blockedClipRef: React.RefObject<BlockedClipState | null>;
-  suppressClickRef: React.RefObject<boolean>;
-  scrollRef: React.RefObject<HTMLDivElement | null>;
-  renderClipContent?: (
-    element: TimelineElement,
-    style: { clip: string; label: string },
-  ) => ReactNode;
-  renderClipOverlay?: (element: TimelineElement) => ReactNode;
-  onDrillDown?: (element: TimelineElement) => void;
-  onSelectElement?: (element: TimelineElement | null) => void;
-  setHoveredClip: (key: string | null) => void;
-  setShowPopover: (v: boolean) => void;
-  setRangeSelection: (v: null) => void;
-  setResizingClip: (v: ResizingClipState | null) => void;
-  setDraggedClip: (v: DraggedClipState | null) => void;
-  setSelectedElementId: (id: string | null) => void;
-  syncClipDragAutoScroll: (x: number, y: number) => void;
-  shiftClickClipRef: React.RefObject<{
-    element: TimelineElement;
-    anchorX: number;
-    anchorY: number;
-  } | null>;
-  getPreviewElement: (element: TimelineElement) => TimelineElement;
-  getTrackStyle: (tag: string) => TrackVisualStyle;
-  keyframeCache?: Map<string, KeyframeCacheEntry>;
-  gsapAnimations: Map<string, GsapAnimation[]>;
-  selectedKeyframes: Set<string>;
-  currentTime: number;
-  onSeek?: (time: number) => void;
-  onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
-  onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
-  onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
-  onContextMenuKeyframe?: (
-    e: React.MouseEvent,
-    elementId: string,
-    target: TimelineKeyframeTarget,
-  ) => void;
-  onMoveKeyframe?: (
-    elementId: string,
-    keyframe: TimelineKeyframeTarget,
-    toClipPercentage: number,
-    propertyGroup?: string,
-    tweenPercentage?: number,
-    animationId?: string,
-  ) => Promise<boolean>;
-  onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
-  /**
-   * Right-click on EMPTY lane space (not on a clip — those preventDefault
-   * before this fires — not the gutter/ruler, not below the lanes). `time` is
-   * the timeline time (seconds) under the pointer on that lane.
-   */
-  onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
-  beatAnalysis?: MusicBeatAnalysis | null;
-}
-
 interface TimelineLanesProps extends TimelineLaneBaseProps {
   /** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
   draggedElement: TimelineElement | null;
@@ -174,6 +90,12 @@ export function TimelineLanes({
   onRazorSplit,
   onRazorSplitAll,
 }: TimelineLanesProps) {
+  // Per-INSTANCE, so two timelines on one page (a mini-timeline in a modal
+  // beside the main one) cannot both mint `...-track-0` and have every caret's
+  // aria-controls resolve to whichever mounted first. React's useId embeds
+  // colons, which are legal in an id and in aria-controls but need escaping in
+  // a CSS `#id` selector, so they come out here and the prefix stays plain.
+  const lanesIdPrefix = `timeline-lanes${useId().replaceAll(":", "")}`;
   const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
   const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
   const toggleClipExpandedTracked = (key: string) => {
@@ -191,6 +113,7 @@ export function TimelineLanes({
         // in a virtualizer if editorial workflows ever push very high clip counts.
         // fallow-ignore-next-line complexity
         displayTrackOrder.map((trackNum, row) => {
+          const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
           const rowHeight = getTimelineRowHeight(row, rowHeights);
           const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
           const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
@@ -217,6 +140,11 @@ export function TimelineLanes({
           const keyframeClipKey = keyframeClip?.key ?? keyframeClip?.id;
           const keyframeClipExpanded =
             keyframeClipKey != null && expandedClipIds.has(keyframeClipKey);
+          // Minted here because this is the only place that sees BOTH ends of
+          // the disclosure: the caret in the sticky header and the diamond lanes
+          // on the canvas. Keyed by display row, not by `trackNum`, which is a
+          // fractional sort key and would mint ids like `...-0.16666666666666666`.
+          const lanesId = `${lanesIdPrefix}-track-${row}`;
           return (
             <div
               key={trackNum}
@@ -229,7 +157,16 @@ export function TimelineLanes({
             >
               <TimelineTrackHeader
                 trackNumber={trackNum}
-                trackLabel={els[0]?.label ?? els[0]?.domId ?? els[0]?.id ?? `Track ${trackNum}`}
+                // What gets announced. `trackNum` is a fractional z-order sort
+                // key, so it stays out of every label and in every callback.
+                trackDisplayNumber={displayNumber}
+                trackLabel={
+                  els[0]?.label ??
+                  els[0]?.domId ??
+                  els[0]?.id ??
+                  `Track${trackDisplaySuffix(displayNumber)}`
+                }
+                lanesId={lanesId}
                 contentOrigin={contentOrigin}
                 keyframeClip={keyframeClip}
                 clipCount={els.length}
@@ -312,10 +249,9 @@ export function TimelineLanes({
                     // Only the track's active keyframe clip shows expanded lanes;
                     // other clips (incl. siblings on a shared track) show compact
                     // diamonds on their own bar instead.
-                    const showsLanes =
-                      STUDIO_KEYFRAMES_ENABLED &&
-                      elementKey === keyframeClipKey &&
-                      keyframeClipExpanded;
+                    const isTrackKeyframeClip =
+                      STUDIO_KEYFRAMES_ENABLED && elementKey === keyframeClipKey;
+                    const showsLanes = isTrackKeyframeClip && keyframeClipExpanded;
                     const capabilities = getTimelineEditCapabilities(el);
                     const isSelected =
                       selectedElementId === elementKey || selectedElementIds.has(elementKey);
@@ -523,11 +459,21 @@ export function TimelineLanes({
                           )}
                       </TimelineClip>
                     );
-                    const propertyLanes = showsLanes && (
+                    // Mounted for the track's keyframe clip in BOTH disclosure
+                    // states, so the header caret's aria-controls resolves while
+                    // collapsed too; collapsed just feeds it no animations, so
+                    // the wrapper renders empty. The key is stable across a
+                    // multi-drag: without it the passenger branch below remounts
+                    // this subtree and interrupts the gesture.
+                    const propertyLanes = isTrackKeyframeClip && (
                       <TimelinePropertyLanes
                         key={`${clipKey}-property-lanes`}
-                        animations={gsapAnimations.get(elementKey) ?? []}
-                        clipStart={previewElement.start}
+                        id={lanesId}
+                        animations={showsLanes ? (gsapAnimations.get(elementKey) ?? []) : []}
+                        // clipTimingStart, not the raw start: an expanded sub-comp
+                        // child's start is host-absolute while its tweens are
+                        // local to its own file.
+                        clipStart={clipTimingStart(previewElement)}
                         clipDuration={previewElement.duration}
                         clipLeftPx={previewElement.start * pps}
                         clipWidthPx={Math.max(previewElement.duration * pps, 4)}