@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/keyframeMenu.ts

@@ -0,0 +1,138 @@
+// THE KEYFRAME CONTEXT MENU, once.
+//
+// A right-click on a keyframe means the same thing in both faces of the dock —
+// the rows' diamonds and the graph's circles — and the rules it has to obey are
+// not obvious ones: a spring on a non-springable kind THROWS inside the sampler,
+// a discrete track holds structurally so every tween is a no-op wearing a label,
+// and the last key's ease governs no segment at all. Three rules, two call
+// sites; written once so the two cannot answer differently.
+import { EASE_PRESETS, groupEasePresets, matchPreset } from "@dailies-studio/timeline";
+import type { EasePreset } from "@dailies-studio/timeline";
+import { DISCRETE_KINDS, SPRINGABLE_KINDS } from "@dailies-studio/engine";
+import type { Ease, TrackKind } from "@dailies-studio/engine";
+import type { MenuEntry } from "@dailies-studio/ui";
+import type { KeyframeSel } from "../../state/types.js";
+import type { ShotEditorStore } from "../../state/store.js";
+import { gateForViewer } from "../../state/menu.js";
+
+/** The one key the pointer is on, as the menu needs to describe it. */
+export interface MenuKey {
+  kind: TrackKind;
+  ease: Ease;
+  /** Is this the LAST key on its track? Then its ease is never sampled. */
+  last: boolean;
+  /** Does the track curve its path (`spatialInterp`)? Then no spring: the
+   *  engine refuses a spring on a curved track. */
+  curved?: boolean;
+}
+
+/**
+ * Which keys a menu opened on `at` is about.
+ *
+ * IN THE SELECTION = the whole set. Right-clicking one of four selected keys to
+ * ease all four is the gesture every timeline has, and collapsing to one here
+ * would silently drop three. Outside it, the menu points at what the pointer
+ * points at — and the caller focuses that key, so a following Backspace
+ * addresses the same thing the menu did.
+ */
+export function keyframeMenuTargets(
+  selection: readonly KeyframeSel[],
+  at: KeyframeSel,
+): readonly KeyframeSel[] {
+  const inSet = selection.some(
+    (k) =>
+      k.containerId === at.containerId &&
+      k.layerId === at.layerId &&
+      k.path === at.path &&
+      k.frame === at.frame,
+  );
+  return inSet ? selection : [at];
+}
+
+export function keyframeMenuEntries(args: {
+  store: ShotEditorStore;
+  key: MenuKey;
+  targets: readonly KeyframeSel[];
+  /** The track the menu opened on — "select all in this track" acts on it. */
+  at: KeyframeSel;
+}): MenuEntry[] {
+  const { store, key, targets, at } = args;
+  const many = targets.length > 1;
+  const current = matchPreset(key.ease);
+  // ONLY WHAT THE ENGINE WILL SAMPLE, on `KeyframeEditor`'s rule (its own
+  // header states it): a spring on a non-springable kind THROWS inside
+  // `evaluateTrack`, so offering it here promises a document that refuses to
+  // play. Dropped rather than disabled, because `easeTrackError` means no valid
+  // track can already read as "spring" on such a kind — so removing the option
+  // can never leave the menu unable to show the current ease.
+  const springable = SPRINGABLE_KINDS.has(key.kind) && key.curved !== true;
+  // A discrete track holds STRUCTURALLY (`evaluateTrack` returns early on
+  // `DISCRETE_KINDS`), so every tween here is a no-op wearing a label. One
+  // disabled line says so instead of four buttons that do nothing.
+  const discrete = DISCRETE_KINDS.has(key.kind);
+  // THE LAST KEY'S EASE GOVERNS NO SEGMENT. Writing it is legal and utterly
+  // invisible, which is the silent inertness this lane refuses everywhere else —
+  // so the entries stay visible (the author can see which ease the key carries)
+  // and refuse with their reason on hover.
+  //
+  // SINGLE-KEY ONLY, and that is the whole of the rule: `key.last` describes the
+  // key the pointer landed on, and it cannot describe a SET. Over a selection it
+  // greyed out every preset because the author right-clicked the last member —
+  // which is the natural one to click after a left-to-right marquee, so easing a
+  // whole run was impossible from the obvious gesture.
+  const easeReason =
+    key.last && !many
+      ? "the last keyframe has no segment leaving it, so its ease is never sampled"
+      : null;
+  const presets = EASE_PRESETS.filter(
+    (p) => (springable || p.ease.type !== "spring") && (!discrete || p.ease.type === "hold"),
+  );
+  const action = (preset: EasePreset): MenuEntry => ({
+    kind: "action" as const,
+    id: `ease-${preset.id}`,
+    label: preset.label,
+    // WHICH ONE IS ON, in the shortcut column rather than as a check mark:
+    // `MenuEntry` has no checked state, and adding one to the shared menu for
+    // a single call site would be a widget feature paid for by one caller. The
+    // column is right-aligned dim text, which is exactly the register this
+    // belongs in. The "current" marker only means something for ONE key — over
+    // a set it would name whichever the pointer happened to be on.
+    ...(!many && current === preset.id ? { shortcut: "current" } : {}),
+    ...(easeReason === null ? {} : { disabled: true, title: easeReason }),
+    onSelect: () => store.setKeyframesEase(targets, preset.ease),
+  });
+  return gateForViewer(store.getState(), [
+    ...(discrete
+      ? [
+          {
+            kind: "action" as const,
+            id: "ease-discrete",
+            label: `a ${key.kind} track always holds`,
+            disabled: true,
+            onSelect: () => {},
+          },
+        ]
+      : []),
+    // The basic group stays flat where it always was; the named families fold
+    // into submenus, because ~25 top-level rows is not a menu anyone can scan.
+    ...groupEasePresets(presets).flatMap((g): MenuEntry[] =>
+      g.group === "basic"
+        ? g.presets.map(action)
+        : [{ kind: "submenu" as const, label: g.label, items: g.presets.map(action) }],
+    ),
+    { kind: "separator" as const },
+    {
+      kind: "action" as const,
+      id: "key-select-track",
+      label: "Select all keyframes in this track",
+      onSelect: () => store.selectTrackKeyframes(at.containerId, at.layerId, at.path),
+    },
+    {
+      kind: "action" as const,
+      id: "key-delete",
+      label: many ? `Delete ${targets.length} keyframes` : "Delete keyframe",
+      danger: true,
+      onSelect: () => store.deleteKeyframes(targets),
+    },
+  ]);
+}

