feat(studio): a host can hide the timeline's audio effects controls (#4704)

* feat(studio): a host can hide the timeline's audio effects controls

* test(studio): share the whole-timeline mount setup between timeline tests

* fix(studio): hidden audio effects also take the effect-rack shortcut off lane names

* test(studio): share the gain-automated group fixture

* test(studio): use the shared group fixture in every automated-group test

* fix(studio): a disabled group lane name does not light up on hover

* refactor(studio): keep the timeline provider and lanes under the file size limit

* refactor(studio): format the lanes row indexes within the size limit

Author: miguel-heygen

packages/studio/src/player/components/Timeline.audioEffects.test.tsx

@@ -0,0 +1,80 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+installTimelineMountEnv();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const voice: TimelineElement = {
+  id: "vo",
+  domId: "vo",
+  tag: "audio",
+  start: 0,
+  duration: 4,
+  track: 0,
+};
+const grouped: TimelineElement[] = ["vo-1", "vo-2"].map((id, track) => ({
+  id,
+  domId: id,
+  tag: "audio",
+  start: 0,
+  duration: 4,
+  track,
+  audioGroup: "voiceover",
+  audioGroupLabel: "Voiceover",
+}));
+
+async function mount(elements: TimelineElement[], showAudioEffects?: boolean) {
+  usePlayerStore.setState({ duration: 10, currentTime: 0, timelineReady: true, elements });
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  await act(async () => root.render(<Timeline showAudioEffects={showAudioEffects} />));
+  const labels = Array.from(host.querySelectorAll("button")).map(
+    (b) => b.getAttribute("aria-label") ?? "",
+  );
+  act(() => root.unmount());
+  return labels;
+}
+
+const effects = (labels: string[]) => labels.filter((l) => l.startsWith("Effects"));
+
+describe("Timeline showAudioEffects", () => {
+  it("shows the effects button on an audio track by default", async () => {
+    expect(effects(await mount([voice]))).toHaveLength(1);
+  });
+
+  it("hides the effects button on an audio track when the host turns effects off", async () => {
+    expect(effects(await mount([voice], false))).toEqual([]);
+  });
+
+  it("hides the group-these-clips effects button on a track of several clips", async () => {
+    const clips: TimelineElement[] = [
+      { ...voice, id: "sfx-1", domId: "sfx-1" },
+      { ...voice, id: "sfx-2", domId: "sfx-2", start: 5 },
+    ];
+    expect(effects(await mount(clips))).toHaveLength(1);
+    expect(effects(await mount(clips, false))).toEqual([]);
+  });
+
+  it("hides a group's effects button and its open-effects name when effects are off", async () => {
+    const on = await mount(grouped);
+    expect(effects(on).length).toBeGreaterThan(0);
+    expect(on).toContain("Open Voiceover effects");
+
+    const off = await mount(grouped, false);
+    expect(effects(off)).toEqual([]);
+    expect(off).not.toContain("Open Voiceover effects");
+    expect(off).toContain("Select Voiceover");
+  });
+});

packages/studio/src/player/components/Timeline.playheadRemount.test.tsx

@@ -2,38 +2,14 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import { Timeline } from "./Timeline";
+import { installTimelineMountEnv } from "./timelineMountTestEnv";
 import { liveTime, usePlayerStore } from "../store/playerStore";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-class MockResizeObserver {
-  constructor(private readonly callback: ResizeObserverCallback) {}
-  observe(target: Element) {
-    this.callback([{ target } as ResizeObserverEntry], this as unknown as ResizeObserver);
-  }
-  unobserve() {}
-  disconnect() {}
-}
-
-const originalResizeObserver = globalThis.ResizeObserver;
-const originalClientWidth = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "clientWidth");
-
-beforeAll(() => {
-  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
-  Object.defineProperty(HTMLElement.prototype, "clientWidth", {
-    configurable: true,
-    get: () => 900,
-  });
-});
-
-afterAll(() => {
-  globalThis.ResizeObserver = originalResizeObserver;
-  if (originalClientWidth)
-    Object.defineProperty(HTMLElement.prototype, "clientWidth", originalClientWidth);
-  document.body.innerHTML = "";
-});
+installTimelineMountEnv();
 
 const clips = [{ id: "intro", tag: "div", start: 2, duration: 10, track: 0 }];
 const needle = (host: HTMLElement) =>

