feat(studio): bend a fade by dragging its own line

Picking a curve used to be a double-click on a 9px grip that cycled through
three shapes. Nothing advertised the gesture, you could not see the options
before committing to one, and getting back to where you started meant going
all the way round.

The line is now the control. A dot sits on the curve's midpoint and
dragging it up or down bends the fade, live, with the curve following the
pointer rather than approaching it: the pointer's height inside the clip IS
the level the curve must reach halfway through, and `fadeCurveThroughMidpoint`
returns the bend that does it. Drag back through the middle and the fade is
straight again, exactly, because the two directions are inverse functions.

Both media now draw one shape rather than two lookalikes.
`envelopeCurveForFade` is the whole conversion: a fade is `p^(2^(-2·bend))`
and an envelope segment is `x^(2^(2·curve))`, so an audio fade and a visual
one differ by a sign and nothing else. That collapses the two samplers into
one and is asserted point by point, since the two are stored in different
places and reached through different code.

The dot only appears once there is a fade to bend. On a clip with none there
is no line to pull, and the corner grips are what start one.

Author: miguel-heygen

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

@@ -2,12 +2,14 @@ import { useCallback, useRef, useState } from "react";
 import type { PointerEvent as ReactPointerEvent } from "react";
 import {
   clampClipFades,
+  fadeSampler,
   fadeWedgePath,
   MIN_FADE_SECONDS,
   type ClipFades,
-  type FadeCurve,
   type FadeSampler,
 } from "./clipFades";
+import { bendFromPointer, bendHandlePosition } from "./clipFadeBendDrag";
+import { FADE_CURVE_LIMIT } from "@hyperframes/core/clip-fade";
 
 /**
  * The fade grips on a clip's top corners, and the wedges they draw.
@@ -26,8 +28,9 @@ export interface TimelineClipFadesProps {
   duration: number;
   pixelsPerSecond: number;
   width: number;
-  curve: FadeCurve;
-  /** How the level rises across the fade — the medium decides. */
+  /** How far the fade is bent; 0 is a straight ramp. */
+  curve: number;
+  /** How the level rises across the fade, read back from where it is kept. */
   sample: FadeSampler;
   /**
    * The clip's accent. The same colour, weight and opacity the automation lane
@@ -40,8 +43,8 @@ export interface TimelineClipFadesProps {
   showGrips: boolean;
   /** True when this is not the selected clip, which is what makes it editable. */
   readOnly: boolean;
-  /** Double-clicking a grip steps the fade through its curve shapes. */
-  onCycleCurve(): void;
+  /** Dragging the fade line bends it. Live while dragging, once on release. */
+  onBend(curve: number, persist: boolean): void;
   /** Live during the drag: preview only, never persisted. */
   onPreview(next: ClipFades): void;
   /** Once, on release. */
