@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/CurvePane.tsx

@@ -0,0 +1,508 @@
+// GRAPH MODE: the dock's track area, showing HOW something moves.
+//
+// The rows answer "when does this happen" and this answers "how does it move",
+// and they are two resolutions of one subject — which is why this is a MODE of
+// the dock rather than a second panel beside it. A graph stacked under forty
+// rows gets the height neither of them can spare.
+//
+// ── WHAT IS HERE AND WHAT IS SHARED ─────────────────────────────────────────
+//
+// The curve itself is `@dailies-studio/timeline`'s `CurveGraph` over the
+// adapter in curveModel.ts. What this file owns is the TOOLBAR (scope, ease
+// presets, the one key's Frame and Value, Normalize, Frame all), the LEFT
+// COLUMN (which curve is focused, which others are shown beside it, each in
+// its colour with its value at the playhead), the empty states in the plot,
+// and the rule for what the pane is looking at when the author has not said.
+//
+// The column is the same width as the rows' label column (`useLabelWidth`, the
+// rail track's shown width), so switching modes does not move the vertical
+// rule the whole panel is read against.
+import {
+  CurveGraph,
+  EASE_PRESETS,
+  KeyframeFields,
+  PlayheadChip,
+  PlayheadLine,
+  matchPreset,
+} from "@dailies-studio/timeline";
+import type { KeyframeAddr, KeyframeFieldsView } from "@dailies-studio/timeline";
+import { IconChevronDown, IconDiamond, formatValue, useContextMenu } from "@dailies-studio/ui";
+import { useEffect, useMemo, useState } from "react";
+import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactElement } from "react";
+import type { Ease } from "@dailies-studio/engine";
+import { containerFrame, defDurationFrames, homeOf, isDefId } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { useShotEditor, useShotEditorHot, useStore } from "../../state/context.js";
+import { primaryKeyframe } from "../../state/types.js";
+import type { ShotEditorState } from "../../state/types.js";
+import { useLabelWidth } from "./labelWidth.js";
+import { keyframeMenuEntries, keyframeMenuTargets } from "./keyframeMenu.js";
+import {
+  allAnimatedRows,
+  curveRowId,
+  curveRowsOf,
+  curveSubjectLayer,
+  curveTracksOf,
+  curveValueAt,
+  parseCurveRowId,
+  sameSubject,
+  shotCurveModel,
+  unitOf,
+} from "./curveModel.js";
+import type { CurveSubject } from "./curveModel.js";
+
+/** The list's curve colours, in order. Tokens (shotTokens.css), so each theme
+ *  sets its own readable values. A fifth curve takes the first colour again. */
+const CURVE_COLORS = ["var(--curve-1)", "var(--curve-2)", "var(--curve-3)", "var(--curve-4)"] as const;
+
+/** The toolbar's ease presets: the five shapes the graph board names, each one
+ *  of `EASE_PRESETS` (so the ease written is the palette's own), with the
+ *  board's glyph for the shape. */
+const TOOLBAR_PRESETS: ReadonlyArray<{ id: string; label: string; glyph: string }> = [
+  { id: "linear", label: "Linear", glyph: "M2 12L12 2" },
+  { id: "ease-in", label: "Ease in", glyph: "M2 12C8 12 10 8 12 2" },
+  { id: "ease-out", label: "Ease out", glyph: "M2 12C4 6 6 2 12 2" },
+  { id: "ease-in-out", label: "Ease in-out", glyph: "M2 12C7 12 7 2 12 2" },
+  { id: "hold", label: "Hold", glyph: "M2 12H8V2H12" },
+];
+
+const presetEase = (id: string): Ease | undefined => EASE_PRESETS.find((p) => p.id === id)?.ease;
+
+/** Which curves the list shows: the selection's owner, or every animated
+ *  element in the container. */
+type CurveScope = "selected" | "all";
+
+export function CurvePane() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const selection = useShotEditor((s) => s.selection);
+  const selectedKeyframes = useShotEditor((s) => s.selectedKeyframes);
+  const selectedKeyframe = primaryKeyframe({ selectedKeyframes });
+  const ppf = useShotEditor((s) => s.dockPpf);
+  const labelWidth = useLabelWidth();
+  // ── THE FRAME STAYS OUT OF THIS PANE ─────────────────────────────────────
+  //
+  // The dock's rule is that the frame stays out of the dock and lives in
+  // leaves, and this pane keeps it: the graph's playhead (`CurvePlayhead`,
+  // drawn inside `CurveGraph`) and each curve's value at the playhead
+  // (`CurveRowValue`) subscribe to it, and nothing else here does. The model
+  // is built without it: a frame laid over the model per tick re-rendered
+  // the whole pane and the graph sixty times a second for a playhead line.
+
+  const [scope, setScope] = useState<CurveScope>("selected");
+  const [normalize, setNormalize] = useState(false);
+  const [frameAll, setFrameAll] = useState(0);
+  /** The curves shown BESIDE the focused one, by row id. Local, like the dock's
+   *  own disclosure sets: it is about this panel's shape and nothing else. */
+  const [shownIds, setShownIds] = useState<ReadonlySet<string>>(() => new Set());
+
+  const subject = curveSubjectLayer(
+    { selectedKeyframe, selection, containerId: editingDef ?? sceneId },
+    doc ?? undefined,
+  );
+
+  const rows = useMemo(() => {
+    if (doc === null || subject === null) return [];
+    return scope === "all"
+      ? allAnimatedRows(doc, subject.containerId)
+      : curveRowsOf(doc, subject.containerId, subject.layerId);
+  }, [doc, scope, subject?.containerId, subject?.layerId]);
+
+  /**
+   * Which curve is drawn on top and edited.
+   *
+   * Seeded from the selected keyframe, and re-seeded whenever that moves to a
+   * different property — clicking a diamond in the rows and then switching to
+   * the graph should land on the thing that was clicked.
+   */
+  const [focus, setFocus] = useState<CurveSubject | null>(null);
+  const wanted = useMemo(() => {
+    if (selectedKeyframe === null) return null;
+    const match = rows.find(
+      (r) =>
+        r.subject.path === selectedKeyframe.path &&
+        r.subject.layerId === selectedKeyframe.layerId &&
+        r.numberTrack,
+    );
+    return match?.subject ?? null;
+  }, [rows, selectedKeyframe?.path, selectedKeyframe?.layerId]);
+  useEffect(() => {
+    if (wanted !== null && !sameSubject(wanted, focus)) setFocus(wanted);
+  }, [wanted]);
+  // A pane that opens on nothing is a panel that reads as broken, so it falls
+  // back to the first curve there is. Not stored: a fallback that persisted
+  // would fight the seeding above on the next selection.
+  const focused =
+    focus !== null && rows.some((r) => r.id === curveIdOf(focus) && r.numberTrack)
+      ? focus
+      : (rows.find((r) => r.numberTrack)?.subject ?? null);
+
+  // EACH CURVE'S COLOUR, by its place among the curves in the list, so a dot
+  // and its line always agree and a curve keeps its colour as others are shown.
+  const colors = useMemo(() => {
+    const out = new Map<string, string>();
+    rows.filter((r) => r.numberTrack).forEach((r, i) => out.set(r.id, CURVE_COLORS[i % CURVE_COLORS.length]!));
+    return out;
+  }, [rows]);
+  const shown = useMemo(
+    () => rows.filter((r) => r.numberTrack && shownIds.has(r.id)).map((r) => r.subject),
+    [rows, shownIds],
+  );
+
+  const defOpen = editingDef !== null && subject !== null && isDefId(subject.containerId);
+  /** The playhead in the subject's own frames, read by the leaves. Held to
+   *  the Shot's own frames: a cut the transport plays leaves the cold
+   *  `sceneId` on the Shot it left until Pause, and the frames past it are
+   *  another Shot's, which this graph does not draw. */
+  const containerId = subject?.containerId ?? null;
+  const containerSpan = defOpen || doc === null || containerId === null ? 0 : (doc.scenesById[containerId]?.durationFrames ?? 0);
+  const localFrameOf = (s: ShotEditorState): number =>
+    doc === null || containerId === null
+      ? 0
+      : defOpen
+        ? s.defFrame
+        : Math.min(containerFrame(doc, containerId, s.frame), Math.max(0, containerSpan - 1));
+
+  const model = useMemo(() => {
+    if (doc === null || subject === null) return null;
+    const def = defOpen ? doc.components?.[subject.containerId] : undefined;
+    const containerFrames =
+      def !== undefined
+        ? defDurationFrames(def)
+        : (doc.scenesById[subject.containerId]?.durationFrames ?? 0);
+    return shotCurveModel({
+      store,
+      doc,
+      containerId: subject.containerId,
+      containerFrames,
+      frame: 0,
+      fps: doc.fps,
+      pxPerFrame: ppf,
+      focus: focused,
+      rows,
+      selected: selectedKeyframes,
+      defOpen,
+      visible: shown,
+      colors,
+    });
+  }, [store, doc, subject?.containerId, subject?.layerId, defOpen, ppf, focused, rows, selectedKeyframes, shown, colors]);
+
+  // THE SAME KEYFRAME MENU THE ROWS OPEN. The graph knows a circle was
+  // right-clicked and nothing else — ease presets are this lane's vocabulary, so
+  // the entries are built here, from the shared builder, against the real track.
+  const menu = useContextMenu();
+  const openKeyMenu = (ref: KeyframeAddr, at: { x: number; y: number }): void => {
+    const subject = parseCurveRowId(ref.rowId);
+    if (doc === null || subject === null) return;
+    const track = curveTracksOf(doc, subject.containerId, subject.layerId)?.[subject.path];
+    const index = track?.keyframes.findIndex((k) => k.id === ref.keyframeId) ?? -1;
+    const key = index < 0 ? undefined : track!.keyframes[index]!;
+    if (track === undefined || key === undefined) return;
+    const sel = {
+      containerId: subject.containerId,
+      layerId: subject.layerId,
+      path: subject.path,
+      frame: key.frame,
+    };
+    const targets = keyframeMenuTargets(store.getState().selectedKeyframes, sel);
+    if (targets.length === 1) store.selectKeyframe(sel);
+    menu.open(
+      at,
+      keyframeMenuEntries({
+        store,
+        key: {
+          kind: track.kind,
+          ease: key.easeOut,
+          last: index === track.keyframes.length - 1,
+          curved: track.spatialInterp !== undefined,
+        },
+        targets,
+        at: sel,
+      }),
+    );
+  };
+
+  if (doc === null) return null;
+
+  const openScopeMenu = (e: ReactMouseEvent<HTMLButtonElement>): void => {
+    const box = e.currentTarget.getBoundingClientRect();
+    menu.open({ x: box.left, y: box.bottom + 4 }, [
+      { kind: "action", id: "selected", label: "Selected", checked: scope === "selected", onSelect: () => setScope("selected") },
+      { kind: "action", id: "all", label: "All animated", checked: scope === "all", onSelect: () => setScope("all") },
+    ]);
+  };
+
+  // ── THE EASE PRESETS ACT ON THE SELECTED KEYS ───────────────────────────
+  //
+  // The whole selection, on every track, through the store's one batched
+  // write: one undo step for N keys, the same write the inspector's preset
+  // select makes. The active chip is the preset every selected key already
+  // has; a mixed or custom selection lights none.
+  const selectedEases = selectedKeyframes.flatMap((at) => {
+    const key = curveTracksOf(doc, at.containerId, at.layerId)?.[at.path]?.keyframes.find((k) => k.frame === at.frame);
+    return key === undefined ? [] : [key.easeOut];
+  });
+  const presetIds = new Set(selectedEases.map(matchPreset));
+  const activePreset = presetIds.size === 1 ? [...presetIds][0]! : null;
+  const noKeys = selectedKeyframes.length === 0;
+  const applyPreset = (id: string): void => {
+    const ease = presetEase(id);
+    if (noKeys || ease === undefined) return;
+    store.setKeyframesEase(
+      selectedKeyframes.map((k) => ({ containerId: k.containerId, layerId: k.layerId, path: k.path, frame: k.frame })),
+      ease,
+    );
+  };
+
+  // THE ONE KEY'S FRAME AND VALUE, editable in the toolbar: the inspector's own
+  // store-free fields, through the graph's gesture, so a typed frame is one
+  // undo entry exactly as it is there. Only for ONE key on the focused curve:
+  // a frame typed into a set has no one meaning.
+  const only = selectedKeyframes.length === 1 ? selectedKeyframes[0]! : null;
+  const onlyKey =
+    only === null || focused === null || model?.focusedCurve == null
+      ? undefined
+      : only.containerId === focused.containerId && only.layerId === focused.layerId && only.path === focused.path
+        ? model.focusedCurve.keyframes.find((k) => k.frame === only.frame)
+        : undefined;
+  const fields: KeyframeFieldsView | null =
+    onlyKey === undefined || focused === null
+      ? null
+      : {
+          ref: { rowId: curveRowId(focused), keyframeId: onlyKey.id },
+          frame: onlyKey.frame,
+          value: onlyKey.value,
+          ...unitOf(focused.path),
+        };
+
+  // WHOSE CURVES THESE ARE, named over each owner's rows: the rows are
+  // property names ("Opacity", "X"), and without the owner a column of them
+  // does not say which element the graph is drawing. The layer's own label, or
+  // the shot's name for a shot-level track.
+  const ownerName = (containerId: string, layerId: string | null): string | null =>
+    layerId === null
+      ? (doc.scenesById[containerId]?.name ?? null)
+      : (homeOf(doc, containerId)?.layersById[layerId]?.label ?? null);
+
+  const curveCount = rows.filter((r) => r.numberTrack).length;
+  const toggleShown = (id: string): void =>
+    setShownIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  const list: ReactElement[] = [];
+  let owner: string | undefined;
+  for (const row of rows) {
+    const rowOwner = row.subject.layerId ?? "";
+    if (rowOwner !== owner) {
+      owner = rowOwner;
+      const name = ownerName(row.subject.containerId, row.subject.layerId);
+      // Not a `.curve-row`: a header, never a focus target. The first one sits
+      // beside the ruler, the same 28px tall.
+      if (name !== null) {
+        list.push(
+          <div key={`owner-${rowOwner}`} className="curve-scope">
+            <IconDiamond className="curve-scope-icon" aria-hidden="true" />
+            <span className="curve-scope-name">{name}</span>
+          </div>,
+        );
+      }
+    }
+    const isFocused = row.id === curveIdOf(focused);
+    const isShown = row.numberTrack && (isFocused || shownIds.has(row.id));
+    const color = colors.get(row.id);
+    list.push(
+      <button
+        key={row.id}
+        type="button"
+        className={`curve-row${isFocused ? " is-focused" : ""}${isShown ? " is-shown" : ""}${row.numberTrack ? "" : " is-flat"}`}
+        style={{ "--depth": row.depth, ...(color === undefined ? {} : { "--curve-color": color }) } as CSSProperties}
+        data-testid={`curve-row-${row.subject.path}${row.subject.component === undefined ? "" : `-${row.subject.component}`}`}
+        // A NON-NUMERIC ROW IS NOT A CURVE. A colour has no value axis, so
+        // its row is a label and the graph keeps whatever it was drawing —
+        // rather than blanking, which reads as breakage.
+        disabled={!row.numberTrack}
+        title={
+          !row.numberTrack
+            ? `${row.label} has no value axis to draw`
+            : isFocused
+              ? `Editing the ${row.label} curve`
+              : `Edit the ${row.label} curve. Shift-click to ${shownIds.has(row.id) ? "hide it" : "show it beside the focused one"}`
+        }
+        onClick={(e) => {
+          if (e.shiftKey) {
+            if (!isFocused) toggleShown(row.id);
+            return;
+          }
+          setFocus(row.subject);
+        }}
+      >
+        <span className={`curve-row-dot${row.numberTrack ? "" : " is-none"}`} aria-hidden="true" />
+        <span className="curve-row-name">{row.label}</span>
+        {row.numberTrack && <CurveRowValue doc={doc} subject={row.subject} frameOf={localFrameOf} />}
+      </button>,
+    );
+  }
+
+  const graphReady = model !== null && model.focusedCurve !== null;
+
+  return (
+    <div className="curve-pane" data-testid="curve-pane">
+      {menu.menu}
+      <div className="curve-toolbar">
+        <div className="curve-toolbar-scope" style={{ width: labelWidth }}>
+          <span className="curve-count">Curves · {curveCount}</span>
+          <button
+            type="button"
+            className="curve-scope-btn"
+            aria-haspopup="menu"
+            aria-label={`Show curves: ${scope === "all" ? "All animated" : "Selected"}`}
+            onClick={openScopeMenu}
+          >
+            {scope === "all" ? "All animated" : "Selected"}
+            <IconChevronDown aria-hidden="true" />
+          </button>
+        </div>
+        <div className="curve-toolbar-main">
+          <div className="curve-presets" role="group" aria-label="Ease presets">
+            {TOOLBAR_PRESETS.map((p) => {
+              const active = !noKeys && activePreset === p.id;
+              return (
+                <button
+                  key={p.id}
+                  type="button"
+                  className={`curve-preset${active ? " is-active" : ""}`}
+                  aria-pressed={active}
+                  aria-disabled={noKeys}
+                  title={noKeys ? "Select keyframes to set their ease" : `Set the selected keyframes to ${p.label.toLowerCase()}`}
+                  onClick={() => applyPreset(p.id)}
+                >
+                  <svg className="curve-preset-glyph" viewBox="0 0 14 14" aria-hidden="true">
+                    <path d={p.glyph} />
+                  </svg>
+                  {p.label}
+                </button>
+              );
+            })}
+          </div>
+          <span className="curve-divider" aria-hidden="true" />
+          <div className="curve-readouts">
+            {fields !== null && model !== null ? (
+              <KeyframeFields key={`${fields.ref.rowId}:${fields.ref.keyframeId}`} fields={fields} gesture={model.gesture} bare />
+            ) : (
+              <>
+                <span className="curve-readout" title="Select one keyframe on this curve to edit its frame">
+                  <span className="curve-readout-label">Frame</span>
+                  <span className="curve-readout-value">–</span>
+                </span>
+                <span className="curve-readout" title="Select one keyframe on this curve to edit its value">
+                  <span className="curve-readout-label">Value</span>
+                  <span className="curve-readout-value">–</span>
+                </span>
+              </>
+            )}
+          </div>
+        </div>
+        <div className="curve-toolbar-view">
+          <button
+            type="button"
+            className={`curve-tool${normalize ? " is-on" : ""}`}
+            aria-pressed={normalize}
+            title="Scale every curve to its own range, so their timing reads on one axis"
+            onClick={() => setNormalize((n) => !n)}
+          >
+            Normalize
+          </button>
+          <button
+            type="button"
+            className="curve-tool is-filled"
+            disabled={!graphReady}
+            title="Zoom to fit every key on show"
+            onClick={() => setFrameAll((n) => n + 1)}
+          >
+            Frame all
+          </button>
+        </div>
+      </div>
+      <div className="curve-body">
+        <div className="curve-rows" style={{ width: labelWidth }}>
+          <div className="curve-list">{list}</div>
+          {curveCount > 0 && <div className="curve-hint">Click a curve to edit. Shift-click to show more.</div>}
+        </div>
+        <div className="curve-graph">
+          {/* THE EMPTY STATES SIT IN THE PLOT, where the curve would be: the
+              column beside it is too narrow to hold a sentence, and the plot
+              is the place an author looks when nothing is drawn. */}
+          {rows.length === 0 ? (
+            <div className="curve-empty">
+              {subject === null || (subject.layerId === null && scope === "selected")
+                ? "Keyframe a property to see its curve."
+                : scope === "all"
+                  ? "Nothing in this shot is animated yet. Add a keyframe from the rows or the inspector."
+                  : "This element has no keyframes yet. Add one from the rows or the inspector."}
+            </div>
+          ) : !graphReady ? (
+            <div className="curve-empty">
+              None of these properties has a value axis to draw. Their keys stay in the rows.
+            </div>
+          ) : (
+            <CurveGraph
+              model={model}
+              onKeyContextMenu={openKeyMenu}
+              normalize={normalize}
+              frameAll={frameAll}
+              playhead={({ ppf: scale, offset }) => <CurvePlayhead ppf={scale} offset={offset} frameOf={localFrameOf} />}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/** The graph's playhead, drawn inside `CurveGraph` at its scale and inset, and
+ *  the pane's one leaf that follows the frame with `CurveRowValue`: a played
+ *  frame repaints a line, never the pane or the graph. */
+function CurvePlayhead({
+  ppf,
+  offset,
+  frameOf,
+}: {
+  ppf: number;
+  offset: number;
+  frameOf: (s: ShotEditorState) => number;
+}) {
+  const frame = useShotEditorHot(frameOf);
+  return (
+    <PlayheadLine frame={frame} ppf={ppf} offset={offset} className="curves-playhead">
+      <PlayheadChip frame={frame} />
+    </PlayheadLine>
+  );
+}
+
+/** One curve's value at the playhead, in the list. A leaf on the frame that
+ *  repaints only when its number moves. */
+function CurveRowValue({
+  doc,
+  subject,
+  frameOf,
+}: {
+  doc: Doc3D;
+  subject: CurveSubject;
+  frameOf: (s: ShotEditorState) => number;
+}) {
+  const value = useShotEditorHot((s) => curveValueAt(doc, subject, frameOf(s), doc.fps));
+  return value === null ? null : <span className="curve-row-value">{formatValue(value, 0.01)}</span>;
+}
+
+/** The row id of a subject, or "" for none. THROUGH `curveRowId`, never a
+ *  second spelling of the encoding: the focused comparison and the row's own
+ *  key have to be the same string by construction. */
+function curveIdOf(subject: CurveSubject | null): string {
+  return subject === null ? "" : curveRowId(subject);
+}