packages/studio/src/player/components/TimelineGroupHeader.tsx

@@ -24,6 +24,7 @@ interface TimelineGroupHeaderProps {
   onOpenFxRack: () => void;
   columnWidth: number;
   theme: TimelineTheme;
+  showAudioEffects?: boolean;
 }
 
 /**
@@ -41,17 +42,19 @@ function GroupNameButton({
   label,
   memberCount,
   onOpenFxRack,
+  showAudioEffects,
 }: {
   label: string;
   memberCount: number;
   onOpenFxRack: () => void;
+  showAudioEffects: boolean;
 }) {
   return (
     <button
       type="button"
       tabIndex={-1}
-      aria-label={`Open ${label} effects`}
-      title="Open effects"
+      aria-label={showAudioEffects ? `Open ${label} effects` : `Select ${label}`}
+      title={showAudioEffects ? "Open effects" : "Select group"}
       // No `flex-1`: the row's control group owns the slack now (`ml-auto`), so
       // claiming it here would push the controls off the right edge — and the
       // count with them, since it rides inside this button.
@@ -97,6 +100,7 @@ export function TimelineGroupHeader({
   onOpenFxRack,
   columnWidth,
   theme,
+  showAudioEffects = true,
 }: TimelineGroupHeaderProps) {
   return (
     <div
@@ -137,17 +141,24 @@ export function TimelineGroupHeader({
               ▸ sits off-centre in its box because the glyph is not square. */}
         <span aria-hidden="true">{isExpanded ? "▾" : "▸"}</span>
       </button>
-      <GroupNameButton label={label} memberCount={memberCount} onOpenFxRack={onOpenFxRack} />
+      <GroupNameButton
+        label={label}
+        memberCount={memberCount}
+        onOpenFxRack={onOpenFxRack}
+        showAudioEffects={showAudioEffects}
+      />
       {/* `ml-auto` absorbs the slack the truncating name leaves, so the controls
           sit on the edge whatever the name's length. */}
       <div className="ml-auto flex shrink-0 items-center gap-1.5">
