@hyperframes/studio 0.7.92 → 0.7.93

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

@@ -1,139 +0,0 @@
-// @vitest-environment happy-dom
-
-import React, { act, useRef } from "react";
-import { createRoot, type Root } from "react-dom/client";
-import { afterEach, describe, expect, it } from "vitest";
-import type { TimelineElement } from "../store/playerStore";
-import { usePlayerStore } from "../store/playerStore";
-import { createTimelineRowGeometry } from "./timelineLayout";
-import { useTimelineRevealClip } from "./useTimelineRevealClip";
-
-Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
-
-const element: TimelineElement = {
-  id: "hero",
-  tag: "div",
-  start: 20,
-  duration: 2,
-  track: 1,
-};
-const geometry = createTimelineRowGeometry([1], [48]);
-
-function createHarnessRoot() {
-  const host = document.createElement("div");
-  document.body.append(host);
-  return { host, root: createRoot(host) };
-}
-
-interface HarnessProps {
-  mounted: boolean;
-  version: number;
-  width?: number;
-  height?: number;
-  deferFocusUntilViewportUpdate?: boolean;
-  focusedElementId?: string;
-}
-
-function Harness({
-  mounted,
-  version,
-  width = 300,
-  height = 100,
-  deferFocusUntilViewportUpdate = false,
-  focusedElementId,
-}: HarnessProps) {
-  const scrollRef = useRef<HTMLDivElement>(null);
-  useTimelineRevealClip({
-    scrollRef,
-    elements: [element],
-    rowGeometry: geometry,
-    pixelsPerSecond: 100,
-    contentOrigin: 32,
-    allowHorizontal: true,
-    deferFocusUntilViewportUpdate,
-    focusedElementId,
-    viewportVersion: version,
-    sessionEpoch: 1,
-  });
-  return (
-    <div
-      ref={(node) => {
-        scrollRef.current = node;
-        if (node) {
-          Object.defineProperty(node, "clientWidth", { configurable: true, value: width });
-          Object.defineProperty(node, "clientHeight", { configurable: true, value: height });
-        }
-      }}
-    >
-      {mounted && <div data-el-id="hero" tabIndex={-1} />}
-    </div>
-  );
-}
-
-async function renderHarness(root: Root, props: HarnessProps): Promise<void> {
-  await act(async () => root.render(<Harness {...props} />));
-}
-
-afterEach(() => {
-  usePlayerStore.getState().reset();
-  document.body.replaceChildren();
-});
-
-describe("useTimelineRevealClip", () => {
-  it("scrolls from model coordinates, then consumes only after the clip mounts", async () => {
-    const { host, root } = createHarnessRoot();
-    usePlayerStore.getState().requestClipReveal("hero");
-
-    await renderHarness(root, { mounted: false, version: 0 });
-    const scroll = host.firstElementChild as HTMLDivElement;
-    expect(scroll.scrollLeft).toBe(1_944);
-    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
-
-    await renderHarness(root, { mounted: true, version: 1 });
-    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-    expect(document.activeElement?.getAttribute("data-el-id")).toBe("hero");
-
-    scroll.scrollLeft = 0;
-    await act(async () => usePlayerStore.getState().requestClipReveal("hero"));
-    await renderHarness(root, { mounted: true, version: 2 });
-    expect(scroll.scrollLeft).toBe(1_944);
-    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-    await act(async () => root.unmount());
-  });
-
-  it("consumes an invalid target without scrolling", async () => {
-    const { root } = createHarnessRoot();
-    usePlayerStore.getState().requestClipReveal("missing");
-    await renderHarness(root, { mounted: false, version: 0 });
-    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-    await act(async () => root.unmount());
-  });
-
-  it("keeps a reveal pending through zero-size viewport and virtualized focus handoff", async () => {
-    const { host, root } = createHarnessRoot();
-    usePlayerStore.getState().requestClipReveal("hero");
-
-    await renderHarness(root, { mounted: true, version: 0, width: 0, height: 0 });
-    const scroll = host.firstElementChild as HTMLDivElement;
-    expect(scroll.scrollLeft).toBe(0);
-    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
-    expect(document.activeElement?.getAttribute("data-el-id")).not.toBe("hero");
-
-    await renderHarness(root, {
-      mounted: true,
-      version: 1,
-      deferFocusUntilViewportUpdate: true,
-    });
-    expect(scroll.scrollLeft).toBe(1_944);
-    expect(usePlayerStore.getState().clipRevealRequest?.elementId).toBe("hero");
-    await renderHarness(root, {
-      mounted: true,
-      version: 2,
-      deferFocusUntilViewportUpdate: true,
-      focusedElementId: "hero",
-    });
-    expect(usePlayerStore.getState().clipRevealRequest).toBeNull();
-    expect(document.activeElement?.getAttribute("data-el-id")).toBe("hero");
-    await act(async () => root.unmount());
-  });
-});

