@hyperframes/studio 0.8.55 → 0.8.57

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

@@ -5,7 +5,7 @@ import { createRoot, type Root } from "react-dom/client";
 import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
-import { TimelineTrackHeader } from "./TimelineTrackHeader";
+import { TimelineTrackHeader, gutterFill } from "./TimelineTrackHeader";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { type TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -794,10 +794,6 @@ describe("TimelineTrackHeader", () => {
       });
       expect(header()?.style.paddingLeft).toBe("14px");
       expect(header()?.style.borderLeft).toContain("2px");
-      // And a lighter gutter, so the row reads as sitting INSIDE its group
-      // rather than beside it. Overlaid on the theme's own fill rather than a
-      // hard-coded colour, so it follows whatever the gutter is.
-      expect(header()?.style.background).toContain("linear-gradient");
       act(() => view.root.unmount());
     });
 
@@ -912,3 +908,28 @@ describe("TimelineTrackHeader", () => {
     });
   });
 });
+
+// A host themes the timeline by overriding --timeline-* on theme.css, so the
+// rendered gutter must carry the CSS variable, not a baked-in colour.
+describe("theming", () => {
+  it("reads the gutter background and border from timeline theme tokens", () => {
+    const view = renderHeader({});
+    const header = view.host.querySelector<HTMLElement>('[role="rowheader"]');
+    expect(header?.style.background).toBe(defaultTimelineTheme.gutterBackground);
+    expect(header?.style.background).toContain("var(--timeline-gutter-bg)");
+    expect(header?.style.borderRight).toContain(defaultTimelineTheme.gutterBorder);
+    act(() => view.root.unmount());
+  });
+
+  // happy-dom's `background` shorthand garbles a `var()` layer next to
+  // `linear-gradient(...)` (verified), so this checks the same value through
+  // the pure function instead of the broken CSSOM roundtrip.
+  it("overlays the group-member tint on the themed gutter, not a hard-coded colour", () => {
+    const filled = gutterFill(defaultTimelineTheme.gutterBackground, true);
+    expect(filled).toContain("linear-gradient");
+    expect(filled.endsWith(defaultTimelineTheme.gutterBackground)).toBe(true);
+    expect(gutterFill(defaultTimelineTheme.gutterBackground, false)).toBe(
+      defaultTimelineTheme.gutterBackground,
+    );
+  });
+});

package/src/player/components/TimelineTrackHeader.tsx

@@ -34,7 +34,7 @@ const GROUP_MEMBER_INDENT = 14;
 const GROUP_MEMBER_TINT = "rgba(255,255,255,0.035)";
 
 /** The gutter fill for a row, tinted when it belongs to a group. */