-        <TimelineFxButton
-          fxChainRaw={fxChain}
-          onChainChange={onFxChainChange}
-          onChainPreview={onFxChainPreview}
-          auditionSpans={auditionSpans}
-          onOpenRack={onOpenFxRack}
-        />
+        {showAudioEffects && (
+          <TimelineFxButton
+            fxChainRaw={fxChain}
+            onChainChange={onFxChainChange}
+            onChainPreview={onFxChainPreview}
+            auditionSpans={auditionSpans}
+            onOpenRack={onOpenFxRack}
+          />
+        )}
         {/* No lanes, no control: an author who opens it meets an empty row and
             learns nothing. A track header already gates its own `∿` this way
             (`disclosable`); the group's was the one that still offered a

packages/studio/src/player/components/TimelineGroupLaneLabels.tsx

@@ -63,8 +63,13 @@ export function TimelineGroupLaneLabels({
             tabIndex={-1}
             key={lane.target}
             data-group-lane-label={lane.target}
-            aria-label={`Show ${groupLabel} ${parts.name}${parts.param ? ` ${parts.param}` : ""} in the effect rack`}
-            className="absolute left-0 flex items-center gap-1.5 overflow-hidden border-0 px-1.5 text-left text-[10px] text-[var(--timeline-text-secondary)] hover:text-[var(--timeline-text-solid)] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[var(--timeline-accent)]"
+            aria-label={
+              onReveal
+                ? `Show ${groupLabel} ${parts.name}${parts.param ? ` ${parts.param}` : ""} in the effect rack`
+                : undefined
+            }
+            disabled={!onReveal}
+            className="absolute left-0 flex items-center gap-1.5 overflow-hidden border-0 px-1.5 text-left text-[10px] text-[var(--timeline-text-secondary)] enabled:hover:text-[var(--timeline-text-solid)] focus-visible:outline-solid focus-visible:outline-1 focus-visible:outline-[var(--timeline-accent)]"
             style={{
               top: top + index * AUTOMATION_LANE_H,
               width: columnWidth,

packages/studio/src/player/components/TimelineGroupRow.test.tsx

@@ -45,9 +45,21 @@ const GROUP: TimelineTrackGroupInfo = {
   hidden: false,
 };
 
+const GAIN_AUTOMATED: Partial<TimelineTrackGroupInfo> = {
+  fxChain: JSON.stringify({
+    version: 1,
+    nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
+  }),
+  automation: JSON.stringify({
+    version: 1,
+    lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
+  }),
+};
+
 function renderRow(
   overrides: Partial<TimelineTrackGroupInfo> = {},
   expandedLaneOwnerIds = new Set<string>(),
+  showAudioEffects?: boolean,
 ) {
   const onSetAudioGroupAttributeQuiet = vi.fn();
   const onSetElementAttributeQuiet = vi.fn();
@@ -66,6 +78,7 @@ function renderRow(
           virtualized={false}
           contentOrigin={232}
           theme={defaultTimelineTheme}
+          showAudioEffects={showAudioEffects}
           collapsedGroupIds={new Set()}
           expandedLaneOwnerIds={expandedLaneOwnerIds}
           toggleGroupExpanded={vi.fn()}
@@ -118,19 +131,7 @@ describe("TimelineGroupRow", () => {
   });
 
   it("opens a group automation lane on its exact rack parameter", async () => {
-    const { host } = renderRow(
-      {
-        fxChain: JSON.stringify({
-          version: 1,
-          nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-        }),
-        automation: JSON.stringify({
-          version: 1,
-          lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-        }),
-      },
-      new Set(["voiceover"]),
-    );
+    const { host } = renderRow(GAIN_AUTOMATED, new Set(["voiceover"]));
     const laneTitle = host.querySelector<HTMLButtonElement>('[data-group-lane-label="fx.p1.gain"]');
 
     await act(async () => {
@@ -147,6 +148,14 @@ describe("TimelineGroupRow", () => {
     });
   });
 
+  it("keeps a group lane's name off the rack while audio effects are hidden", () => {
+    const { host } = renderRow(GAIN_AUTOMATED, new Set(["voiceover"]), false);
+    const laneTitle = host.querySelector<HTMLButtonElement>('[data-group-lane-label="fx.p1.gain"]');
+
+    expect(laneTitle?.disabled).toBe(true);
+    expect(laneTitle?.getAttribute("aria-label")).toBeNull();
+  });
+
   // C1 names this as the step's own definition of done: "opening the popover on
   // a GROUP and applying a preset results in exactly ONE `data-fx-chain` write,
   // on the group element, and zero writes on members". A group IS a bus — a
@@ -180,33 +189,15 @@ describe("TimelineGroupRow", () => {
 
     expect(laneToggle(renderRow().host)).toBeUndefined();
 
-    const automated = renderRow({
-      fxChain: JSON.stringify({
-        version: 1,
-        nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-      }),
-      automation: JSON.stringify({
-        version: 1,
-        lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-      }),
-    });
+    const automated = renderRow(GAIN_AUTOMATED);
     expect(laneToggle(automated.host)).toBeDefined();
   });
 
   // Same shape as a track header: caret and name on the left, every control in
   // one right-anchored group. It was two lines — name, then controls — which is
   // what let a stray child overflow the 48px box on the track side.
   it("keeps the caret, the name and every control on one line", () => {
-    const { host } = renderRow({
-      fxChain: JSON.stringify({
-        version: 1,
-        nodes: [{ type: "peaking", id: "p1", params: { frequency: 1000, gain: -3, q: 1 } }],
-      }),
-      automation: JSON.stringify({
-        version: 1,
-        lanes: [{ target: "fx.p1.gain", points: [{ t: 0, v: 0 }] }],
-      }),
-    });
+    const { host } = renderRow(GAIN_AUTOMATED);
     const header = host.querySelector<HTMLElement>('[role="rowheader"]');
     // Caret, name, control group — no second line.
     expect(header?.children).toHaveLength(3);

packages/studio/src/player/components/TimelineGroupRow.tsx

@@ -33,6 +33,7 @@ interface TimelineGroupRowProps {
   virtualized: boolean;
   contentOrigin: number;
   theme: TimelineTheme;
+  showAudioEffects?: boolean;
   rovingTargetId?: string | null;
   collapsedGroupIds: ReadonlySet<string>;
   expandedLaneOwnerIds: ReadonlySet<string>;
@@ -59,6 +60,7 @@ export function TimelineGroupRow({
   virtualized,
   contentOrigin,
   theme,
+  showAudioEffects = true,
   rovingTargetId = null,
   collapsedGroupIds,
   expandedLaneOwnerIds,
@@ -173,6 +175,7 @@ export function TimelineGroupRow({
           // stays pinned there through horizontal scroll.
           columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
           theme={theme}
+          showAudioEffects={showAudioEffects}
         />
         {/* The group's OWN curves, under the strip. Selected-gated exactly like a
           clip's: a lane is editable once the group is selected, which clicking
@@ -187,7 +190,7 @@ export function TimelineGroupRow({
             columnWidth={contentOrigin >= LABEL_COL_W ? LABEL_COL_W : contentOrigin}
             gutterBackground={theme.gutterBackground}
             accentColor={GROUP_LANE_ACCENT}
-            onReveal={openGroupFxRack}
+            onReveal={showAudioEffects ? openGroupFxRack : undefined}
           />
         )}
       </div>

packages/studio/src/player/components/TimelineLanes.tsx

@@ -41,6 +41,7 @@ export function TimelineLanes({
   contentGutter,
   trackContentWidth,
   theme,
+  showAudioEffects,
   displayTrackOrder,
   rowGeometry,
   virtualRows,
@@ -115,11 +116,8 @@ export function TimelineLanes({
   // synthetic lane element spans the whole composition rather than a clip.
   const compositionDuration = usePlayerStore((s) => s.duration);
   useAutomationSelectionKeyboard({ lanes: automationLanes });
-  const { logicalRowsByTrack, groupByAnchor } = useTimelineLaneRowIndexes(logicalRows, groups);
-  const groupMemberTracks = useMemo(
-    () => new Set(groups.flatMap((group) => group.memberTracks)),
-    [groups],
-  );
+  const rowIndexes = useTimelineLaneRowIndexes(logicalRows, groups);
+  const { logicalRowsByTrack, groupByAnchor, groupMemberTracks } = rowIndexes;
   const {
     toggleRowExpanded: toggleRowExpandedTracked,
     toggleClipExpanded: toggleClipExpandedTracked,
@@ -168,6 +166,7 @@ export function TimelineLanes({
                 virtualized={rowsVirtualized}
                 contentOrigin={contentOrigin}
                 theme={theme}
+                showAudioEffects={showAudioEffects}
                 rovingTargetId={keyboard.rovingTargetId}
                 collapsedGroupIds={collapsedGroupIds}
                 expandedLaneOwnerIds={expandedLaneOwnerIds}
@@ -292,6 +291,7 @@ export function TimelineLanes({
                 isAudioTrack={isAudioTrack}
                 isGroupMember={groupMemberTracks.has(trackNum)}
                 theme={theme}
+                showAudioEffects={showAudioEffects}
                 onToggleClipExpanded={() => {
                   const keys = els.map(getTimelineElementIdentity);
                   if (keys.length > 0) toggleRowExpandedTracked(keys);