package/src/player/components/useTimelineRevealClip.ts

@@ -1,180 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { TimelineElement } from "../store/playerStore";
-import { usePlayerStore } from "../store/playerStore";
-import { getTimelineElementIdentity } from "../lib/timelineElementHelpers";
-import { CLIP_Y, RULER_H, type TimelineRowGeometry } from "./timelineLayout";
-import { computeRevealScroll } from "./timelineRevealScroll";
-
-interface UseTimelineRevealClipInput {
-  scrollRef: React.RefObject<HTMLDivElement | null>;
-  elements: readonly TimelineElement[];
-  rowGeometry: TimelineRowGeometry;
-  pixelsPerSecond: number;
-  contentOrigin: number;
-  allowHorizontal: boolean;
-  deferFocusUntilViewportUpdate: boolean;
-  focusedElementId?: string;
-  viewportVersion: unknown;
-  sessionEpoch: number;
-}
-
-function escapeSelectorValue(value: string): string {
-  return typeof CSS !== "undefined" && typeof CSS.escape === "function"
-    ? CSS.escape(value)
-    : value.replace(/["\\]/g, "\\$&");
-}
-
-function scrollToTimelineElement(
-  container: HTMLDivElement,
-  element: TimelineElement,
-  row: number,
-  rowGeometry: TimelineRowGeometry,
-  pixelsPerSecond: number,
-  contentOrigin: number,
-  allowHorizontal: boolean,
-): boolean {
-  const clipLeft = contentOrigin + element.start * pixelsPerSecond;
-  const target = computeRevealScroll({
-    scrollLeft: container.scrollLeft,
-    scrollTop: container.scrollTop,
-    viewportWidth: container.clientWidth,
-    viewportHeight: container.clientHeight,
-    clipLeft,
-    clipRight: clipLeft + Math.max(element.duration * pixelsPerSecond, 4),
-    clipTop: rowGeometry.getRowTop(row) + CLIP_Y,
-    clipBottom: rowGeometry.getRowTop(row) + rowGeometry.getRowHeight(row) - CLIP_Y,
-    stickyLeft: contentOrigin,
-    stickyTop: RULER_H,
-    allowHorizontal,
-  });
-  if (target.left !== null) container.scrollLeft = target.left;
-  if (target.top !== null) container.scrollTop = target.top;
-  const didScroll = target.left !== null || target.top !== null;
-  if (didScroll) container.dispatchEvent(new Event("scroll"));
-  return didScroll;
-}
-
-function focusRevealedElement(container: HTMLDivElement, elementId: string): boolean {
-  const clip = container.querySelector(`[data-el-id="${escapeSelectorValue(elementId)}"]`);
-  if (!(clip instanceof HTMLElement)) return false;
-  const alreadyHighlighted = clip.hasAttribute("data-reveal-highlight");
-  clip.setAttribute("data-reveal-highlight", "true");
-  clip.focus({ preventScroll: true });
-  if (document.activeElement !== clip) {
-    clip.removeAttribute("data-reveal-highlight");
-    return false;
-  }
-  if (!alreadyHighlighted) {
-    clip.addEventListener("blur", () => clip.removeAttribute("data-reveal-highlight"), {
-      once: true,
-    });
-  }
-  return true;
-}
-
-function focusAndConsumeReveal(
-  container: HTMLDivElement,
-  request: { elementId: string; nonce: number },
-  deferUntilFocusPin: boolean,
-  focusedElementId?: string,
-): void {
-  if (!focusRevealedElement(container, request.elementId)) return;
-  if (deferUntilFocusPin && focusedElementId !== request.elementId) return;
-  if (usePlayerStore.getState().clipRevealRequest === request) {
-    usePlayerStore.getState().clearClipRevealRequest();
-  }
-}
-
-function resolveRevealTarget(
-  elements: readonly TimelineElement[],
-  rowGeometry: TimelineRowGeometry,
-  elementId: string,
-): { element: TimelineElement; row: number } | null {
-  const element = elements.find((candidate) => getTimelineElementIdentity(candidate) === elementId);
-  if (!element) return null;
-  const row = rowGeometry.getRowIndex(element.track);
-  return row < 0 ? null : { element, row };
-}
-
-function shouldScrollReveal(
-  previous: { request: { elementId: string; nonce: number }; sessionEpoch: number } | null,
-  request: { elementId: string; nonce: number },
-  sessionEpoch: number,
-): boolean {
-  return previous?.request !== request || previous.sessionEpoch !== sessionEpoch;
-}
-
-/** Coordinate-first reveal; the request remains pinned until its clip mounts. */
-export function useTimelineRevealClip({
-  scrollRef,
-  elements,
-  rowGeometry,
-  pixelsPerSecond,
-  contentOrigin,
-  allowHorizontal,
-  deferFocusUntilViewportUpdate,
-  focusedElementId,
-  viewportVersion,
-  sessionEpoch,
-}: UseTimelineRevealClipInput): void {
-  const revealRequest = usePlayerStore((state) => state.clipRevealRequest);
-  const scrolledRequestRef = useRef<{
-    request: { elementId: string; nonce: number };
-    sessionEpoch: number;
-  } | null>(null);
-
-  useEffect(() => {
-    if (!revealRequest) {
-      scrolledRequestRef.current = null;
-      return;
-    }
-    const target = resolveRevealTarget(elements, rowGeometry, revealRequest.elementId);
-    if (!target) {
-      usePlayerStore.getState().clearClipRevealRequest();
-      return;
-    }
-    const container = scrollRef.current;
-    if (!container) return;
-    if (container.clientWidth <= 0 || container.clientHeight <= 0) return;
-
-    if (shouldScrollReveal(scrolledRequestRef.current, revealRequest, sessionEpoch)) {
-      scrolledRequestRef.current = { request: revealRequest, sessionEpoch };
-      const didScroll = scrollToTimelineElement(
-        container,
-        target.element,
-        target.row,
-        rowGeometry,
-        pixelsPerSecond,
-        contentOrigin,
-        allowHorizontal,
-      );
-      // Keep the reveal pin alive until the scroll snapshot catches up. If the
-      // request were consumed here, horizontal windowing could unmount and
-      // recreate the focused clip between the programmatic scroll and the next
-      // viewport publication.
-      if (didScroll && deferFocusUntilViewportUpdate) return;
-    }
-
-    // Focus is the durable row/clip pin. Do not consume the reveal pin until
-    // the focus listener has published that replacement, or windowing can
-    // briefly unmount and recreate the element between the two owners.
-    focusAndConsumeReveal(
-      container,
-      revealRequest,
-      deferFocusUntilViewportUpdate,
-      focusedElementId,
-    );
-  }, [
-    allowHorizontal,
-    contentOrigin,
-    deferFocusUntilViewportUpdate,
-    elements,
-    focusedElementId,
-    pixelsPerSecond,
-    revealRequest,
-    rowGeometry,
-    scrollRef,
-    sessionEpoch,
-    viewportVersion,
-  ]);
-}