feat(studio): two faces — a module opens on one knob, the rest one click away

Rule 1 of `plans/audio-fx-ux/README.md`. A module opens on its name, a
line saying what it is for, and the single control that carries it; every
other parameter is behind a Details disclosure. Nothing is hidden — it is
ordered. `EFFECT_COPY.primary` names that control and `primaryEnds` says
what its two ends sound like, which is the question an author actually
has: a number tells them where the knob is, not which way to move it.

The DSP name moves onto the disclosure itself, so it is read at the
moment the author asks what this really is and never before.

Ten of the fifteen effects get this. The other five — compressor, gate,
saturate, reverb, bitcrush — name their primary as "strength", meaning
they want a single DERIVED control over several parameters, which is
`PROFILES`, whose figures are proposed rather than measured and which has
not shipped. They open on all their controls until it does. That is the
honest state: inventing one knob for them now would be a knob that lies
about what it sets. The lookup needs no special case for it either —
"strength" names no parameter today, and the day it does name one, this
starts using it without being told.

Worth naming: `peaking`'s primary is "how much", and that only became
coherent in the commit before this one. Boosting an unspecified frequency
means nothing, so one knob was a lie while the module was generic; now
that picking the job is what picks the range, it is the whole truth.

The disclosure is local state, keyed by node like the row itself, so it
stays with its effect across a reorder — and an effect arriving in the
open slot arrives closed, like any other.

Tests that address a non-primary knob now open Details first, which is
also the gesture a user makes. Falsified: expanding Details unconditionally
fails the two-faces test, and dropping the "is it a real parameter" guard
fails three.

studio 3688 passing, 18 todo.

Author: vanceingalls

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

@@ -64,6 +64,17 @@ function audioSelection(
   return { dataAttributes, id: "bed", element: bed } as unknown as DomEditSelection;
 }
 