@@ -51,6 +54,16 @@ export interface TimelineClipFadesProps {
 /** Side of the grip square, in px. Matches the trim handle's visual weight. */
 const GRIP = 9;
 
+/** Diameter of the bend handle. Smaller than a grip: it is a finer adjustment,
+ *  and it sits on the line rather than on a corner you throw the pointer at. */
+const BEND = 7;
+
+/** What the bend reads as, for a title and for a screen reader. */
+function bendLabel(curve: number): string {
+  if (Math.abs(curve) < 0.02) return "Straight";
+  return curve < 0 ? "Starts slow, finishes fast" : "Starts fast, finishes slow";
+}
+
 /**
  * Vertical units the wedge is drawn in. A clip's height is set by the row, and
  * sometimes by `bottom` rather than a number, so the overlay draws in its own
@@ -71,21 +84,27 @@ export function TimelineClipFades({
   readOnly,
   onPreview,
   onCommit,
-  onCycleCurve,
+  onBend,
 }: TimelineClipFadesProps) {
   // While dragging, the drawn fades come from here: the committed value only
   // catches up once the write lands, and the wedge has to track the pointer.
   const [draft, setDraft] = useState<ClipFades | null>(null);
+  const [bendDraft, setBendDraft] = useState<number | null>(null);
   const dragRef = useRef<{ edge: "in" | "out"; originX: number; from: ClipFades } | null>(null);
+  const bendRef = useRef<{ top: number; height: number } | null>(null);
+  const hostRef = useRef<HTMLDivElement | null>(null);
   const shown = draft ?? fades;
+  // The bend is previewed the same way the lengths are: the committed value
+  // only catches up once the write lands, and the line has to stay under the
+  // pointer until then.
+  const shownCurve = bendDraft ?? curve;
+  const shownSample = bendDraft === null ? sample : fadeSampler(bendDraft);
 
   const onGripDown = useCallback(
     (edge: "in" | "out", event: ReactPointerEvent) => {
       if (event.button !== 0) return;
       // The grip sits on top of the trim handle and inside the clip body; both
-      // would otherwise start their own gesture from this same press. NOT
-      // preventDefault: that suppresses the compatibility click events, and the
-      // double-click that cycles the curve is one of them.
+      // would otherwise start their own gesture from this same press.
       event.stopPropagation();
       event.currentTarget.setPointerCapture(event.pointerId);
       dragRef.current = { edge, originX: event.clientX, from: fades };
@@ -126,15 +145,108 @@ export function TimelineClipFades({
       const from = dragRef.current?.from;
       dragRef.current = null;
       setDraft(null);
-      // A press that moved nothing — the first half of a double-click, or a
-      // mis-aimed click — must not write the same fade back to the file.
+      // A press that moved nothing must not write the same fade back to the
+      // file: a mis-aimed click is not an edit.
       if (next && from && (next.fadeIn !== from.fadeIn || next.fadeOut !== from.fadeOut)) {
         onCommit(next);
       }
     },
     [onCommit, resolveDrag],
   );
 
+  /**
+   * The bend drag. It measures the clip's own pixel box on the way down rather
+   * than taking a height prop, because a clip row is sometimes sized by
+   * `bottom` and so has no number to pass down.
+   */
+  const onBendDown = useCallback((event: ReactPointerEvent) => {
+    if (event.button !== 0) return;
+    event.stopPropagation();
+    const host = hostRef.current;
+    if (!host) return;
+    const box = host.getBoundingClientRect();
+    if (!(box.height > 0)) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    bendRef.current = { top: box.top, height: box.height };
+  }, []);
+
+  const resolveBend = useCallback((clientY: number): number | null => {
+    const drag = bendRef.current;
+    return drag ? bendFromPointer(clientY - drag.top, drag.height) : null;
+  }, []);
+
+  const onBendMove = useCallback(
+    (event: ReactPointerEvent) => {
+      const next = resolveBend(event.clientY);
+      if (next === null) return;
+      setBendDraft(next);
+      onBend(next, false);
+    },
+    [onBend, resolveBend],
+  );
+
+  const onBendUp = useCallback(
+    (event: ReactPointerEvent) => {
+      const next = resolveBend(event.clientY);
+      bendRef.current = null;
+      setBendDraft(null);
+      if (next !== null && next !== curve) onBend(next, true);
+    },
+    [curve, onBend, resolveBend],
+  );
+
+  /**
+   * The handle that bends a fade, sitting on the curve's own midpoint so it
+   * stays under the pointer as the shape changes. Only present once there is a
+   * fade to bend: with none there is no line to pull, and the corner grips are
+   * what start one.
+   */
+  const bendFor = (edge: "in" | "out") => {
+    const seconds = edge === "in" ? shown.fadeIn : shown.fadeOut;
+    if (seconds < MIN_FADE_SECONDS) return null;
+    const at = bendHandlePosition({
+      edge,
+      seconds,
+      pixelsPerSecond,
+      width,
+      height: hostRef.current?.getBoundingClientRect().height ?? 0,
+      level: shownSample(0.5),
+    });
+    if (!at) return null;
+    const label = bendLabel(shownCurve);
+    return (
+      <div
+        key={`bend-${edge}`}
+        role="slider"
+        tabIndex={-1}
+        aria-label={edge === "in" ? "Fade in curve" : "Fade out curve"}
+        aria-valuemin={-FADE_CURVE_LIMIT}
+        aria-valuemax={FADE_CURVE_LIMIT}
+        aria-valuenow={shownCurve}
+        aria-valuetext={label}
+        data-clip-fade-bend={edge}
+        onPointerDown={onBendDown}
+        onPointerMove={onBendMove}
+        onPointerUp={onBendUp}
+        onPointerCancel={onBendUp}
+        title={`Drag up or down to bend this fade. ${label}`}
+        style={{
+          position: "absolute",
+          left: at.x - BEND / 2,
+          top: at.y - BEND / 2,
+          width: BEND,
+          height: BEND,
+          borderRadius: "50%",
+          background: accent,
+          boxShadow: "0 0 0 1.5px rgba(0,0,0,0.55)",
+          cursor: "ns-resize",
+          pointerEvents: "auto",
+          zIndex: 6,
+        }}
+      />
+    );
+  };
+
   const gripFor = (edge: "in" | "out") => {
     const seconds = edge === "in" ? shown.fadeIn : shown.fadeOut;
     const span = Math.min(seconds * pixelsPerSecond, width);
@@ -156,11 +268,7 @@ export function TimelineClipFades({
         onPointerMove={onGripMove}
         onPointerUp={onGripUp}
         onPointerCancel={onGripUp}
-        onDoubleClick={(event) => {
-          event.stopPropagation();
-          if (seconds > 0) onCycleCurve();
-        }}
-        title={`Fade ${edge}: drag to set its length, double-click to change its ${curve} curve`}
+        title={`Fade ${edge}: drag to set its length. Drag the dot on the line to bend it.`}
         style={{
           position: "absolute",
           left: x - GRIP / 2,
@@ -171,14 +279,17 @@ export function TimelineClipFades({
           background: "rgba(255,255,255,0.9)",
           boxShadow: "0 0 0 1px rgba(0,0,0,0.5)",
           cursor: "ew-resize",
+          pointerEvents: "auto",
           zIndex: 6,
         }}
       />
     );
   };
 
   return (
-    <>
+    // One positioned box owns the overlay so the bend handle has a parent whose
+    // height it can measure, and so both handles share the clip's coordinates.
+    <div ref={hostRef} style={{ position: "absolute", inset: 0, pointerEvents: "none" }}>
       <svg
         aria-hidden="true"
         width="100%"
@@ -193,7 +304,7 @@ export function TimelineClipFades({
           const { line, fill } = fadeWedgePath({
             edge,
             seconds,
-            sample,
+            sample: shownSample,
             pixelsPerSecond,
             width,
             height: VIEW_HEIGHT,
@@ -218,6 +329,7 @@ export function TimelineClipFades({
         })}
       </svg>
       {showGrips && !readOnly && (["in", "out"] as const).map(gripFor)}
-    </>
+      {showGrips && !readOnly && (["in", "out"] as const).map(bendFor)}
+    </div>
   );
 }

packages/studio/src/player/components/clipFadeBendDrag.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { fadeEase } from "@hyperframes/core/clip-fade";
+import { bendFromPointer, bendHandlePosition } from "./clipFadeBendDrag";
+import { fadeSampler } from "./clipFades";
+
+const HEIGHT = 40;
+
+describe("bendFromPointer", () => {
+  it("is straight when the pointer sits on the line", () => {
+    expect(bendFromPointer(HEIGHT / 2, HEIGHT)).toBeCloseTo(0, 6);
+  });
+
+  it("puts the curve under the pointer, which is the whole gesture", () => {
+    for (const offsetY of [6, 12, 20, 28, 34]) {
+      const bend = bendFromPointer(offsetY, HEIGHT);
+      const level = fadeEase(0.5, bend);
+      expect((1 - level) * HEIGHT).toBeCloseTo(offsetY, 0);
+    }
+  });
+
+  it("bends up for a fade that gets loud early and down for one that waits", () => {
+    // Smaller offsetY is higher on the screen, so the level halfway through is
+    // greater: the fade has already done most of its work.
+    expect(bendFromPointer(8, HEIGHT)).toBeGreaterThan(0);
+    expect(bendFromPointer(32, HEIGHT)).toBeLessThan(0);
+  });
+
+  it("stops following a pointer dragged past the range instead of inverting", () => {
+    expect(bendFromPointer(-200, HEIGHT)).toBe(1);
+    expect(bendFromPointer(400, HEIGHT)).toBe(-1);
+  });
+
+  it("reports straight rather than dividing by a clip with no height", () => {
+    expect(bendFromPointer(10, 0)).toBe(0);
+  });
+});
+
+describe("bendHandlePosition", () => {
+  const base = { seconds: 2, pixelsPerSecond: 25, width: 200, height: HEIGHT };
+
+  it("sits halfway along a fade in, and halfway along a fade out", () => {
+    expect(bendHandlePosition({ ...base, edge: "in", level: 0.5 })?.x).toBeCloseTo(25, 6);
+    expect(bendHandlePosition({ ...base, edge: "out", level: 0.5 })?.x).toBeCloseTo(175, 6);
+  });
+
+  it("rides the curve, so the handle stays under the pointer while bending", () => {
+    for (const bend of [-1, -0.5, 0, 0.5, 1]) {
+      const level = fadeSampler(bend)(0.5);
+      const at = bendHandlePosition({ ...base, edge: "in", level });
+      expect(at?.y).toBeCloseTo((1 - level) * HEIGHT, 6);
+    }
+  });
+
+  it("has nowhere to sit on a fade with no width or a clip with no height", () => {
+    expect(bendHandlePosition({ ...base, edge: "in", level: 0.5, seconds: 0 })).toBeNull();
+    expect(bendHandlePosition({ ...base, edge: "in", level: 0.5, height: 0 })).toBeNull();
+  });
+
+  it("never runs past a fade clamped to the clip's own width", () => {
+    const at = bendHandlePosition({ ...base, edge: "in", level: 0.5, seconds: 999 });
+    expect(at?.x).toBeCloseTo(base.width / 2, 6);
+  });
+});
+
+describe("the drag round-trips", () => {
+  it("lands the handle back where the pointer left it", () => {
+    // Inside the band the bend limit can express: levels from 0.5^4 to 0.5^0.25,
+    // which is roughly 6.4px to 37.5px down a 40px clip.
+    for (const offsetY of [8, 15, 25, 35]) {
+      const bend = bendFromPointer(offsetY, HEIGHT);
+      const at = bendHandlePosition({
+        edge: "in",
+        seconds: 2,
+        pixelsPerSecond: 25,
+        width: 200,
+        height: HEIGHT,
+        level: fadeSampler(bend)(0.5),
+      });
+      expect(at?.y).toBeCloseTo(offsetY, 0);
+    }
+  });
+
+  it("parks the handle at the limit when the pointer goes further than a bend can", () => {
+    const at = (offsetY: number) =>
+      bendHandlePosition({
+        edge: "in",
+        seconds: 2,
+        pixelsPerSecond: 25,
+        width: 200,
+        height: HEIGHT,
+        level: fadeSampler(bendFromPointer(offsetY, HEIGHT))(0.5),
+      })?.y;
+    // Dragged off the top of the clip and well past it: both stop in the same
+    // place rather than the curve flipping over.
+    expect(at(0)).toBeCloseTo(at(-500)!, 6);
+    expect(at(HEIGHT)).toBeCloseTo(at(500)!, 6);
+  });
+});