package/src/panels/timeline/labelWidth.ts

@@ -0,0 +1,49 @@
+// THE TIMELINE'S NAME COLUMN IS THE LEFT COLUMN'S TRACK.
+//
+// The dock spans the shell's three column tracks, so its label column sits
+// under the left column and has to be exactly as wide as the rail the grid
+// DRAWS: the fitted width, not the stored one (a small window shrinks the rail
+// first). `fitShell` is the same call App.tsx makes for `--rail-w`, so the two
+// cannot disagree. A collapsed rail keeps its track, so collapse and Video
+// never move a bar.
+import { useCallback, useSyncExternalStore } from "react";
+import { useStore } from "../../state/context.js";
+import { fitShell } from "../../state/panelSize.js";
+import type { ShellFit } from "../../state/panelSize.js";
+
+type StoredSizes = Parameters<typeof fitShell>[2];
+
+/** The label column's width for this window and these stored sizes. Read it
+ *  from effects and handlers, which must never close over a stale width. */
+export function labelWidthOf(stored: StoredSizes): number {
+  return fitShell(window.innerWidth, window.innerHeight, stored).railWidth;
+}
+
+/**
+ * One value of the shell's fitted tracks, for rendering.
+ *
+ * On the COLD channel plus the window's resize: the stored sizes are cold
+ * fields, so a playback tick never re-evaluates this, and the snapshot is a
+ * primitive, so a notification that leaves it unchanged renders nothing.
+ */
+export function useShellFit<T extends number | boolean>(pick: (fit: ShellFit) => T): T {
+  const store = useStore();
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      const stop = store.subscribeCold(onChange);
+      window.addEventListener("resize", onChange);
+      return () => {
+        stop();
+        window.removeEventListener("resize", onChange);
+      };
+    },
+    [store],
+  );
+  const read = (): T => pick(fitShell(window.innerWidth, window.innerHeight, store.getState()));
+  return useSyncExternalStore(subscribe, read, read);
+}
+
+/** The label column's width, for rendering. */
+export function useLabelWidth(): number {
+  return useShellFit((fit) => fit.railWidth);
+}

