feat(studio): the Tone module — a multi-band EQ on faders

packages/studio/src/components/editor/propertyPanelFxEqModule.tsx

@@ -0,0 +1,191 @@
+/**
+ * The Tone module: a multi-band EQ as one control surface over several nodes.
+ *
+ * Faders rather than the rack's usual horizontal sliders, because a row of them
+ * around a centre detent is what an equaliser looks like to everybody who has
+ * met one. Recognising the control is most of the value — an author who has
+ * never opened a mixer has still used bass, middle and treble.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  audioEqSummary,
+  HF_AUDIO_EQ_RANGE_DB,
+  type HfAudioEqBand,
+} from "@hyperframes/core/audio-fx-eq";
+
+export interface FxEqModuleProps {
+  eqId: string;
+  bands: HfAudioEqBand[];
+  open: boolean;
+  disabled?: boolean;
+  onToggleOpen(): void;
+  /** Dragging: heard immediately, not persisted. */
+  onPreview(bandName: string, gain: number): void;
+  /** Release: the write that persists. */
+  onCommit(bandName: string, gain: number): void;
+  onRemove(): void;
+}
+
+/** Fader travel as a percentage from the top, with 0 dB at the centre. */
+function offsetFor(gain: number): number {
+  const clamped = Math.max(-HF_AUDIO_EQ_RANGE_DB, Math.min(HF_AUDIO_EQ_RANGE_DB, gain));
+  return 50 - (clamped / (HF_AUDIO_EQ_RANGE_DB * 2)) * 100;
+}
+
+const shown = (gain: number): string => {
+  const v = Number(gain.toFixed(1));
+  return v > 0 ? `+${v}` : String(v);
+};
+
+function Fader({
+  band,
+  disabled,
+  onPreview,
+  onCommit,
+}: {
+  band: HfAudioEqBand;
+  disabled?: boolean;
+  onPreview(gain: number): void;
+  onCommit(gain: number): void;
+}) {
+  /**
+   * Held locally for the length of the gesture.
+   *
+   * The module is driven by the chain, and dragging only PREVIEWS — it does
+   * not write — so a purely controlled input re-renders back to the old value
+   * on the first move and the fader snaps out from under the pointer. Same
+   * split the rack's other controls already make.
+   */
+  const [local, setLocal] = useState(band.gain);
+  const [dragging, setDragging] = useState(false);
+  useEffect(() => {
+    if (!dragging) setLocal(band.gain);
+  }, [band.gain, dragging]);
+
+  const value = dragging ? local : band.gain;
+  const pct = offsetFor(value);
+  const moved = Math.abs(value) >= 0.05;
+
+  const move = (next: number) => {
+    setDragging(true);
+    setLocal(next);
+    onPreview(next);
+  };
+  const settle = () => {
+    if (!dragging) return;
+    setDragging(false);
+    onCommit(local);
+  };
+
+  // A range input rotated into a fader: it keeps keyboard control, focus and
+  // the platform's own pointer handling, which a div with pointer events would
+  // all have to reimplement badly.
+  return (
+    <div className="hf-fx-eq-band flex min-w-0 flex-1 flex-col items-center gap-1">
+      <div className="relative h-[74px] w-full">
+        <span className="pointer-events-none absolute inset-x-0 top-1/2 h-px bg-panel-border-input" />
+        <span
+          className="pointer-events-none absolute left-1/2 w-[3px] -translate-x-1/2 rounded-sm bg-panel-accent"
+          style={
+            // `value`, not `band.gain`: mid-drag across zero the fill would
+            // otherwise keep pointing the way it started.
+            value >= 0 ? { top: `${pct}%`, bottom: "50%" } : { top: "50%", bottom: `${100 - pct}%` }
+          }
+        />
+        <input
+          className="hf-fx-eq-fader absolute left-1/2 h-[19px] w-[74px] -translate-x-1/2 -translate-y-1/2 rotate-[-90deg] cursor-ns-resize appearance-none bg-transparent"
+          style={{ top: "50%" }}
+          type="range"
+          min={-HF_AUDIO_EQ_RANGE_DB}
+          max={HF_AUDIO_EQ_RANGE_DB}
+          step={0.5}
+          value={value}
+          disabled={disabled}
+          aria-label={`${band.name} ${shown(value)} dB`}
+          onChange={(e) => move(Number(e.target.value))}
+          onPointerUp={settle}
+          onKeyUp={settle}
+          onBlur={settle}
+        />
+      </div>
+      <span className="hf-fx-eq-name w-full truncate text-center font-mono text-[9px] uppercase tracking-wide text-panel-text-2">
+        {band.name}
+      </span>
+      <span
+        className={`hf-fx-eq-value font-mono text-[9px] tabular-nums ${
+          moved ? "text-panel-accent" : "text-panel-text-4"
+        }`}
+      >
+        {moved ? shown(value) : "0"}
+      </span>
+    </div>
+  );
+}
+
+export function FxEqModule({
+  bands,
+  open,
+  disabled,
+  onToggleOpen,
+  onPreview,
+  onCommit,
+  onRemove,
+}: FxEqModuleProps) {
+  const preview = useCallback((name: string, gain: number) => onPreview(name, gain), [onPreview]);
+  const commit = useCallback((name: string, gain: number) => onCommit(name, gain), [onCommit]);
+
+  return (
+    <div
+      className="hf-fx-node hf-fx-eq-module rounded-[4px] border border-panel-border-input"
+      data-fx-node="eq"
+    >
+      <div className="hf-fx-node-head flex items-center gap-1.5 px-1.5 py-1">
+        <button
+          type="button"
+          className="hf-fx-node-name flex-1 text-left text-[11px] text-panel-text-0"
+          aria-expanded={open}
+          onClick={onToggleOpen}
+        >
+          Tone
+        </button>
+        <span className="font-mono text-[9px] text-panel-text-4">{bands.length}-band</span>
+        <button
+          type="button"
+          className="hf-fx-remove px-1 text-[11px] text-panel-text-4 hover:text-panel-danger"
+          aria-label="Remove Tone"
+          disabled={disabled}
+          onClick={onRemove}
+        >
+          ×
+        </button>
+      </div>
+
+      {open ? (
+        <div className="hf-fx-eq-body px-2 pb-2">
+          <div className="flex gap-1.5">
+            {bands.map((band) => (
+              <Fader
+                key={band.name}
+                band={band}
+                disabled={disabled}
+                onPreview={(g) => preview(band.name, g)}
+                onCommit={(g) => commit(band.name, g)}
+              />
+            ))}
+          </div>
+          <div className="mt-1.5 flex justify-between font-mono text-[8px] tracking-wide text-panel-text-4">
+            <span>CUT</span>
+            <span>BOOST</span>
+          </div>
+        </div>
+      ) : (
+        // Closed, it reads like every other module: a sentence about the sound
+        // rather than a list of values.
+        <p className="hf-fx-eq-summary px-2 pb-1.5 text-[11px] text-panel-text-2">
+          {audioEqSummary(bands)}
+        </p>
+      )}
+    </div>
+  );
+}

