@hyperframes/studio 0.7.107 → 0.7.108

package/src/components/editor/propertyPanelFxFamily.ts

@@ -0,0 +1,83 @@
+/**
+ * Telling module families apart before the word registers.
+ *
+ * A rack of eight modules is eight lines of text, and reading it top to bottom
+ * means reading eight names. Lettering each family differently means an author
+ * knows what KIND of module they are looking at with the label out of focus —
+ * the shape of the line carries it, and the word only confirms.
+ *
+ * Two faces of type, as budgeted in `plans/audio-fx-ux/README.md`: the sans
+ * carries four families apart by weight, case and tracking, and the serif is
+ * spent on the single family that behaves differently from all of them.
+ * Non-linear is the only generative one — it invents signal rather than
+ * measuring or shaping what is there — so it should not look like the others.
+ *
+ * Alongside it, a tint step per module WITHIN its family, derived from position
+ * in the registry rather than assigned by hand: two filters read as two
+ * different modules without reading as two different families, and adding an
+ * effect upstream never re-colours its siblings.
+ */
+
+import { HF_AUDIO_FX, type HfAudioFxNode } from "@hyperframes/core/audio-fx";
+
+export type FxFamily = "filter" | "dynamics" | "nonlinear" | "time" | "smart";
+
+/**
+ * How each family letters.
+ *
+ * `smart` is not a registry group. It is the measuring modules — the carve, the
+ * Tone EQ, the leveller — which analyse the audio and write their own settings.
+ * Monospace because that is what a readout looks like, and what they show IS a
+ * readout: numbers something else decided.
+ */
+export const FX_FAMILY_TYPE: Record<FxFamily, string> = {
+  filter: "font-light uppercase tracking-[0.14em]",
+  dynamics: "font-bold uppercase tracking-tight",
+  nonlinear: "font-serif italic tracking-normal",
+  time: "font-extralight uppercase tracking-[0.24em]",
+  smart: "font-mono font-medium tracking-normal",
+};
+
+/** Hue per family, and a lightness ramp across the modules inside it. */
+const FAMILY_HUE: Record<FxFamily, number> = {
+  filter: 205,
+  dynamics: 25,
+  nonlinear: 310,
+  time: 165,
+  smart: 95,
+};
+
+/**
+ * Which family a chain node belongs to.
+ *
+ * The composite tags win over the registry group, because what a node IS to the
+ * author is the module that owns it: a carve's peaking filters are not filters
+ * the author added, they are one carve.
+ */
+export function fxFamilyOf(
+  node: Pick<HfAudioFxNode, "type" | "fromCarve" | "fromEq" | "fromLeveller">,
+): FxFamily {
+  if (node.fromCarve || node.fromEq || node.fromLeveller) return "smart";
+  const group = HF_AUDIO_FX.find((def) => def.id === node.type)?.group;
+  return group === "dynamics" || group === "nonlinear" || group === "time" ? group : "filter";
+}
+
+/**
+ * The module's own tint: its family's hue, stepped by where it sits among its
+ * siblings in the registry.
+ *
+ * Kept narrow on purpose — 62% to 76% lightness at low saturation. This has to
+ * separate two modules at a glance without reading as a status colour, and the
+ * panel already spends saturation on "automated" and "bypassed".
+ */
+export function fxFamilyTint(
+  node: Pick<HfAudioFxNode, "type" | "fromCarve" | "fromEq" | "fromLeveller">,
+): string {
+  const family = fxFamilyOf(node);
+  const siblings = HF_AUDIO_FX.filter((def) => fxFamilyOf({ type: def.id }) === family);
+  const index = siblings.findIndex((def) => def.id === node.type);
+  const step = siblings.length > 1 ? Math.max(0, index) / (siblings.length - 1) : 0;
+  // Comma syntax rather than the space-separated modern form: it is what every
+  // CSS parser in the chain agrees on, including the one the tests run in.
+  return `hsl(${FAMILY_HUE[family]}, 32%, ${(62 + step * 14).toFixed(1)}%)`;
+}

package/src/components/editor/propertyPanelFxNodeOpenBody.tsx