package/src/panels/timeline/marquee.ts

@@ -0,0 +1,155 @@
+// THE DOCK'S RUBBER BAND: which bars a dragged rectangle takes.
+//
+// ── WHY THE LOGIC IS HERE AND NOT IN THE COMPONENT ──────────────────────
+//
+// The same argument model.ts makes for every other piece of this lane's
+// geometry: "does a bar that merely touches the edge of the box count" is a
+// question about two rectangles, and a question about two rectangles should be
+// answerable without mounting a timeline. `TimelineDock` measures, this decides,
+// and the test fixture below the fold in timelineMarquee.test.ts is four boxes
+// and no DOM.
+//
+// ── ONE COORDINATE SPACE, AND IT IS `.dock-tracks` ──────────────────────
+//
+// Every number in this file is in the track area's OWN content pixels: a client
+// x less `.dock-tracks`'s left edge. Not client coordinates, and deliberately:
+// the first write of a marquee's selection can move the playhead into another
+// shot (`focusScene`), and the lane's follow effect then scrolls horizontally
+// under a pointer that has not moved. In content space the box stays pinned to
+// the frames it was drawn over while the lane slides beneath it, which is what
+// an author who drew a box around two bars means. It is also what the painted
+// rect wants, since `.dock-marquee` is absolutely positioned inside the same
+// element.
+//
+// ── AND MEMBERSHIP IS DECIDED PER BAR, EVERY MOVE ───────────────────────
+//
+// Nothing here accumulates. `marqueeHits` is asked again on every move with the
+// live box, so a bar the band reached and then retreated past is simply not in
+// the answer any more. A banked set would make the gesture one-way: overshoot
+// by one row and the only recovery is to release and start again.
+
+/** A point in `.dock-tracks` content pixels. */
+export interface MarqueePoint {
+  x: number;
+  y: number;
+}
+
+/** A box in `.dock-tracks` content pixels, edges normalised so `left <= right`
+ *  and `top <= bottom`. */
+export interface MarqueeRect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/** One lifespan bar's box, with the two ids the selection needs. */
+export interface MarqueeBar extends MarqueeRect {
+  layerId: string;
+  /** The container the row's layer lives in: a scene, or the open definition. */
+  sceneId: string;
+}
+
+/** What a gesture is selecting INTO, and inside which group.
+ *
+ *  `add` is the selection frozen at the press, empty unless shift was held. It
+ *  goes in front of the hits so a shift-marquee reads as an extension of what
+ *  was already there rather than a reordering of it. */
+export interface MarqueeScope {
+  sceneId: string;
+  add: readonly string[];
+}
+
+/** The box between the press and the pointer, whichever way the drag ran. */
+export function rectBetween(from: MarqueePoint, to: MarqueePoint): MarqueeRect {
+  return {
+    left: Math.min(from.x, to.x),
+    top: Math.min(from.y, to.y),
+    right: Math.max(from.x, to.x),
+    bottom: Math.max(from.y, to.y),
+  };
+}
+
+/**
+ * The layer ids a box selects: every bar it touches, plus whatever it is adding
+ * to.
+ *
+ * ── TOUCHING COUNTS ─────────────────────────────────────────────────────
+ *
+ * The test is separation, not enclosure, and it is not strict: a band dragged
+ * up to a bar's edge has REACHED that bar, and no author can see the sub-pixel
+ * difference that a strict test would decide on. Enclosure is the other
+ * candidate and it is wrong for this lane: a bar can be wider than the dock, so
+ * "the box must contain it" would make the longest clips unselectable.
+ *
+ * ── AND THE SCOPE IS ONE SCENE GROUP ────────────────────────────────────
+ *
+ * Not a preference. `select` in store.ts orders the ids it is given against ONE
+ * container (the one `layerContainer()` names, then the playhead's scene) and
+ * DROPS everything that resolves in neither, so a list spanning two shots
+ * silently becomes a list of one shot's worth anyway. Better to decide that
+ * here, where the rule can be read, than to hand over a cross-shot list and
+ * discover which half survived. The group is the one the press began in, which
+ * is also the shot the caller pins with `focusScene` before it writes.
+ *
+ * Ids in `add` from another group are passed through untouched: they are the
+ * author's existing selection, not this box's business, and `select` is the one
+ * place that resolves a home.
+ */
+export function marqueeHits(
+  rect: MarqueeRect,
+  bars: readonly MarqueeBar[],
+  scope: MarqueeScope,
+): string[] {
+  const out = [...scope.add];
+  const seen = new Set(out);
+  for (const bar of bars) {
+    if (bar.sceneId !== scope.sceneId) continue;
+    if (bar.right < rect.left || bar.left > rect.right) continue;
+    if (bar.bottom < rect.top || bar.top > rect.bottom) continue;
+    if (seen.has(bar.layerId)) continue;
+    seen.add(bar.layerId);
+    out.push(bar.layerId);
+  }
+  return out;
+}
+
+/**
+ * Every mounted lifespan bar's box, read off the DOM once at the press.
+ *
+ * THE DOM AND NOT THE MODEL, because the y here is flow layout: rows are 28 or
+ * 56 tall, a shot's disclosure adds a block of them, and past the window
+ * threshold spacers stand in for the rows that are not mounted. `TimelineDock`
+ * has prefix sums over exactly that (`groupHeights`), and rebuilding a second
+ * copy of them for this would be a second spelling of the layout that can drift
+ * from the first. The element positions cannot drift from themselves.
+ *
+ * ONCE, at the press: nothing in a marquee moves a row. The dock holds its
+ * collapse until the pointer is up (see `onPointerDownCapture` in
+ * TimelineDock), selection paints an outline rather than reflowing, and the
+ * boxes are content-relative so a follow scroll does not move them.
+ *
+ * ponytail: a row the virtual window has not mounted has no box and cannot be
+ * hit. There is no auto-scroll, so a box can only be drawn over rows that are
+ * on screen anyway; add the query per move if auto-scroll ever lands.
+ */
+export function marqueeBars(tracks: HTMLElement): MarqueeBar[] {
+  const origin = tracks.getBoundingClientRect();
+  const out: MarqueeBar[] = [];
+  for (const row of tracks.querySelectorAll<HTMLElement>("[data-lifespan]")) {
+    const layerId = row.dataset["lifespan"];
+    const sceneId = row.dataset["rowScene"];
+    const bar = row.querySelector<HTMLElement>("[data-bar]");
+    if (layerId === undefined || sceneId === undefined || bar === null) continue;
+    const box = bar.getBoundingClientRect();
+    out.push({
+      layerId,
+      sceneId,
+      left: box.left - origin.left,
+      top: box.top - origin.top,
+      right: box.right - origin.left,
+      bottom: box.bottom - origin.top,
+    });
+  }
+  return out;
+}