@hyperframes/studio 0.7.106 → 0.7.108

package/src/components/editor/propertyPanelFxNodeRow.tsx

@@ -0,0 +1,339 @@
+/**
+ * One effect in the FX rack: its header controls, and its knobs when open.
+ *
+ * An entry in the chain, as opposed to a composite module — the carve and the
+ * Tone EQ own several nodes each and have their own files.
+ *
+ * The row speaks the author's language, not the registry's. `EFFECT_COPY`
+ * supplies the name and every knob's name, `SUMMARY` the sentence under it, and
+ * the DSP name moves inside — it is a fact about the mechanism, so it belongs
+ * with the mechanism. See `plans/audio-fx-ux/README.md` §Decided.
+ */
+
+import { useMemo, useState } from "react";
+import {
+  defaultAudioFxParams,
+  getAudioFxDef,
+  type HfAudioFxDef,
+  type HfAudioFxNode,
+  type HfAudioFxParam,
+  type HfAudioFxParamValues,
+} from "@hyperframes/core/audio-fx";
+import { EFFECT_COPY, SUMMARY } from "@hyperframes/core/audio-fx-copy";
+import { trackNodeBypassed } from "./audioFxTelemetry.js";
+import { getAudioFxProfile } from "@hyperframes/core/audio-fx-profiles";
+import { FX_FAMILY_TYPE, fxFamilyOf, fxFamilyTint } from "./propertyPanelFxFamily.js";
+import { FxNodeOpenBody } from "./propertyPanelFxNodeOpenBody.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 real parameter, and for the five effects that declare it
+  // that is the point: their one knob is derived, and `profileRow` below builds
+  // it. Anything else has to be a parameter the effect actually has.
+  if (!primary || primary === "strength") return null;
+  return def.params.some((p) => p.key === primary) ? primary : null;
+}
+
+/**
+ * The derived knob, as a parameter the existing controls can render.
+ *
+ * A profile is not in the registry — it sets five real parameters and is none of
+ * them — so this fabricates the one row it needs rather than teaching `FxParams`
+ * about a second kind of control. 0..1 in hundredths, the same shape and the
+ * same feel as the carve's Strength.
+ */
+function profileParam(type: string): HfAudioFxParam | null {
+  const profile = getAudioFxProfile(type);
+  if (!profile) return null;
+  return {
+    kind: "number",
+    key: "strength",
+    label: profile.label,
+    unit: "",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    default: 0.5,
+    hint: `Sets ${profile.derives.length} settings at once. Open Details to see where they land.`,
+  };
+}
+
+/**
+ * The registry's definition with the plain names written over it.
+ *
+ * Over rather than instead of: the registry stays the authority on range, step,
+ * unit and what is automatable, and only the words change. A parameter with no
+ * copy keeps its own label rather than disappearing — `audioFxCopy.test.ts` is
+ * what makes sure there is never one.
+ */
+function plainDef(def: HfAudioFxDef): HfAudioFxDef {
+  const copy = EFFECT_COPY[def.id];
+  if (!copy) return def;
+  return {
+    ...def,
+    params: def.params.map((param) => {
+      const plain = copy.params[param.key];
+      if (!plain) return param;
+      // The registry's hint explains the mechanism, which is still the better
+      // tooltip than none — but the plain one wins where it exists.
+      return { ...param, label: plain.label, ...(plain.hint ? { hint: plain.hint } : {}) };
+    }),
+  };
+}
+
+interface FxNodeRowProps {
+  node: HfAudioFxNode;
+  index: number;
+  /** Where it sits in the signal path, as the rack counts it. Absent means unnumbered. */
+  position?: number;
+  automatedTargets?: ReadonlySet<string>;
+  liveAutomationValues?: ReadonlyMap<string, number>;
+  onAutomateParam?(nodeId: string, paramKey: string): void;
+  onRemoveParamAutomation?(nodeId: string, paramKey: string): void;
+  open: boolean;
+  /** Last in the chain, so it cannot move further down. */
+  last: boolean;
+  disabled?: boolean;
+  onToggleOpen(): void;
+  onUpdate(index: number, patch: Partial<HfAudioFxNode>): void;
+  onMove(index: number, delta: number): void;
+  onRemove(index: number): void;
+  onPreview(index: number, params: HfAudioFxParamValues): void;
+  /** What the track reads as, carried onto this row own events. */
+  trackKind?: string;
+}
+
+/** Reorder arrow. Disabled at the end of the chain it would move past. */
+function FxMoveButton({
+  label,
+  glyph,
+  disabled,
+  onClick,
+}: {
+  label: string;
+  glyph: string;
+  disabled: boolean;
+  onClick(): void;
+}) {
+  return (
+    <button
+      type="button"
+      className="hf-fx-move px-1 font-mono text-[10px] text-panel-text-2 hover:text-panel-text-0 disabled:opacity-25"
+      title={label}
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {glyph}
+    </button>
+  );
+}
+
+/** Name, bypass, reorder and remove for one effect. */
+function FxNodeHeader({
+  label,
+  family,
+  position,
+  open,
+  bypassed,
+  first,
+  last,
+  disabled,
+  onToggleOpen,
+  onToggleBypass,
+  onMove,
+  onRemove,
+}: {
+  label: string;
+  /** How this family letters, so the KIND reads before the word does. */
+  family: string;
+  position?: number;
+  open: boolean;
+  bypassed: boolean;
+  first: boolean;
+  last: boolean;
+  disabled?: boolean;
+  onToggleOpen(): void;
+  onToggleBypass(): void;
+  onMove(delta: number): void;
+  onRemove(): void;
+}) {
+  return (
+    <div className="hf-fx-node-head flex min-h-7 items-center gap-1 px-1.5">
+      {/* Two digits, because a rack reads as a path when its steps are numbered
+          and as a list when they are not — and the difference decides whether an
+          author thinks the order matters. It does; it is audible. */}
+      {position !== undefined ? (
+        <span className="hf-fx-node-index shrink-0 font-mono text-[9px] tabular-nums text-panel-text-2">
+          {String(position).padStart(2, "0")}
+        </span>
+      ) : null}
+      <button
+        type="button"
+        className={`hf-fx-node-name flex-1 truncate text-left text-[11px] text-panel-text-1 hover:text-panel-text-0 ${family}`}
+        aria-expanded={open}
+        onClick={onToggleOpen}
+      >
+        {label}
+      </button>
+      <button
+        type="button"
+        className="hf-fx-bypass rounded-[3px] border border-panel-border-input px-1.5 py-0.5 font-mono text-[9px] text-panel-text-2 hover:text-panel-text-0 disabled:opacity-40"
+        aria-pressed={bypassed}
+        title={bypassed ? "Enable" : "Bypass"}
+        disabled={disabled}
+        onClick={onToggleBypass}
+      >
+        {bypassed ? "Off" : "On"}
+      </button>
+      <FxMoveButton
+        label="Move up"
+        glyph="&uarr;"
+        disabled={Boolean(disabled) || first}
+        onClick={() => onMove(-1)}
+      />
+      <FxMoveButton
+        label="Move down"
+        glyph="&darr;"
+        disabled={Boolean(disabled) || last}
+        onClick={() => onMove(1)}
+      />
+      <button
+        type="button"
+        className="hf-fx-remove px-1 font-mono text-[11px] text-panel-text-2 hover:text-red-400 disabled:opacity-40"
+        title="Remove"
+        disabled={disabled}
+        onClick={onRemove}
+      >
+        &times;
+      </button>
+    </div>
+  );
+}
+
+/** One effect in the chain: its header controls, and its knobs when open. */
+export function FxNodeRow({
+  node,
+  index,
+  position,
+  automatedTargets,
+  liveAutomationValues,
+  onAutomateParam,
+  onRemoveParamAutomation,
+  open,
+  last,
+  disabled,
+  onToggleOpen,
+  onUpdate,
+  onMove,
+  onRemove,
+  onPreview,
+  trackKind,
+}: FxNodeRowProps) {
+  const registryDef = getAudioFxDef(node.type);
+  const def = useMemo(() => (registryDef ? plainDef(registryDef) : null), [registryDef]);
+  const primary = registryDef ? primaryParamOf(registryDef) : null;
+  /**
+   * The derived knob, for a module with no real parameter that can be its face.
+   *
+   * It behaves like the primary one everywhere below — one control on the open
+   * face, everything it sets behind Details — so the two are the same shape and
+   * only their source differs.
+   */
+  const profile = getAudioFxProfile(node.type);
+  const derived = useMemo(() => profileParam(node.type), [node.type]);
+  /** 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 oneKnob = primary !== null || derived !== 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
+  // to bottom far more often than any one module is opened, so this is the line
+  // that decides whether an author can follow their own mix.
+  const summary = SUMMARY[node.type]?.(params);
+  return (
+    <div
+      className={`hf-fx-node rounded-[4px] border border-l-2 border-panel-border-input${bypassed ? " opacity-50" : ""}`}
+      data-fx-node={node.type}
+      data-fx-family={fxFamilyOf(node)}
+      // The tint is on the edge rather than the text: the name already carries
+      // the family in its lettering, and colouring it too would fight the
+      // panel's own tokens for automated and bypassed.
+      style={{ borderLeftColor: fxFamilyTint(node) }}
+    >
+      <FxNodeHeader
+        family={FX_FAMILY_TYPE[fxFamilyOf(node)]}
+        position={position}
+        // The node's own job name when a preset gave it one, because that is the
+        // most specific truth available: a chain that cuts mud and then lifts
+        // clarity must not show the same name twice. Then the plain name, and
+        // the registry's only if an effect somehow has no copy.
+        label={node.label ?? EFFECT_COPY[node.type]?.title ?? registryDef.label}
+        open={open}
+        bypassed={bypassed}
+        first={index === 0}
+        last={last}
+        disabled={disabled}
+        onToggleOpen={onToggleOpen}
+        onToggleBypass={() => {
+          trackNodeBypassed(node.type, !bypassed, { trackKind });
+          onUpdate(index, { enabled: bypassed });
+        }}
+        onMove={(delta) => onMove(index, delta)}
+        onRemove={() => onRemove(index)}
+      />
+      {summary ? (
+        <p className="hf-fx-node-summary truncate px-1.5 pb-1 text-[10px] text-panel-text-2">
+          {summary}
+        </p>
+      ) : null}
+      {open ? (
+        <FxNodeOpenBody
+          node={node}
+          registryDef={registryDef}
+          def={def}
+          onlyPrimary={onlyPrimary}
+          primary={primary}
+          derived={derived}
+          profile={profile}
+          oneKnob={oneKnob}
+          details={details}
+          onToggleDetails={() => setDetails((was) => !was)}
+          copy={copy}
+          params={params}
+          index={index}
+          disabled={disabled}
+          bypassed={bypassed}
+          automatedTargets={automatedTargets}
+          liveAutomationValues={liveAutomationValues}
+          onUpdate={onUpdate}
+          onPreview={onPreview}
+          onAutomateParam={onAutomateParam}
+          onRemoveParamAutomation={onRemoveParamAutomation}
+          trackKind={trackKind}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/editor/propertyPanelFxPresetMenu.tsx

@@ -0,0 +1,159 @@
+/**
+ * The preset shelf for the FX rack.
+ *
+ * Its own module rather than another block inside the section: the section is
+ * already the largest file in the panel, and this surface is going to grow —
+ * search, per-item descriptions and a preview of the chain each preset draws
+ * are all queued behind it.
+ */
+
+import {
+  audioFxPresetsByFamily,
+  HF_AUDIO_FX_PRESET_FAMILIES,
+  type HfAudioFxPresetFamily,
+} from "@hyperframes/core/audio-fx-presets";
+import { PRESET_PROBLEM } from "@hyperframes/core/audio-fx-copy";
+import { useRef } from "react";
+import type { HfAudioNameKind } from "@hyperframes/core/audio-carve";
+
+/**
+ * Shelf names in the author's language, which is deliberately not the effect
+ * registry's grouping. `group` says what an effect *is* (filter, dynamics);
+ * somebody reaching for Telephone is shopping for what they *want*, and
+ * Telephone is filters and saturation — nobody looks for it under either.
+ */
+const FAMILY_LABEL: Record<HfAudioFxPresetFamily, string> = {
+  voice: "Voice",
+  repair: "Fix",
+  character: "Character",
+  space: "Space",
+};
+
+export interface FxPresetMenuProps {
+  /**
+   * What the track reads as, from its id and filename.
+   *
+   * Only a confident "music" or "sfx" hides anything. `unknown` keeps the whole
+   * shelf, on the same principle the carve's source picker follows: a name is a
+   * hint, and a shelf that hides what somebody came for is worse than a long
+   * one. Nothing here is irreversible either — the cost of a wrong guess is one
+   * shelf the author has to scroll past, against the cost of "My voice sounds
+   * amateur" sitting on a music bed.
+   */
+  trackKind?: HfAudioNameKind;
+  onPick(id: string): void;
+  /**
+   * Report that a preset was auditioned. Called at most once per preset for as
+   * long as this shelf stays mounted — a pointer crossing the column passes a
+   * dozen items in a second, and counting every crossing would describe mouse
+   * travel rather than interest, while drowning every other event in the rack.
+   */
+  onAuditionTracked?(id: string): void;
+  /**
+   * Play this preset on the running audio without persisting it, and revert on
+   * `null`. Absent when there is no preview channel to hear it through.
+   */
+  onAudition?(id: string | null): void;
+}
+
+/**
+ * Presets read as the complaint they answer, not as their own names.
+ *
+ * The name is a thing you have to already know — "Telephone", "Broadcast" — and
+ * the author arriving here does not know it; they know their voice sounds
+ * boomy. So the sentence leads and the name follows underneath, which is also
+ * how the name gets learned. The four shelves stay because eighteen sentences
+ * in a column is a wall, and they are already the author's grouping rather than
+ * the registry's. See `plans/audio-fx-ux/README.md` §Decided.
+ */
+export function FxPresetMenu({
+  trackKind,
+  onPick,
+  onAudition,
+  onAuditionTracked,
+}: FxPresetMenuProps) {
+  // Mounted when the shelf opens and thrown away when it closes, so "once per
+  // preset" resets each time the author comes back — a second visit is a second
+  // look, not a duplicate of the first.
+  const auditioned = useRef(new Set<string>());
+  const reportAudition = (id: string) => {
+    if (auditioned.current.has(id)) return;
+    auditioned.current.add(id);
+    onAuditionTracked?.(id);
+  };
+  // The voice presets all begin by cutting rumble out of a human voice and end
+  // in a compressor set for speech. On a music bed that is not a mild mismatch,
+  // it is the wrong instrument — and the shelf leads with the complaint, so it
+  // would be offering the author a problem they do not have.
+  const families =
+    trackKind === "music" || trackKind === "sfx"
+      ? HF_AUDIO_FX_PRESET_FAMILIES.filter((f) => f !== "voice")
+      : HF_AUDIO_FX_PRESET_FAMILIES;
+  return (
+    <div
+      className="hf-fx-preset-menu space-y-1.5 rounded-[4px] border border-panel-border-input p-1.5"
+      // One handler for the shelf rather than one per button: leaving any preset
+      // for the gap between two of them has to revert, and a per-button leave
+      // fires that on the way to the next one.
+      onMouseLeave={onAudition ? () => onAudition(null) : undefined}
+      // Focus leaving the shelf is the keyboard's version of the pointer leaving
+      // it. Moving between two buttons inside fires this and then the next
+      // button's focus, so it reverts and re-auditions rather than sticking.
+      onBlur={onAudition ? () => onAudition(null) : undefined}
+    >
+      {families.map((family) => (
+        <div key={family} className="hf-fx-preset-group space-y-0.5">
+          <span className="hf-fx-preset-group-label block font-mono text-[9px] uppercase tracking-wide text-panel-text-2">
+            {FAMILY_LABEL[family]}
+          </span>
+          {audioFxPresetsByFamily(family).map((preset) => (
+            <button
+              key={preset.id}
+              type="button"
+              // `pr-8` so a long complaint does not run under the wave.
+              className="hf-fx-preset-item block w-full rounded-[3px] bg-panel-surface py-1 pl-1.5 pr-8 text-left text-panel-text-1 hover:text-panel-text-0"
+              // The description says what it does; the count is doing real work
+              // — it tells the author a preset IS a chain they can open and
+              // edit, rather than an opaque setting they cannot follow.
+              title={`${preset.description} (${preset.nodes.length} effect${
+                preset.nodes.length === 1 ? "" : "s"
+              })`}
+              onClick={() => onPick(preset.id)}
+              onMouseEnter={() => {
+                reportAudition(preset.id);
+                onAudition?.(preset.id);
+              }}
+              // Keyboard reaches this too: arrowing down the shelf auditions the
+              // same way hovering does, or the whole affordance is mouse-only.
+              onFocus={() => {
+                reportAudition(preset.id);
+                onAudition?.(preset.id);
+              }}
+            >
+              <span className="hf-fx-preset-problem block truncate text-[10px]">
+                {PRESET_PROBLEM[preset.id] ?? preset.description}
+              </span>
+              <span className="hf-fx-preset-name block truncate font-mono text-[9px] text-panel-text-2">
+                {preset.label}
+              </span>
+              {/* Hovering a preset plays it, and playing is otherwise invisible:
+                  the panel looks identical whether the audition is sounding or
+                  the pointer is just resting there. Only rendered when there IS
+                  an audition channel, so it never claims audio that is not
+                  happening. Four bars because that reads as a level meter at
+                  this size; three reads as an ellipsis. */}
+              {onAudition ? (
+                <span className="hf-fx-preset-wave" aria-hidden="true">
+                  <span />
+                  <span />
+                  <span />
+                  <span />
+                </span>
+              ) : null}
+            </button>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}