@dailies-studio/shot-editor 0.1.0

package/src/panels/timeline/TimelineDock.tsx

@@ -0,0 +1,488 @@
+// The timeline dock: ONE CONTINUOUS MASTER STRIP.
+//
+// ── WHAT DIED HERE, AND WHY ─────────────────────────────────────────────
+//
+// This used to be two levels. A scene strip on top, and underneath it the block
+// tracks of WHICHEVER SCENE THE PLAYHEAD WAS IN — one bit, `state.sceneId`,
+// deciding what half the dock showed. It is a coherent model and it is the wrong
+// one for a video: the author's question is almost never "what is in scene 2",
+// it is "what happens between the logo landing and the price appearing", and
+// those two things are in different scenes. A dock that can only show one scene
+// answers that question by making the author flip between two pictures and hold
+// the join in their head.
+//
+// So every scene's rows are on screen at once, at their master positions,
+// grouped in master order, with the scene boundaries drawn through the tracks.
+// `state.sceneId` survives as the INSPECTOR'S SUBJECT and the URL's, and nothing
+// about this file's layout reads it any more. The scene strip survives too, slim
+// and secondary: it is the only place scenes are created, reordered and trimmed,
+// which is exactly the set of verbs that are about scenes rather than about
+// time.
+//
+// ── WHERE THE SCENE COMES FROM NOW ──────────────────────────────────────
+//
+// Every row carries its own `sceneId` and every gesture passes it to the store.
+// That is not tidiness: `state.sceneId` follows the playhead, so a drag on a row
+// three scenes away would have written to whichever scene the playhead happened
+// to be sitting in.
+//
+// Everything geometric is @dailies-studio/timeline's, unchanged: `Ruler`,
+// `PlayheadLine`, `frameToPx`, `pxToFrame` and `useAnchoredZoom` are about
+// frames and pixels, which the keyframe lane and the block lane agree about.
+// What is NOT reused is `TimelineModel` — see model.ts for why.
+import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { PlayheadLine, Ruler, frameToPx, useAnchoredZoom } from "@dailies-studio/timeline";
+import type { Rational } from "@dailies-studio/engine";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { ResizeHandle } from "../ResizeHandle.js";
+import { DOCK_HEIGHT } from "../../state/panelSize.js";
+import { AudioLane } from "./AudioLane.js";
+import { BlockRow } from "./BlockRow.js";
+import { ChannelRows } from "./ChannelRow.js";
+import { LifespanRow } from "./LifespanRow.js";
+import { MarkerLane } from "./MarkerLane.js";
+import { SceneStrip } from "./SceneStrip.js";
+import { CAMERA_ROW_ID, masterContentFrames, masterDuration, masterRows, sceneBars, timecode } from "./model.js";
+import { collectSnapTargets, snapFrame, snapThresholdFrames } from "./snap.js";
+import type { SnapPress, SnapScope } from "./snap.js";
+
+/** Where the track labels end and the time area begins, in px. */
+export const LABEL_WIDTH = 150;
+
+// ── THE FRAME STAYS OUT OF THIS COMPONENT ─────────────────────────────────
+//
+// During playback the frame changes ~30 times a second, and this component
+// renders the ENTIRE dock — every scene group, camera bar, track row and block
+// bar. When it subscribed to `frame`, all of that reconciled per playback
+// frame. The three things that actually show the frame are leaves below
+// (DockTime, DockReadout, DockPlayhead), each subscribing to `frame` alone, so
+// a playhead tick re-renders three spans and nothing else. If a future reader
+// adds `useShotEditor((s) => s.frame)` back here, playback perf regresses to
+// where it was — don't.
+
+/** The current-time readout, isolated so its per-frame tick stays its own. */
+function DockTime({ fps }: { fps: Rational }) {
+  const frame = useShotEditor((s) => s.frame);
+  return (
+    <span className="dock-time" data-testid="dock-time">
+      {timecode(frame, fps)}
+    </span>
+  );
+}
+
+/** The frame-counter readout, same isolation. */
+function DockReadout({ total }: { total: number }) {
+  const frame = useShotEditor((s) => s.frame);
+  return (
+    <span className="dock-readout" data-testid="dock-readout">
+      {frame} / {Math.max(0, total - 1)}
+    </span>
+  );
+}
+
+/** The playhead, subscribing to the frame itself so its two mount sites ride
+ *  a per-frame tick without dragging the dock along. */
+function DockPlayhead({ ppf }: { ppf: number }) {
+  const frame = useShotEditor((s) => s.frame);
+  return <PlayheadLine frame={frame} ppf={ppf} offset={0} className="dock-playhead" />;
+}
+
+export function TimelineDock() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const isolation = useShotEditor((s) => s.isolation);
+  const playing = useShotEditor((s) => s.playing);
+  const collapsed = useShotEditor((s) => s.dockCollapsed);
+  const ppf = useShotEditor((s) => s.dockPpf);
+  const previewMuted = useShotEditor((s) => s.previewMuted);
+  const previewVolume = useShotEditor((s) => s.previewVolume);
+  const scrollRef = useRef<HTMLDivElement | null>(null);
+  /**
+   * Which layers show their block lanes. LOCAL, not store state: it is about
+   * this panel's shape and nothing else reads it, and the body is hidden rather
+   * than unmounted on collapse (see below) so it survives the one event that
+   * would otherwise lose it.
+   */
+  const [open, setOpen] = useState<ReadonlySet<string>>(() => new Set<string>());
+  /** The frame a live drag has snapped onto, for the guide. Null between drags. */
+  const [guide, setGuide] = useState<number | null>(null);
+
+  // Imperative reads, so the wheel listener never closes over a stale zoom.
+  const read = useCallback(() => store.getState().dockPpf, [store]);
+  const setPxPerFrame = useCallback((next: number) => store.setDockPpf(next), [store]);
+  useAnchoredZoom({
+    scrollRef,
+    labelWidth: LABEL_WIDTH,
+    ppf,
+    min: 0.2,
+    max: 60,
+    read,
+    setPxPerFrame,
+    enabled: !collapsed && doc !== null,
+  });
+
+  // SHIFT+WHEEL PANS. Native and non-passive for `useAnchoredZoom`'s reason: a
+  // React wheel handler is registered passive and cannot preventDefault, so the
+  // page would scroll underneath the pan.
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el === null) return;
+    const onWheel = (e: WheelEvent): void => {
+      if (!e.shiftKey || e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      // A trackpad sends its own horizontal axis; a wheel with one axis sends
+      // deltaY and means the same thing with shift held.
+      el.scrollLeft += e.deltaX !== 0 ? e.deltaX : e.deltaY;
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    return () => el.removeEventListener("wheel", onWheel);
+    // Keyed on whether there IS a document, not on which one: the container
+    // does not exist until one opens, and re-binding a native listener on every
+    // keystroke of an edit would be work for nothing.
+  }, [collapsed, doc === null]);
+
+  /**
+   * A scroll position that cannot be written until the NEXT layout.
+   *
+   * The lane's scrollable width is React-rendered from `ppf` (`timeW` below
+   * feeds every `minWidth`), and `setDockPpf` does not flush a commit — so a
+   * `scrollLeft` written in the same handler is clamped by the browser against
+   * the width the lane still HAS, not the one it is about to have. Zooming
+   * into a late shot from a fitted document would clamp to ~0 and show the
+   * first shot at the last shot's zoom.
+   *
+   * `useAnchoredZoom` solved this for the wheel and its comment names the
+   * reason; this is the same pending-ref + layout-effect pair for the one
+   * scroll target the wheel never produces.
+   */
+  const pendingScroll = useRef<number | null>(null);
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (el === null || pendingScroll.current === null) return;
+    el.scrollLeft = pendingScroll.current;
+    pendingScroll.current = null;
+  }, [ppf]);
+
+  /**
+   * Fit the whole document across the lane, or ONE SHOT if given its id.
+   *
+   * Registered with the store rather than bound to a key here, because the
+   * keymap is the chrome's ONE key-binding site and only this component knows
+   * how wide its lane is — the same division of labour `fitView` uses against
+   * the stage.
+   */
+  const fit = useCallback(
+    (sceneId?: string) => {
+      const el = scrollRef.current;
+      const current = store.getState().doc;
+      if (el === null || current === null) return;
+      const width = el.clientWidth - LABEL_WIDTH;
+      if (width <= 0) return;
+
+      // Whole document: the target is 0, which is in range at every zoom, so
+      // it needs none of the deferral below.
+      if (sceneId === undefined) {
+        const total = masterDuration(current);
+        if (total <= 0) return;
+        store.setDockPpf(width / total);
+        el.scrollLeft = 0;
+        return;
+      }
+
+      const bar = sceneBars(current).find((b) => b.id === sceneId);
+      if (bar === undefined) return;
+      const span = bar.end - bar.start;
+      if (span <= 0) return;
+      const before = store.getState().dockPpf;
+      store.setDockPpf(width / span);
+      // READ THE CLAMP BACK: setDockPpf pins ppf to [0.2, 60], so a very short
+      // shot asks for more zoom than it gets and the scroll must be computed
+      // against what actually landed.
+      const actual = store.getState().dockPpf;
+      const target = frameToPx(bar.start, actual);
+      // An unchanged ppf renders nothing, so the layout effect above would
+      // never fire and the scroll would strand. Layout is already correct
+      // there, so write it now.
+      if (actual === before) el.scrollLeft = target;
+      else pendingScroll.current = target;
+    },
+    [store],
+  );
+  useEffect(() => {
+    store.attachDockFit(fit);
+    return () => store.attachDockFit(null);
+  }, [store, fit]);
+
+  /**
+   * Freeze the snap targets at the press and hand a row back the one function a
+   * drag needs.
+   *
+   * Frozen, for the reason every other value in this lane is read at press: the
+   * document changes under a live drag, and a list re-derived per move would
+   * start including the thing being dragged.
+   */
+  const beginSnap = useCallback<SnapPress>(
+    (exclude: SnapScope["exclude"], suppressed: boolean) => {
+      const s = store.getState();
+      const targets =
+        suppressed || s.doc === null
+          ? []
+          : collectSnapTargets(s.doc, exclude === undefined ? { playhead: s.frame } : { playhead: s.frame, exclude });
+      const threshold = snapThresholdFrames(s.dockPpf);
+      return (candidate: number): number => {
+        const hit = snapFrame(candidate, targets, threshold);
+        setGuide(hit.target === null ? null : hit.frame);
+        return hit.frame;
+      };
+    },
+    [store],
+  );
+  // The guide is cleared by the END of a drag, and a drag has three ends:
+  // release, cancel, and the Escape that `startDrag` turns into a discard. Held
+  // here rather than threaded back through every row, because "is a drag
+  // running" is a property of the dock and not of any one bar.
+  useEffect(() => {
+    const clear = (): void => setGuide(null);
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === "Escape") clear();
+    };
+    window.addEventListener("pointerup", clear);
+    window.addEventListener("pointercancel", clear);
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("pointerup", clear);
+      window.removeEventListener("pointercancel", clear);
+      window.removeEventListener("keydown", onKey);
+    };
+  }, []);
+
+  // Memoised on the document identity: the rows change exactly when the doc
+  // does, and this component still re-renders for ppf/guide/collapse changes
+  // that should not pay a full row rebuild. Above the null return — hooks.
+  // Keyed on the ISOLATION too: going inside a card narrows the outline and the
+  // stage, and a dock still listing every layer in the scene is the one panel
+  // an author uses to find a block showing rows they cannot click.
+  const groups = useMemo(() => (doc === null ? [] : masterRows(doc, isolation)), [doc, isolation]);
+  const contentF = useMemo(
+    // The RULER ends at the document; the CONTENT may run past it, because a
+    // bar dragged off the end has to stay reachable.
+    () => (doc === null ? 0 : masterContentFrames(doc, groups)),
+    [doc, groups],
+  );
+
+  if (doc === null) return null;
+  const total = masterDuration(doc);
+  const timeW = frameToPx(contentF, ppf);
+
+  return (
+    <section
+      className={`timeline-dock${collapsed ? " is-collapsed" : ""}`}
+      data-testid="timeline-dock"
+      aria-label="Timeline"
+    >
+      {/* A child, not a sibling: the dock's height is content-driven up to its
+          max, so only the dock itself knows where its top edge actually is.
+          Absolute inside a `position: fixed` box, above the head it overlays. */}
+      {collapsed ? null : (
+        <ResizeHandle
+          axis="y"
+          getValue={() => store.getState().dockHeight}
+          // Dragging the TOP edge upward is a DECREASING clientY and a TALLER
+          // dock, so the pointer's travel is negated.
+          sign={-1}
+          onChange={(h) => store.setDockHeight(h)}
+          onReset={() => store.setDockHeight(DOCK_HEIGHT.default)}
+          className="dock-resize"
+          label="Resize the timeline"
+        />
+      )}
+      <header className="dock-head">
+        <button
+          type="button"
+          className="dock-collapse"
+          aria-expanded={!collapsed}
+          aria-label={collapsed ? "Expand timeline" : "Collapse timeline"}
+          onClick={() => store.setDockCollapsed(!collapsed)}
+        >
+          {collapsed ? "▴" : "▾"}
+        </button>
+        {/* The transport, on the strip it drives. The header has one too and
+            both call the same action — there is one `playing` bit, so they
+            cannot disagree, and a timeline you have to look away from to start
+            is a timeline you scrub with the keyboard instead. */}
+        <button
+          type="button"
+          className="dock-play"
+          aria-label={playing ? "Pause" : "Play"}
+          title={playing ? "Pause (Space)" : "Play (Space)"}
+          onClick={() => store.setPlaying(!playing)}
+        >
+          {playing ? "❚❚" : "▶"}
+        </button>
+        <DockTime fps={doc.fps} />
+        <span className="dock-span" data-testid="dock-span">
+          Start {timecode(0, doc.fps)} / End {timecode(total, doc.fps)}
+        </span>
+        {/* Wrapped, not passed by reference: `fit` now takes an optional
+            sceneId, and a bare handler would hand it the MouseEvent. */}
+        <button type="button" className="dock-fit" title="Fit the timeline (\)" onClick={() => fit()}>
+          Fit
+        </button>
+        {/* MONITORING, not the mix. Neither control touches the document, so
+            neither can change what an export sounds like — see
+            ShotEditorState.previewMuted. */}
+        <button
+          type="button"
+          className="dock-mute"
+          aria-label={previewMuted ? "Unmute preview" : "Mute preview"}
+          aria-pressed={previewMuted}
+          title={previewMuted ? "Preview muted" : "Mute the preview"}
+          onClick={() => store.setPreviewMuted(!previewMuted)}
+        >
+          {previewMuted ? "🔇" : "🔊"}
+        </button>
+        <input
+          className="dock-volume"
+          type="range"
+          min={0}
+          max={1}
+          step={0.01}
+          value={previewVolume}
+          aria-label="Preview volume"
+          onChange={(e) => store.setPreviewVolume(Number(e.currentTarget.value))}
+        />
+        <DockReadout total={total} />
+      </header>
+
+      {/* The body is HIDDEN, not unmounted, when collapsed. Unmounting would
+          throw away the scroll position and every row's state, and the author
+          would come back to a dock that had forgotten where they were —
+          dockCollapse.test.tsx is the gate. */}
+      <div className="dock-body" hidden={collapsed} data-testid="dock-body">
+        <div className="dock-scroll" ref={scrollRef} data-testid="dock-scroll">
+          {/* INSIDE the scroller, with the same content width as the tracks.
+              It used to sit outside, and that was correct while it was a macro
+              lane over a scene-local micro one — the two never shared an x. They
+              share one now, so a strip that did not scroll with the tracks would
+              draw every scene bar somewhere its own boundary line is not. */}
+          <div style={{ minWidth: LABEL_WIDTH + timeW }}>
+            <SceneStrip ppf={ppf} labelWidth={LABEL_WIDTH} />
+          </div>
+          <div className="dock-ruler" style={{ marginLeft: LABEL_WIDTH, minWidth: timeW }}>
+            {/* MASTER frames end to end. The seek is the identity now — the two
+                clocks used to meet here, and that conversion was the one place a
+                sign error put the playhead in another scene. */}
+            <Ruler
+              durationFrames={total}
+              contentF={contentF}
+              ppf={ppf}
+              timeW={timeW}
+              formatTick={(f) => timecode(f, doc.fps)}
+              onSeek={(f) => store.seek(f)}
+            >
+              <DockPlayhead ppf={ppf} />
+            </Ruler>
+          </div>
+
+          <div className="dock-tracks" data-testid="dock-tracks" style={{ minWidth: LABEL_WIDTH + timeW }}>
+            {/* The scene boundaries, drawn THROUGH the tracks. Derived from the
+                same prefix sum the strip above uses, so the line and the bar it
+                divides can never be a frame apart. */}
+            <div className="dock-overlay" style={{ left: LABEL_WIDTH }} aria-hidden="true">
+              {groups.map((group) =>
+                group.start === 0 ? null : (
+                  <span
+                    key={group.id}
+                    className="dock-boundary"
+                    data-boundary={group.id}
+                    style={{ left: frameToPx(group.start, ppf) }}
+                  />
+                ),
+              )}
+              {guide === null ? null : (
+                <span className="dock-snap-guide" data-testid="snap-guide" style={{ left: frameToPx(guide, ppf) }} />
+              )}
+              <DockPlayhead ppf={ppf} />
+            </div>
+
+            {groups.map((group) => (
+              <div className="dock-scene-group" key={group.id} data-scene-group={group.id}>
+                {/* The camera is a ROW like any other, one per scene at its own
+                    master position, so a camera move trims and retimes with the
+                    same gestures a block does. */}
+                <BlockRow
+                  label="Camera"
+                  sceneId={group.id}
+                  layerId={CAMERA_ROW_ID}
+                  depth={0}
+                  bars={group.camera}
+                  ppf={ppf}
+                  labelWidth={LABEL_WIDTH}
+                  offsetFrames={group.start}
+                  beginSnap={beginSnap}
+                  // The same action ⇧C runs. A camera move has no preset to
+                  // pick, so unlike a layer's blocks it can be created from the
+                  // row; the scene is passed so a row that is not under the
+                  // playhead is refused by name rather than writing somewhere else.
+                  onAdd={() => store.addShotAtPlayhead(group.id)}
+                  addLabel="+ move"
+                />
+                {group.rows.map((row) => (
+                  <Fragment key={row.layerId}>
+                    <LifespanRow
+                      row={row}
+                      sceneId={group.id}
+                      sceneStart={group.start}
+                      ppf={ppf}
+                      labelWidth={LABEL_WIDTH}
+                      expanded={open.has(row.layerId)}
+                      onToggle={() =>
+                        setOpen((was) => {
+                          const next = new Set(was);
+                          if (!next.delete(row.layerId)) next.add(row.layerId);
+                          return next;
+                        })
+                      }
+                      beginSnap={beginSnap}
+                    />
+                    {/* The Figma/Lottie read: one derived row per channel the
+                        blocks write, diamonds at each block's ends. The
+                        preset-named block lane is gone from the expansion —
+                        the preset lives in the span tooltip and the Animate
+                        tab. See ChannelRow.tsx. */}
+                    {open.has(row.layerId) &&
+                      (() => {
+                        const layer = doc.scenesById[group.id]?.layersById[row.layerId];
+                        return layer === undefined ? null : (
+                          <ChannelRows
+                            layer={layer}
+                            sceneId={group.id}
+                            depth={row.depth + 1}
+                            ppf={ppf}
+                            labelWidth={LABEL_WIDTH}
+                            offsetFrames={group.start}
+                            fps={doc.fps}
+                            lifespan={row.lifespan}
+                            beginSnap={beginSnap}
+                          />
+                        );
+                      })()}
+                  </Fragment>
+                ))}
+              </div>
+            ))}
+
+            {/* UNDER the video and OVER the audio, which is where every NLE
+                puts the two. Both are outside the scene groups, and
+                deliberately: `doc.audio` and `doc.markers` are MASTER-timed and
+                belong to no scene, so a lane nested in one would be drawing a
+                lie. The marks sit directly over the waveform because they are
+                almost always beats in it. */}
+            <MarkerLane ppf={ppf} labelWidth={LABEL_WIDTH} beginSnap={beginSnap} />
+            <AudioLane ppf={ppf} labelWidth={LABEL_WIDTH} beginSnap={beginSnap} />
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}