packages/studio/src/components/editor/propertyPanelFxSection.test.tsx

@@ -284,6 +284,110 @@ describe("FxSection chain", () => {
     expect(names).not.toContain("Peaking EQ");
   });
 
+  it("adds a Tone EQ as three ordinary filters on one control surface", () => {
+    const { host, onChainChange } = mount({ chain: { version: 1, nodes: [] } });
+    click(host.querySelector(".hf-fx-add"));
+    click(byText(host, ".hf-fx-add-composite", "Tone (EQ)"));
+
+    const next = onChainChange.mock.calls[0]![0] as HfAudioFxChain;
+    expect(next.nodes.map((n) => n.type)).toEqual(["lowshelf", "peaking", "highshelf"]);
+    expect(next.nodes.map((n) => n.label)).toEqual(["Bass", "Middle", "Treble"]);
+    expect(next.nodes.every((n) => n.fromEq === "eq1")).toBe(true);
+  });
+
+  it("shows the EQ as one module, not as its individual bands", () => {
+    // The bands belong to the Tone module. Listing them again in the rack would
+    // put the same filter on screen twice with two ways to edit it.
+    const { host } = mount({
+      chain: {
+        version: 1,
+        nodes: [
+          {
+            type: "lowshelf",
+            id: "a",
+            fromEq: "eq1",
+            label: "Bass",
+            enabled: true,
+            params: defaultAudioFxParams("lowshelf"),
+          },
+          {
+            type: "peaking",
+            id: "b",
+            fromEq: "eq1",
+            label: "Middle",
+            enabled: true,
+            params: defaultAudioFxParams("peaking"),
+          },
+          {
+            type: "highshelf",
+            id: "c",
+            fromEq: "eq1",
+            label: "Treble",
+            enabled: true,
+            params: defaultAudioFxParams("highshelf"),
+          },
+        ],
+      } as HfAudioFxChain,
+    });
+    expect(host.querySelectorAll(".hf-fx-eq-module")).toHaveLength(1);
+    const names = Array.from(host.querySelectorAll(".hf-fx-node-name")).map((e) =>
+      e.textContent?.trim(),
+    );
+    expect(names).toContain("Tone");
+    expect(names).not.toContain("Bass");
+    // Closed, it says what it is doing rather than listing three zeroes.
+    expect(host.querySelector(".hf-fx-eq-summary")?.textContent).toMatch(/^Flat/);
+  });
+
+  it("moves one band without persisting until the fader is released", () => {
+    const { host, onChainChange, onChainPreview } = mount({
+      chain: {
+        version: 1,
+        nodes: [
+          {
+            type: "lowshelf",
+            id: "a",
+            fromEq: "eq1",
+            label: "Bass",
+            enabled: true,
+            params: defaultAudioFxParams("lowshelf"),
+          },
+          {
+            type: "peaking",
+            id: "b",
+            fromEq: "eq1",
+            label: "Middle",
+            enabled: true,
+            params: defaultAudioFxParams("peaking"),
+          },
+          {
+            type: "highshelf",
+            id: "c",
+            fromEq: "eq1",
+            label: "Treble",
+            enabled: true,
+            params: defaultAudioFxParams("highshelf"),
+          },
+        ],
+      } as HfAudioFxChain,
+    });
+    // The carve module leads the rack, so its header is the first one — open
+    // the EQ's own.
+    click(host.querySelector(".hf-fx-eq-module .hf-fx-node-name"));
+    const fader = host.querySelectorAll<HTMLInputElement>(".hf-fx-eq-fader")[0]!;
+    expect(fader, "the EQ did not open").toBeTruthy();
+    typeInto(fader, "4");
+    // Heard, not written — a persisting write per drag event reloads the
+    // composition and restarts the audio.
+    expect(onChainPreview).toHaveBeenCalled();
+    expect(onChainChange).not.toHaveBeenCalled();
+
+    act(() => fader.dispatchEvent(new Event("pointerup", { bubbles: true })));
+    const next = onChainChange.mock.calls[0]![0] as HfAudioFxChain;
+    expect(next.nodes.find((n) => n.label === "Bass")!.params!.gain).toBe(4);
+    expect(next.nodes.find((n) => n.label === "Middle")!.params!.gain).toBe(0);
+  });
+
   it("cannot move the ends past themselves", () => {
     const { host } = mount({ chain: chainOf("peaking", "reverb") });
     const ups = host.querySelectorAll('.hf-fx-move[title="Move up"]');