-function gutterFill(base: string, isGroupMember: boolean): string {
+export function gutterFill(base: string, isGroupMember: boolean): string {
   return isGroupMember
     ? `linear-gradient(${GROUP_MEMBER_TINT}, ${GROUP_MEMBER_TINT}), ${base}`
     : base;

package/src/player/components/testRootHarness.ts

@@ -0,0 +1,18 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach } from "vitest";
+
+export function createHappyDomRootHarness() {
+  const roots: Root[] = [];
+  afterEach(() => {
+    for (const root of roots.splice(0)) act(() => root.unmount());
+    document.body.innerHTML = "";
+  });
+  return {
+    mount(host: HTMLElement) {
+      const root = createRoot(host);
+      roots.push(root);
+      return root;
+    },
+  };
+}

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

@@ -75,11 +75,11 @@ describe("timeline motion styles", () => {
     const bloomOverlayRule = expectRule(studioCss, ".timeline-clip::before");
     const activeBloomOverlayRule = expectRule(studioCss, ".timeline-clip[data-active]::before");
 
-    expect(baseTimelineClipRule).toContain("background-color: rgba(255, 255, 255, 0.055)");
+    expect(baseTimelineClipRule).toContain("background-color: var(--clip-bg)");
     expect(activeTimelineClipRule).not.toContain("background: linear-gradient");
-    expect(activeTimelineClipRule).toContain("border-color: rgba(60, 230, 172, 0.55)");
+    expect(activeTimelineClipRule).toContain("border-color: var(--clip-border-active)");
     expect(activeTimelineClipRule).not.toContain("box-shadow");
-    expect(bloomOverlayRule).toContain("background: rgba(60, 230, 172, 0.2)");
+    expect(bloomOverlayRule).toContain("background: var(--clip-bg-active)");
     expect(bloomOverlayRule).not.toContain("linear-gradient");
     expect(bloomOverlayRule).toContain("opacity: 0");
     expect(activeBloomOverlayRule).toContain("opacity: 1");

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

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  buildTimelineMeta,
+  resolveRenderClipContent,
+  resolveResizingElementIds,
+  shouldIgnoreTimelinePointerDown,
+  type TimelineMetaBuilderInputs,
+} from "./timelineProviderStateBuilders";
+
+function inputs(overrides: Partial<TimelineMetaBuilderInputs> = {}): TimelineMetaBuilderInputs {
+  return {
+    emptyState: {} as TimelineMetaBuilderInputs["emptyState"],
+    container: {
+      ref: vi.fn(),
+      "aria-label": "Timeline track view",
+      "data-timeline-element-count": 2,
+      isDragOver: false,
+      activeTool: "select",
+      shiftHeld: false,
+      accentClass: "ring",
+      onMouseMove: vi.fn(),
+      onMouseLeave: vi.fn(),
+      style: {},
+    },
+    viewport: {
+      ref: vi.fn(),
+      tabIndex: -1,
+      labelMode: false,
+      zoomMode: "fit",
+      onScroll: vi.fn(),
+      onFocus: vi.fn(),
+      onBlur: vi.fn(),
+      onDragOver: vi.fn(),
+      onDragLeave: vi.fn(),
+      onDrop: vi.fn(),
+      onPointerDown: vi.fn(),
+      onPointerMove: vi.fn(),
+      onPointerUp: vi.fn(),
+      onPointerCancel: vi.fn(),
+      onLostPointerCapture: vi.fn(),
+    },
+    elementCount: 2,
+    labelColumnWidth: 120,
+    razorGuide: null,
+    ...overrides,
+  };
+}
+
+describe("buildTimelineMeta", () => {
+  it("uses the razor branch for the container class", () => {
+    const meta = buildTimelineMeta(
+      inputs({
+        container: {
+          ...inputs().container,
+          activeTool: "razor",
+        },
+      }),
+    );
+    expect(meta.containerProps.className).toContain("cursor-crosshair");
+  });
+
+  it("uses the shift branch for the container class", () => {
+    const meta = buildTimelineMeta(
+      inputs({ container: { ...inputs().container, shiftHeld: true } }),
+    );
+    expect(meta.containerProps.className).toContain("cursor-crosshair");
+  });
+
+  it("uses the default container class without an accent", () => {
+    const meta = buildTimelineMeta(inputs());
+    expect(meta.containerProps.className).toContain("cursor-default");
+    expect(meta.containerProps.className).not.toContain("ring");
+  });
+
+  it("uses the label-column inset only in label mode", () => {
+    const fit = buildTimelineMeta(inputs());
+    const labels = buildTimelineMeta(
+      inputs({ viewport: { ...inputs().viewport, labelMode: true } }),
+    );
+    expect(fit.viewportProps["data-timeline-auto-scroll-left-inset"]).toBe(0);
+    expect(labels.viewportProps["data-timeline-auto-scroll-left-inset"]).toBe(120);
+  });
+});
+
+describe("timeline provider branch helpers", () => {
+  it("resolves virtualized clip content", () => {
+    const render = () => null;
+    expect(resolveRenderClipContent(true, true, render)).toBeUndefined();
+    expect(resolveRenderClipContent(false, true, render)).toBe(render);
+  });
+
+  it("resolves resizing element ids", () => {
+    expect(resolveResizingElementIds(null)).toBeUndefined();
+    expect(resolveResizingElementIds({ element: { id: "clip" } } as never)).toEqual(["clip"]);
+    expect(resolveResizingElementIds({ groupPreview: [{ key: "group::clip" }] } as never)).toEqual([
+      "group::clip",
+    ]);
+  });
+
+  it("ignores pointer downs on interactive descendants only", () => {
+    const button = document.createElement("button");
+    const div = document.createElement("div");
+    expect(shouldIgnoreTimelinePointerDown(button)).toBe(true);
+    expect(shouldIgnoreTimelinePointerDown(div)).toBe(false);
+    expect(shouldIgnoreTimelinePointerDown(null)).toBe(false);
+  });
+});

package/src/player/components/timelineProviderStateBuilders.ts

@@ -0,0 +1,83 @@
+import type {
+  TimelineMeta,
+  TimelineContainerProps,
+  TimelineViewportProps,
+} from "./TimelineProvider";
+import type { ResizingClipState } from "./useTimelineClipDrag";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
+
+export function resolveResizingElementIds(
+  resizingClip: ResizingClipState | null,
+): readonly string[] | undefined {
+  if (resizingClip?.groupPreview) return resizingClip.groupPreview.map((change) => change.key);
+  if (resizingClip) return [resizingClip.element.key ?? resizingClip.element.id];
+  return undefined;
+}
+
+export function resolveRenderClipContent(
+  rowVirtualizationActive: boolean,
+  isScrolling: boolean,
+  renderClipContent: TimelineLaneBaseProps["renderClipContent"],
+): TimelineLaneBaseProps["renderClipContent"] {
+  return rowVirtualizationActive && isScrolling ? undefined : renderClipContent;
+}
+
+export function shouldIgnoreTimelinePointerDown(target: EventTarget | null): boolean {
+  return target instanceof Element && target.closest("button, input, select, a") !== null;
+}
+
+type ContainerInputs = Omit<TimelineContainerProps, "className"> & {
+  isDragOver: boolean;
+  activeTool: string;
+  shiftHeld: boolean;
+  accentClass: string;
+};
+
+type ViewportInputs = Omit<
+  TimelineViewportProps,
+  "className" | "data-timeline-scroll-viewport" | "data-timeline-auto-scroll-left-inset"
+> & {
+  labelMode: boolean;
+  zoomMode: "fit" | "manual";
+};
+
+export interface TimelineMetaBuilderInputs {
+  emptyState: TimelineMeta["emptyState"];
+  container: ContainerInputs;
+  viewport: ViewportInputs;
+  elementCount: number;
+  labelColumnWidth: number;
+  razorGuide: TimelineMeta["razorGuide"];
+}
+
+export function buildTimelineMeta({
+  emptyState,
+  container,
+  viewport,
+  elementCount,
+  labelColumnWidth,
+  razorGuide,
+}: TimelineMetaBuilderInputs): TimelineMeta {
+  const { labelMode, zoomMode, ...viewportProps } = viewport;
+  const containerClassName = `relative border-t select-none h-full overflow-hidden ${container.isDragOver ? container.accentClass : ""} ${container.activeTool === "razor" ? "cursor-crosshair" : container.shiftHeld ? "cursor-crosshair" : "cursor-default"}`;
+  const viewportClassName = `${zoomMode === "fit" ? "overflow-x-hidden" : "overflow-x-auto"} overflow-y-auto h-full outline-hidden`;
+  return {
+    emptyState,
+    containerProps: {
+      ref: container.ref,
+      "aria-label": container["aria-label"],
+      "data-timeline-element-count": elementCount,
+      className: containerClassName,
+      onMouseMove: container.onMouseMove,
+      onMouseLeave: container.onMouseLeave,
+      style: container.style,
+    },
+    viewportProps: {
+      ...viewportProps,
+      "data-timeline-scroll-viewport": true,
+      "data-timeline-auto-scroll-left-inset": labelMode ? labelColumnWidth : 0,
+      className: viewportClassName,
+    },
+    razorGuide,
+  };
+}

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

@@ -9,10 +9,10 @@ import { getTrackStyle } from "./timelineIcons";
 describe("getTimelineTrackStyle", () => {
   it("uses one neutral clip style for every timeline tag", () => {
     const expectedStyle = {
-      clip: "rgba(255,255,255,0.055)",
-      clipActive: "rgba(60,230,172,0.16)",
-      accent: "#3CE6AC",
-      label: "rgba(255,255,255,0.5)",
+      clip: "var(--timeline-track-clip-fill)",
+      clipActive: "var(--timeline-track-clip-active)",
+      accent: "var(--color-accent)",
+      label: "var(--timeline-track-label)",
     };
 
     expect(getTimelineTrackStyle("video")).toEqual(expectedStyle);

package/src/player/components/timelineTheme.ts

@@ -22,6 +22,8 @@ export interface TimelineTheme {
   tickMinor: string;
   clipBackground: string;
   clipBackgroundActive: string;
+  clipBackgroundHover: string;
+  clipBackgroundDragging: string;
   clipBorder: string;
   clipBorderHover: string;
   clipBorderActive: string;
@@ -36,43 +38,45 @@ export interface TimelineTheme {
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
-  clip: "rgba(255,255,255,0.055)",
-  clipActive: "rgba(60,230,172,0.16)",
-  accent: "#3CE6AC",
-  label: "rgba(255,255,255,0.5)",
+  clip: "var(--timeline-track-clip-fill)",
+  clipActive: "var(--timeline-track-clip-active)",
+  accent: "var(--color-accent)",
+  label: "var(--timeline-track-label)",
 };
 
+// Every field reads a CSS custom property (declared in styles/theme.css)
+// rather than a literal, so a host themes the timeline the same way it
+// themes the rest of Studio: by overriding the token, not this object.
 export const defaultTimelineTheme: TimelineTheme = {
-  // Near-black card surfaces: the panels sit dark while the shell canvas
-  // between them is a step LIGHTER (#18181B), so the gaps read as visible
-  // seams around dark cards (CapCut-style).
-  shellBackground: "#0A0A0B",
-  shellBorder: "rgba(255,255,255,0.05)",
-  rulerBorder: "rgba(255,255,255,0.16)",
-  // All track lanes use a single uniform color — one step lighter than the panel
-  // surface (#0A0A0B) so lanes are visibly distinct from the ruler/shell.
-  rowBackground: "#101014",
-  rowBorder: "rgba(255,255,255,0.06)",
-  gutterBackground: "#0E0F12",
-  gutterBorder: "rgba(255,255,255,0.10)",
-  textPrimary: "rgba(255,255,255,0.92)",
-  textSecondary: "rgba(255,255,255,0.62)",
-  tickText: "rgba(255,255,255,0.34)",
-  tickMajor: "rgba(255,255,255,0.10)",
-  tickMinor: "rgba(255,255,255,0.06)",
-  clipBackground: "#141922",
-  clipBackgroundActive: "#181e28",
-  clipBorder: "rgba(255,255,255,0.10)",
-  clipBorderHover: "rgba(255,255,255,0.18)",
-  clipBorderActive: "rgba(255,255,255,0.24)",
+  shellBackground: "var(--timeline-shell-bg)",
+  shellBorder: "var(--timeline-shell-border)",
+  rulerBorder: "var(--timeline-ruler-border)",
+  rowBackground: "var(--timeline-row-bg)",
+  rowBorder: "var(--timeline-row-border)",
+  gutterBackground: "var(--timeline-gutter-bg)",
+  gutterBorder: "var(--timeline-gutter-border)",
+  textPrimary: "var(--timeline-text-primary)",
+  textSecondary: "var(--timeline-text-secondary)",
+  tickText: "var(--timeline-tick-text)",
+  tickMajor: "var(--timeline-tick-major)",
+  tickMinor: "var(--timeline-tick-minor)",
+  clipBackground: "var(--timeline-clip-bg)",
+  clipBackgroundActive: "var(--timeline-clip-bg-active)",
+  clipBackgroundHover: "var(--timeline-clip-bg-hover)",
+  clipBackgroundDragging: "var(--timeline-clip-bg-dragging)",
+  clipBorder: "var(--timeline-clip-border)",
+  clipBorderHover: "var(--timeline-clip-border-hover)",
+  clipBorderActive: "var(--timeline-clip-border-active)",
+  // Shadows stay literal: a light host still wants a dark contact shadow, so
+  // these are not part of the surface/hairline/text/clip-colour theming ask.
   clipShadow: "none",
   clipShadowHover: "0 2px 8px rgba(0,0,0,0.2)",
   clipShadowActive: "0 2px 8px rgba(0,0,0,0.2), 0 0 0 1px rgba(255,255,255,0.04)",
   clipShadowDragging: "0 8px 24px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.06)",
-  handleColor: "rgba(255,255,255,0.2)",
-  panelResizeSeam: "rgba(255,255,255,0.12)",
-  panelResizeActive: "rgba(255,255,255,0.24)",
-  clipRadius: "8px",
+  handleColor: "var(--timeline-handle)",
+  panelResizeSeam: "var(--timeline-resize-seam)",
+  panelResizeActive: "var(--timeline-resize-active)",
+  clipRadius: "var(--radius-lg)",
 };
 
 export function getTimelineTrackStyle(_tag: string): TimelineTrackStyle {

package/src/player/components/timelineTrackDisplay.ts

@@ -1,10 +1,7 @@
 /**
  * The one owner of "what track number does the user see".
  *
- * `TimelineElement.track` is a z-order SORT key, not a row number: an expanded
- * sub-composition child gets a synthesized fractional key (`host.track + n /
- * (siblings + 2)`, see `useTimelineRowElements`), so putting it in a string
- * announces "Hide track 0.16666666666666666". Every user-visible track number,
+ * `TimelineElement.track` is a z-order SORT key, not a row number. Every
  * whether it is rendered by a component or baked into an undo-history label,
  * routes through here; the raw key stays in callbacks and lookups only.
  */

package/src/player/components/useTimelineClipContextMenu.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import type { ClipContextMenuState } from "./TimelineOverlays";
+import type { ClipContextMenuState } from "./TimelineProvider";
 
 /** A clicked member of an active multi-selection keeps the whole group
  *  selected, so the context menu it opens acts on all of it. */

package/src/player/components/useTimelineOverlaysState.ts

@@ -0,0 +1,100 @@
+import type { TimelineElement } from "../store/playerStore";
+import type { TimelineOverlaysState } from "./TimelineProvider";
+import type { TimelineTimeRange } from "../store/rangeSelectionSlice";
+import { useClipContextMenu } from "./useTimelineClipContextMenu";
+import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { usePublishRangeSelection } from "./usePublishRangeSelection";
+import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
+import { useTrackGapMenu, type TrackGapHighlight } from "./useTrackGapMenu";
+
+type OverlayStateInputs = Omit<
+  TimelineOverlaysState,
+  | "elements"
+  | "elementsRef"
+  | "gapContextMenu"
+  | "onDismissGapContextMenu"
+  | "onCloseTrackGap"
+  | "onCloseAllTrackGaps"
+  | "onHoverGapAction"
+  | "rangeSelection"
+  | "setRangeSelection"
+> & {
+  elements: TimelineElement[];
+  elementsRef: { current: TimelineElement[] };
+  rangeSelection: Parameters<typeof useTimelineRangeSelection>[0] & {
+    onRangeSelect?: (range: TimelineTimeRange | null) => void;
+  };
+  gapMenu: Parameters<typeof useTrackGapMenu>[0];
+  onSelectElement: ((element: TimelineElement | null) => void) | undefined;
+  selectedElementId: string | null;
+  setRangeSelectionRef: { current: ((selection: null) => void) | null };
+};
+
+export type TimelineOverlaysStateResult = {
+  overlays: TimelineOverlaysState;
+  shiftClickClipRef: ReturnType<typeof useTimelineRangeSelection>["shiftClickClipRef"];
+  marqueeRect: ReturnType<typeof useTimelineRangeSelection>["marqueeRect"];
+  isScrubbing: ReturnType<typeof useTimelineRangeSelection>["isScrubbing"];
+  handlePointerDown: ReturnType<typeof useTimelineRangeSelection>["handlePointerDown"];
+  handlePointerMove: ReturnType<typeof useTimelineRangeSelection>["handlePointerMove"];
+  handlePointerUp: ReturnType<typeof useTimelineRangeSelection>["handlePointerUp"];
+  handlePointerCancel: ReturnType<typeof useTimelineRangeSelection>["handlePointerCancel"];
+  gapHighlight: TrackGapHighlight | null;
+  openGapMenu: ReturnType<typeof useTrackGapMenu>["openGapMenu"];
+  onContextMenuClip: ReturnType<typeof useClipContextMenu>;
+};
+
+export function useTimelineOverlaysState({
+  gapMenu,
+  rangeSelection: rangeSelectionInputs,
+  onSelectElement,
+  selectedElementId,
+  setRangeSelectionRef,
+  ...state
+}: OverlayStateInputs): TimelineOverlaysStateResult {
+  const {
+    rangeSelection,
+    setRangeSelection,
+    shiftClickClipRef,
+    marqueeRect,
+    isScrubbing,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handlePointerCancel,
+  } = useTimelineRangeSelection(rangeSelectionInputs);
+  usePublishRangeSelection(rangeSelection, rangeSelectionInputs.onRangeSelect);
+  setRangeSelectionRef.current = () => setRangeSelection(null); // oxlint-disable-line react/refs -- stable ref consumed by useTimelineClipDrag
+  useTimelineSelectionLifecycle(state.elements, selectedElementId, state.setShowPopover, () =>
+    setRangeSelection(null),
+  );
+  const gap = useTrackGapMenu(gapMenu);
+  const onContextMenuClip = useClipContextMenu(
+    onSelectElement,
+    gap.dismissGapMenu,
+    state.setClipContextMenu,
+  );
+
+  return {
+    overlays: {
+      ...state,
+      rangeSelection,
+      setRangeSelection,
+      gapContextMenu: gap.gapMenuModel,
+      onDismissGapContextMenu: gap.dismissGapMenu,
+      onCloseTrackGap: gap.closeTrackGap,
+      onCloseAllTrackGaps: gap.closeAllTrackGaps,
+      onHoverGapAction: gap.setHoveredGapAction,
+    },
+    shiftClickClipRef,
+    marqueeRect,
+    isScrubbing,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handlePointerCancel,
+    gapHighlight: gap.gapHighlight,
+    openGapMenu: gap.openGapMenu,
+    onContextMenuClip,
+  };
+}