+/**
+ * Open a module's Details, where every control that is not the primary one now
+ * lives — a module opens on one knob and the rest is one click away.
+ */
+function openDetails(host: HTMLElement, index = 0): void {
+  const buttons = Array.from(host.querySelectorAll<HTMLButtonElement>(".hf-fx-node-details"));
+  const button = buttons[index];
+  if (!button) throw new Error("no Details disclosure to open");
+  act(() => button.click());
+}
+
 /** A button found by the text it contains, since several now read as sentences. */
 function byTextButton(host: HTMLElement, text: string): HTMLButtonElement | undefined {
   return Array.from(host.querySelectorAll("button")).find((b) => b.textContent?.includes(text));
@@ -111,7 +122,11 @@ const writeTo = (calls: unknown[][], attr: string): unknown[] | undefined =>
 describe("AudioFxGroup automation", () => {
   it("renders the chain's parameters", () => {
     const { host } = mount({ "fx-chain": CHAIN });
+    // The one knob that carries the module is on the open face; the rest are one
+    // click away, which is what Details is.
     expect(rowFor(host, plainLabel("lowpass", "frequency"))).toBeTruthy();
+    expect(rowFor(host, plainLabel("lowpass", "q"))).toBeNull();
+    openDetails(host);
     expect(rowFor(host, plainLabel("lowpass", "q"))).toBeTruthy();
   });
 
@@ -139,6 +154,7 @@ describe("AudioFxGroup automation", () => {
         lanes: [{ target: "volume", points: [{ t: 0, v: 0.5 }] }],
       }),
     });
+    openDetails(host);
     act(() =>
       (
         rowFor(host, plainLabel("lowpass", "q"))!.querySelector(
@@ -164,6 +180,7 @@ describe("AudioFxGroup automation", () => {
     const cutoff = rowFor(host, plainLabel("lowpass", "frequency"))!;
     expect(cutoff.querySelector<HTMLInputElement>('input[type="range"]')?.disabled).toBe(true);
     expect(cutoff.hasAttribute("data-automated")).toBe(true);
+    openDetails(host);
     expect(
       rowFor(host, plainLabel("lowpass", "q"))!.querySelector<HTMLInputElement>(
         'input[type="range"]',

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

@@ -10,7 +10,7 @@
  * with the mechanism. See `plans/audio-fx-ux/README.md` §Decided.
  */
 
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import {
   defaultAudioFxParams,
   getAudioFxDef,
@@ -22,6 +22,29 @@ import { EFFECT_COPY, SUMMARY } from "@hyperframes/core/audio-fx-copy";
 import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
 import { FxParams } from "./propertyPanelFxControls.js";
 
+/**
+ * The one control that carries the module, if it has one.
+ *
+ * "Two faces": a module opens on its name, a line about what it is for, and one
+ * knob — the rest is one click away and never in the way. Nothing is hidden; it
+ * is ordered.
+ *
+ * `primary` is either a real parameter key or the string "strength", which means
+ * the module wants a single DERIVED control over several parameters — the
+ * `PROFILES` idea, whose figures are proposed rather than measured and which has
+ * not shipped. Until it does, those five effects (compressor, gate, saturate,
+ * reverb, bitcrush) open on all of their controls, which is honest: the one knob
+ * they want does not exist yet, and inventing one would be a knob that lies.
+ */
+function primaryParamOf(def: HfAudioFxDef): string | null {
+  const primary = EFFECT_COPY[def.id]?.primary;
+  // "strength" names no parameter, which is exactly what makes this work: the
+  // day `PROFILES` ships and a derived `strength` knob really is in the
+  // registry, this starts using it without being told.
+  if (!primary) return null;
+  return def.params.some((p) => p.key === primary) ? primary : null;
+}
+
 /**
  * The registry's definition with the plain names written over it.
  *
@@ -250,7 +273,17 @@ export function FxNodeRow({
 }: FxNodeRowProps) {
   const registryDef = getAudioFxDef(node.type);
   const def = useMemo(() => (registryDef ? plainDef(registryDef) : null), [registryDef]);
-  if (!registryDef || !def) return null;
+  const primary = registryDef ? primaryParamOf(registryDef) : null;
+  /** The same def cut down to the one knob, so the open face reuses every wire. */
+  const onlyPrimary = useMemo(
+    () => (def && primary ? { ...def, params: def.params.filter((p) => p.key === primary) } : def),
+    [def, primary],
+  );
+  // Local, because nothing outside the row needs to know. Keyed by node id like
+  // the row itself, so it stays with its effect across a reorder.
+  const [details, setDetails] = useState(false);
+  if (!registryDef || !def || !onlyPrimary) return null;
+  const copy = EFFECT_COPY[node.type];
   const bypassed = node.enabled === false;
   const params = node.params ?? defaultAudioFxParams(node.type);
   // What this effect is doing to the sound, as a sentence. The rack is read top
@@ -285,24 +318,68 @@ export function FxNodeRow({
       ) : null}
       {open ? (
         <>
-          {/* The DSP name, once, where the mechanism is. An author who wants to
-              know what "Remove Rumble" really is finds out by opening it; one who
-              does not never has to meet the word. */}
-          <p className="hf-fx-node-mechanism border-t border-panel-border-input px-1.5 pt-1 font-mono text-[9px] uppercase tracking-wide text-panel-text-4">
-            Details — {registryDef.label}
-          </p>
-          <FxNodeParams
-            node={node}
-            def={def}
-            index={index}
-            disabled={Boolean(disabled) || bypassed}
-            automatedTargets={automatedTargets}
-            liveAutomationValues={liveAutomationValues}
-            onUpdate={onUpdate}
-            onPreview={onPreview}
-            onAutomateParam={onAutomateParam}
-            onRemoveParamAutomation={onRemoveParamAutomation}
-          />
+          {/* What it is for, before what it is made of. */}
+          {copy?.does ? (
+            <p className="hf-fx-node-does border-t border-panel-border-input px-1.5 py-1 text-[10px] text-panel-text-4">
+              {copy.does}
+            </p>
+          ) : null}
+          {primary && !details ? (
+            <>
+              <FxNodeParams
+                node={node}
+                def={onlyPrimary}
+                index={index}
+                disabled={Boolean(disabled) || bypassed}
+                automatedTargets={automatedTargets}
+                liveAutomationValues={liveAutomationValues}
+                onUpdate={onUpdate}
+                onPreview={onPreview}
+                onAutomateParam={onAutomateParam}
+                onRemoveParamAutomation={onRemoveParamAutomation}
+              />
+              {/* What the two ends of that knob sound like. A number tells an
+                  author where the control is; this tells them which way to move
+                  it, which is the question they actually have. */}
+              {copy?.primaryEnds ? (
+                <p className="hf-fx-node-ends flex justify-between gap-2 px-1.5 pb-1 text-[9px] text-panel-text-4">
+                  <span className="truncate">{copy.primaryEnds.low}</span>
+                  <span className="truncate text-right">{copy.primaryEnds.high}</span>
+                </p>
+              ) : null}
+            </>
+          ) : null}
+          {/* The DSP name lives on the disclosure, so it is read at the moment
+              the author asks what this really is — and never before. */}
+          {primary ? (
+            <button
+              type="button"
+              className="hf-fx-node-details flex w-full items-center gap-1 border-t border-panel-border-input px-1.5 py-1 text-left font-mono text-[9px] uppercase tracking-wide text-panel-text-4 hover:text-panel-text-0"
+              aria-expanded={details}
+              onClick={() => setDetails((was) => !was)}
+            >
+              <span aria-hidden="true">{details ? "\u25BE" : "\u25B8"}</span>
+              Details — {registryDef.label}
+            </button>
+          ) : (
+            <p className="hf-fx-node-mechanism border-t border-panel-border-input px-1.5 pt-1 font-mono text-[9px] uppercase tracking-wide text-panel-text-4">
+              Details — {registryDef.label}
+            </p>
+          )}
+          {details || !primary ? (
+            <FxNodeParams
+              node={node}
+              def={def}
+              index={index}
+              disabled={Boolean(disabled) || bypassed}
+              automatedTargets={automatedTargets}
+              liveAutomationValues={liveAutomationValues}
+              onUpdate={onUpdate}
+              onPreview={onPreview}
+              onAutomateParam={onAutomateParam}
+              onRemoveParamAutomation={onRemoveParamAutomation}
+            />
+          ) : null}
         </>
       ) : null}
     </div>

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

@@ -102,6 +102,17 @@ const click = (el: Element | null | undefined) => {
     (el as HTMLElement).click();
   });
 };
+/**
+ * Open a module's Details, where every control that is not the primary one now
+ * lives — a module opens on one knob and the rest is one click away.
+ */
+function openDetails(host: HTMLElement, index = 0): void {
+  const buttons = Array.from(host.querySelectorAll<HTMLButtonElement>(".hf-fx-node-details"));
+  const button = buttons[index];
+  if (!button) throw new Error("no Details disclosure to open");
+  act(() => button.click());
+}
+
 const byText = (host: HTMLElement, sel: string, text: string) =>
   Array.from(host.querySelectorAll(sel)).find((e) => e.textContent?.trim() === text);
 
@@ -284,6 +295,9 @@ describe("FxSection chain", () => {
       });
 
     render(chainOfNodes(a, b));
+    // Frequency is behind Details for a peaking node — the module opens on how
+    // much, now that picking the module is what picks the range.
+    openDetails(host);
     // Only the first card is open, which is the one being edited.
     const openFrequency = (): HTMLInputElement =>
       host.querySelector<HTMLInputElement>(".hf-fx-node .hf-fx-number")!;
@@ -295,6 +309,9 @@ describe("FxSection chain", () => {
     // The author moves that effect down; the other one takes the open slot.
     render(chainOfNodes(b, a));
 
+    // Its own Details, not the one that was open: the disclosure is per module,
+    // so the effect arriving in the slot arrives closed like any other.
+    openDetails(host);
     expect(openFrequency().value).toBe("1600");
   });
 
@@ -331,9 +348,31 @@ describe("FxSection chain", () => {
     expect(name).not.toBe(getAudioFxDef("highpass")?.label);
     // And a sentence under it, so the rack reads top to bottom.
     expect(node.querySelector(".hf-fx-node-summary")?.textContent).toContain("Cutting everything");
-    // The first node is open by default, which is where the DSP name lives.
-    expect(node.querySelector(".hf-fx-node-mechanism")?.textContent).toContain(
-      getAudioFxDef("highpass")?.label,
+    // Open, it says what it is for and offers ONE knob — the rest is behind a
+    // disclosure, which is also the only place the DSP name appears.
+    expect(node.querySelector(".hf-fx-node-does")?.textContent).toBe(EFFECT_COPY.highpass?.does);
+    expect(node.querySelectorAll(".hf-fx-row")).toHaveLength(1);
+    const details = node.querySelector(".hf-fx-node-details");
+    expect(details?.textContent).toContain(getAudioFxDef("highpass")?.label);
+    expect(details?.getAttribute("aria-expanded")).toBe("false");
+
+    openDetails(host);
+    expect(node.querySelectorAll(".hf-fx-row").length).toBe(
+      getAudioFxDef("highpass")?.params.length,
+    );
+  });
+
+  it("opens a module on all of its controls when its one knob does not exist yet", () => {
+    // Five effects want a single DERIVED control over several parameters — the
+    // `PROFILES` idea, whose figures are proposed rather than measured. Until it
+    // ships they open on everything, which is honest: inventing one knob for
+    // them now would be a knob that lies about what it sets.
+    const { host } = mount({ chain: chainOf("compressor") });
+    const node = fxCard(host);
+    expect(EFFECT_COPY.compressor?.primary).toBe("strength");
+    expect(node.querySelector(".hf-fx-node-details")).toBeNull();
+    expect(node.querySelectorAll(".hf-fx-row").length).toBe(
+      getAudioFxDef("compressor")?.params.length,
     );
   });
 
@@ -654,6 +693,9 @@ describe("FxSection chain", () => {
     // Persisting on every input event refreshes the preview, which reloads the
     // composition and restarts audio — that is what made playback stutter.
     const { host, onChainChange, onChainPreview } = mount({ chain: chainOf("peaking") });
+    // Details, because this is about the drag mechanics on a real control and
+    // the frequency it asserts on is not the one knob the module opens with.
+    openDetails(host);
     const slider = fxCard(host).querySelector<HTMLInputElement>(".hf-fx-slider")!;
     act(() => slider.dispatchEvent(new Event("pointerdown", { bubbles: true })));
     for (const v of ["5000", "10000", "15000"]) {
@@ -705,6 +747,7 @@ describe("FxSection chain", () => {
       sourceOptions: [{ id: "vo", label: "Voiceover" }],
     };
     const { host, root } = renderInto(<FxSection {...shared} chain={chainOf("peaking")} />);
+    openDetails(host);
     const slider = fxCard(host).querySelector<HTMLInputElement>(".hf-fx-slider")!;
     const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
     act(() => slider.dispatchEvent(new Event("pointerdown", { bubbles: true })));
@@ -747,6 +790,7 @@ describe("FxSection chain", () => {
 
   it("clamps a typed value into the renderable range", () => {
     const { host, onChainChange } = mount({ chain: chainOf("peaking") });
+    openDetails(host);
     const input = fxCard(host).querySelector<HTMLInputElement>(".hf-fx-number")!;
     typeInto(input, "999999");
     // React delegates onBlur through focusout, which is the event that bubbles.
@@ -1024,7 +1068,9 @@ describe("automation in the panel", () => {
     expect(row.querySelector<HTMLInputElement>('input[type="range"]')?.disabled).toBe(true);
     expect(row.querySelector<HTMLInputElement>('input[type="number"]')?.disabled).toBe(true);
     expect(row.hasAttribute("data-automated")).toBe(true);
-    // A sibling parameter on the same effect stays editable.
+    // A sibling parameter on the same effect stays editable — one click in,
+    // which is where every control that is not the primary one lives.
+    openDetails(host);
     const q = rowFor(host, plainLabel("lowpass", "q"))!;
     expect(q.querySelector<HTMLInputElement>('input[type="range"]')?.disabled).toBe(false);
   });