@@ -0,0 +1,269 @@
+/**
+ * An effect row's open face: the derived or primary one-knob control, and
+ * Details underneath it.
+ *
+ * Split out of `propertyPanelFxNodeRow.tsx`, which owned all of this before
+ * the file grew past a size where the header and the open face were still one
+ * thing to read.
+ */
+
+import {
+  applyAudioFxProfile,
+  audioFxProfileStrength,
+  getAudioFxProfile,
+} from "@hyperframes/core/audio-fx-profiles";
+import type {
+  HfAudioFxDef,
+  HfAudioFxNode,
+  HfAudioFxParam,
+  HfAudioFxParamValues,
+} from "@hyperframes/core/audio-fx";
+import type { EFFECT_COPY } from "@hyperframes/core/audio-fx-copy";
+import { trackProfileCommitted } from "./audioFxTelemetry.js";
+import { FxParamRow } from "./propertyPanelFxControls.js";
+import { FxBandRuler } from "./propertyPanelFxBandRuler.js";
+import { FxNodeParams, type FxNodeControlHandlers } from "./propertyPanelFxNodeParams.js";
+
+/**
+ * The derived one-knob face, for a module with no real parameter that can be
+ * its own. Not routed through `FxNodeParams`: this knob is not in the
+ * registry, so it has no AudioParam behind it and nothing to automate. What
+ * automation there is belongs to the parameters it sets, under Details, where
+ * they can be aimed at individually.
+ */
+function FxNodeDerivedKnob({
+  node,
+  derived,
+  profile,
+  disabled,
+  bypassed,
+  params,
+  index,
+  onPreview,
+  onUpdate,
+  trackKind,
+}: {
+  node: HfAudioFxNode;
+  derived: HfAudioFxParam | null;
+  profile: ReturnType<typeof getAudioFxProfile>;
+  disabled?: boolean;
+  bypassed: boolean;
+  params: HfAudioFxParamValues;
+  index: number;
+  onPreview(index: number, params: HfAudioFxParamValues): void;
+  onUpdate(index: number, patch: Partial<HfAudioFxNode>): void;
+  trackKind?: string;
+}) {
+  if (!derived) return null;
+  return (
+    <>
+      <div className="hf-fx-params space-y-0.5 border-t border-panel-border-input px-1.5 py-1.5">
+        <FxParamRow
+          param={derived}
+          value={audioFxProfileStrength(node.type, params)}
+          disabled={Boolean(disabled) || bypassed}
+          onChange={(_k, v) => onPreview(index, applyAudioFxProfile(node.type, Number(v), params))}
+          onCommit={(_k, v) => {
+            trackProfileCommitted(node.type, Number(v), { trackKind });
+            onUpdate(index, { params: applyAudioFxProfile(node.type, Number(v), params) });
+          }}
+        />
+      </div>
+      {profile ? (
+        <p className="hf-fx-node-ends flex justify-between gap-2 px-1.5 pb-1 text-[9px] text-panel-text-2">
+          <span className="truncate">{profile.ends.low}</span>
+          <span className="truncate text-right">{profile.ends.high}</span>
+        </p>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * The primary knob's face: the one control, what its two ends sound like, and
+ * — for a spectral module — the ruler that teaches where it is working.
+ */
+function FxNodePrimaryKnob({
+  node,
+  onlyPrimary,
+  primary,
+  copy,
+  params,
+  index,
+  disabled,
+  bypassed,
+  automatedTargets,
+  liveAutomationValues,
+  onUpdate,
+  onPreview,
+  onAutomateParam,
+  onRemoveParamAutomation,
+  trackKind,
+}: FxNodeControlHandlers & {
+  node: HfAudioFxNode;
+  onlyPrimary: HfAudioFxDef;
+  primary: string | null;
+  copy: (typeof EFFECT_COPY)[string] | undefined;
+  params: HfAudioFxParamValues;
+  index: number;
+  disabled?: boolean;
+  bypassed: boolean;
+}) {
+  if (!primary) return null;
+  return (
+    <>
+      <FxNodeParams
+        node={node}
+        def={onlyPrimary}
+        index={index}
+        disabled={Boolean(disabled) || bypassed}
+        automatedTargets={automatedTargets}
+        liveAutomationValues={liveAutomationValues}
+        onUpdate={onUpdate}
+        onPreview={onPreview}
+        onAutomateParam={onAutomateParam}
+        onRemoveParamAutomation={onRemoveParamAutomation}
+        trackKind={trackKind}
+      />
+      {/* 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-2">
+          <span className="truncate">{copy.primaryEnds.low}</span>
+          <span className="truncate text-right">{copy.primaryEnds.high}</span>
+        </p>
+      ) : null}
+      {/* Where it is working, in the words the rack shares. Only for a module
+          that acts on a range at all — there is nothing spectral about a
+          limiter, and a ruler under one would be noise. */}
+      {copy?.band && typeof params.frequency === "number" ? (
+        <FxBandRuler band={copy.band} at={params.frequency} />
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * Everything below the header: does-copy, the one-knob face, and Details. The
+ * derived and primary knobs are already their own components — what is left
+ * is five independent conditionals deciding which pieces of the open face to
+ * show, which is the section's actual job rather than an avoidable branch.
+ */
+// fallow-ignore-next-line complexity
+export function FxNodeOpenBody({
+  node,
+  registryDef,
+  def,
+  onlyPrimary,
+  primary,
+  derived,
+  profile,
+  oneKnob,
+  details,
+  onToggleDetails,
+  copy,
+  params,
+  index,
+  disabled,
+  bypassed,
+  automatedTargets,
+  liveAutomationValues,
+  onUpdate,
+  onPreview,
+  onAutomateParam,
+  onRemoveParamAutomation,
+  trackKind,
+}: FxNodeControlHandlers & {
+  node: HfAudioFxNode;
+  registryDef: HfAudioFxDef;
+  def: HfAudioFxDef;
+  onlyPrimary: HfAudioFxDef;
+  primary: string | null;
+  derived: HfAudioFxParam | null;
+  profile: ReturnType<typeof getAudioFxProfile>;
+  oneKnob: boolean;
+  details: boolean;
+  onToggleDetails(): void;
+  copy: (typeof EFFECT_COPY)[string] | undefined;
+  params: HfAudioFxParamValues;
+  index: number;
+  disabled?: boolean;
+  bypassed: boolean;
+}) {
+  return (
+    <>
+      {/* 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-2">
+          {copy.does}
+        </p>
+      ) : null}
+      {!details ? (
+        <FxNodeDerivedKnob
+          node={node}
+          derived={derived}
+          profile={profile}
+          disabled={disabled}
+          bypassed={bypassed}
+          params={params}
+          index={index}
+          onPreview={onPreview}
+          onUpdate={onUpdate}
+          trackKind={trackKind}
+        />
+      ) : null}
+      {!details ? (
+        <FxNodePrimaryKnob
+          node={node}
+          onlyPrimary={onlyPrimary}
+          primary={primary}
+          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}
+      {/* The DSP name lives on the disclosure, so it is read at the moment
+          the author asks what this really is — and never before. */}
+      {oneKnob ? (
+        <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-2 hover:text-panel-text-0"
+          aria-expanded={details}
+          onClick={onToggleDetails}
+        >
+          <span aria-hidden="true">{details ? "▾" : "▸"}</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-2">
+          Details — {registryDef.label}
+        </p>
+      )}
+      {details || !oneKnob ? (
+        <FxNodeParams
+          node={node}
+          def={def}
+          index={index}
+          disabled={Boolean(disabled) || bypassed}
+          automatedTargets={automatedTargets}
+          liveAutomationValues={liveAutomationValues}
+          onUpdate={onUpdate}
+          onPreview={onPreview}
+          onAutomateParam={onAutomateParam}
+          onRemoveParamAutomation={onRemoveParamAutomation}
+          trackKind={trackKind}
+        />
+      ) : null}
+    </>
+  );
+}

package/src/components/editor/propertyPanelFxNodeParams.tsx

@@ -0,0 +1,112 @@
+/**
+ * An open effect's knobs, with whatever automation surface applies to them.
+ *
+ * Split into its own file — rather than living in `propertyPanelFxNodeRow.tsx`
+ * or `propertyPanelFxNodeOpenBody.tsx` — because both of those import it: it
+ * backs the row's own Details disclosure AND the open face's derived/primary
+ * knobs, and either owning file would have made the other import a cycle.
+ */
+
+import {
+  defaultAudioFxParams,
+  type HfAudioFxDef,
+  type HfAudioFxNode,
+  type HfAudioFxParamValues,
+} from "@hyperframes/core/audio-fx";
+import { fxAutomationTarget } from "@hyperframes/core/audio-automation";
+import { trackParamCommitted } from "./audioFxTelemetry.js";
+import { FxParams } from "./propertyPanelFxControls.js";
+
+/**
+ * Which of an effect's knobs already have a lane.
+ *
+ * A lane addresses a node by id, so a node the panel has not yet given one
+ * cannot be automated at all. Adding an effect mints the id, so this only
+ * affects chains written before ids existed.
+ */
+function automatedKeysOf(
+  node: HfAudioFxNode,
+  params: readonly { key: string }[],
+  automatedTargets: ReadonlySet<string> | undefined,
+): Set<string> {
+  if (!node.id || !automatedTargets) return new Set();
+  const nodeId = node.id;
+  return new Set(
+    params.filter((p) => automatedTargets.has(fxAutomationTarget(nodeId, p.key))).map((p) => p.key),
+  );
+}
+
+/**
+ * Wiring a knob row hands down to whatever renders it — shared between
+ * `FxNodeParams` and `FxNodeOpenBody`, which both sit between the row and the
+ * controls.
+ */
+export interface FxNodeControlHandlers {
+  automatedTargets?: ReadonlySet<string>;
+  liveAutomationValues?: ReadonlyMap<string, number>;
+  onUpdate(index: number, patch: Partial<HfAudioFxNode>): void;
+  onPreview(index: number, params: HfAudioFxParamValues): void;
+  onAutomateParam?(nodeId: string, paramKey: string): void;
+  onRemoveParamAutomation?(nodeId: string, paramKey: string): void;
+  trackKind?: string;
+}
+
+export function FxNodeParams({
+  node,
+  def,
+  index,
+  disabled,
+  automatedTargets,
+  liveAutomationValues,
+  onUpdate,
+  onPreview,
+  onAutomateParam,
+  onRemoveParamAutomation,
+  trackKind,
+}: FxNodeControlHandlers & {
+  node: HfAudioFxNode;
+  def: HfAudioFxDef;
+  index: number;
+  disabled: boolean;
+}) {
+  const nodeId = node.id;
+  // Lanes address a node by id; the controls know their own parameter keys. This
+  // is the one place that translation belongs.
+  const liveValues = ((): Map<string, number> | undefined => {
+    if (!nodeId || !liveAutomationValues?.size) return undefined;
+    const byKey = new Map<string, number>();
+    for (const param of def.params) {
+      const live = liveAutomationValues.get(fxAutomationTarget(nodeId, param.key));
+      if (live !== undefined) byKey.set(param.key, live);
+    }
+    return byKey;
+  })();
+  return (
+    <FxParams
+      def={def}
+      params={node.params ?? defaultAudioFxParams(node.type)}
+      liveValues={liveValues}
+      disabled={disabled}
+      onChange={(params: HfAudioFxParamValues) => onPreview(index, params)}
+      onCommit={(next: HfAudioFxParamValues) => {
+        // Which knob actually moved. `onCommit` hands over the whole parameter
+        // set, so without the diff every commit would report the first key and
+        // the numbers would say authors only ever touch "frequency".
+        const before = node.params ?? defaultAudioFxParams(node.type);
+        for (const [key, value] of Object.entries(next)) {
+          if (before[key] === value) continue;
+          if (typeof value !== "number" && typeof value !== "string") continue;
+          trackParamCommitted(node.type, key, value, "details", { trackKind });
+        }
+        onUpdate(index, { params: next });
+      }}
+      automatedKeys={automatedKeysOf(node, def.params, automatedTargets)}
+      onAutomate={nodeId && onAutomateParam ? (key) => onAutomateParam(nodeId, key) : undefined}
+      onRemoveAutomation={
+        nodeId && onRemoveParamAutomation
+          ? (key) => onRemoveParamAutomation(nodeId, key)
+          : undefined
+      }
+    />
+  );
+}