@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/MarkerLane.tsx

@@ -30,13 +30,43 @@ import type { PointerEvent as ReactPointerEvent } from "react";
 import { frameToPx, startDrag } from "@dailies-studio/timeline";
 import type { Rational } from "@dailies-studio/engine";
 import type { MarkerRef } from "@dailies-studio/shot/doc";
-import { useShotEditor, useStore } from "../../state/context.js";
+import { useShotEditor, useShotEditorHot, useStore } from "../../state/context.js";
 import { frameDelta, timecode } from "./model.js";
 import { isSnapSuppressed } from "./snap.js";
 import type { SnapPress } from "./snap.js";
+import { formatCombo } from "../../state/shortcuts.js";
 
-export function MarkerLane(props: { ppf: number; labelWidth: number; beginSnap?: SnapPress }) {
-  const { ppf, labelWidth, beginSnap } = props;
+export function MarkerLane(props: {
+  ppf: number;
+  labelWidth: number;
+  beginSnap?: SnapPress;
+  /**
+   * The SHOT CONTEXT's window, or absent in the scene context.
+   *
+   * A marker's frame is a MASTER frame and stays one; this only RE-ZEROES the
+   * lane on the shot, exactly as every other row in the dock is re-zeroed.
+   *
+   * ── EVERY MARKER IS STILL RENDERED, AND CLIPPED BY THE TRACK BOX ────────
+   *
+   * Narrowing the list to the window was the obvious thing and it is wrong,
+   * because the pin is the thing being DRAGGED: `dragMarker` writes an
+   * unclamped master frame, so pulling a mark one frame past the shot's edge
+   * unmounted its own pin mid-gesture — the pointer capture died with the node,
+   * the drag was silently discarded, and the beat was left wherever the last
+   * committed move had put it. The same filter also made the snap guide point
+   * at a mark the lane refused to draw. Drawing them all and letting
+   * `.marker-track`'s clip hide what is outside costs a handful of spans and
+   * has neither failure.
+   *
+   * DRAWN AT ALL, unlike the component context which prunes both master lanes:
+   * a definition runs on a second clock with no master position, so its ruler
+   * cannot place a master frame. A shot IS a window of master time, and
+   * beat-synced authoring inside one is the whole point of the tool.
+   */
+  shotWindow?: { origin: number; len: number } | undefined;
+}) {
+  const { ppf, labelWidth, beginSnap, shotWindow } = props;
+  const origin = shotWindow?.origin ?? 0;
   const store = useStore();
   const doc = useShotEditor((s) => s.doc);
   const selected = useShotEditor((s) => s.selectedMarker);
@@ -67,6 +97,7 @@ export function MarkerLane(props: { ppf: number; labelWidth: number; beginSnap?:
               marker={marker}
               selected={marker.id === selected}
               ppf={ppf}
+              origin={origin}
               fps={doc.fps}
               beginSnap={beginSnap}
             />
@@ -81,16 +112,23 @@ function MarkerPin(props: {
   marker: MarkerRef;
   selected: boolean;
   ppf: number;
+  /** The shot context's re-zero. DRAWING ONLY: the drag below is a signed
+   *  delta on a master frame, which no offset touches. */
+  origin: number;
   fps: Rational;
   beginSnap: SnapPress | undefined;
 }) {
-  const { marker, selected, ppf, fps, beginSnap } = props;
+  const { marker, selected, ppf, origin, fps, beginSnap } = props;
+  /** What the ruler above this lane is reading. Master time outside a shot,
+   *  and the shot's own zero inside one — a tooltip that said 0:42 under a
+   *  ruler reading 0:02 is two clocks in one panel. */
+  const shown = marker.frame - origin;
   const store = useStore();
   // Subscribed to the BOOLEAN, not the frame: useSyncExternalStore only
   // notifies when the selected value changes, so a pin re-renders exactly
   // twice per playhead pass-through instead of once per playback frame — and
   // the lane above it never re-renders at all.
-  const atPlayhead = useShotEditor((s) => s.frame === marker.frame);
+  const atPlayhead = useShotEditorHot((s) => s.frame === marker.frame);
 
   const drag = (e: ReactPointerEvent<HTMLElement>): void => {
     e.preventDefault();
@@ -120,12 +158,12 @@ function MarkerPin(props: {
     <span
       className={`marker-pin${selected ? " is-selected" : ""}${atPlayhead ? " is-at-playhead" : ""}`}
       data-marker={marker.id}
-      style={{ left: frameToPx(marker.frame, ppf) }}
+      style={{ left: frameToPx(shown, ppf) }}
       role="button"
       tabIndex={-1}
-      aria-label={`${label} at ${timecode(marker.frame, fps)}`}
+      aria-label={`${label} at ${timecode(shown, fps)}`}
       aria-pressed={selected}
-      title={`${label} · ${timecode(marker.frame, fps)} · drag to move it, ⌘drag to ignore snapping`}
+      title={formatCombo(`${label} · ${timecode(shown, fps)} · drag to move it, ⌘drag to ignore snapping`)}
       onPointerDown={drag}
     >
       {/* The diamond is a rotated square rather than an SVG: it is 8px of

package/src/panels/timeline/PlayButton.tsx

@@ -0,0 +1,91 @@
+// THE PLAY CONTROL, one for the dock (`dock-play`) and Code Studio's preview
+// strip (`components-play`), so the two cannot disagree about what Play is
+// doing. Each caller passes its own class; the sheets place the look.
+//
+//   idle      the Play glyph, "Play (Space)".
+//   pending   a queued Play (`playIntent`): the cancel glyph, `aria-busy`,
+//             and after 300ms a ring around the glyph. The ring turns while
+//             the scene loads or the stage hands over, and counts the
+//             percent while a Play pass draws. The title says which.
+//   playing   the Pause glyph, "Pause (Space)".
+//   refused   a start `playHold` refuses (the board, an export lock): the
+//             Play glyph, disabled, with the refusal itself as its title, so
+//             it names which hold this is. `setPlaying` refuses on the same
+//             `playHold`, so the greyed control is the guard agreeing with
+//             itself, not a second rule.
+//
+// A press is `setPlaying(!playOn(state))`, as Space is, so a second press
+// cancels a queued Play. Only a start is ever refused: a running transport
+// and a queued Play can always be called off, whatever opens meanwhile.
+//
+// A leaf with its own subscriptions, so a play edge, and each percent of a
+// Play pass, re-renders this button and not the dock around it.
+import { IconClose, IconPause, IconPlay } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { SCENE_WAITING, playHold, playOn, preparingPercent, preparingTitle } from "../../state/playHold.js";
+
+/** Every Play control, whoever places it: input aimed at one does not end a
+ *  background preparing pass, which its click upgrades (`StagePanel`). */
+export const PLAY_CONTROL = "[data-play-control]";
+
+export function PlayButton(props: { className: string; testId?: string }) {
+  const store = useStore();
+  const playing = useShotEditor((s) => s.playing);
+  const intent = useShotEditor((s) => s.playIntent);
+  // The refusal and its wording. A string selector is compared by value, so
+  // this is as cold a subscription as a boolean.
+  const refusal = useShotEditor(playHold);
+  const pending = !playing && intent !== null;
+  const title = playing
+    ? "Pause (Space)"
+    : intent === null
+      ? (refusal ?? "Play (Space)")
+      : intent.phase === "preparing"
+        ? preparingTitle(intent)
+        : SCENE_WAITING;
+  return (
+    <button
+      type="button"
+      className={props.className}
+      data-testid={props.testId}
+      data-play-control=""
+      data-state={playing ? "playing" : pending ? "pending" : "idle"}
+      aria-label={playing ? "Pause" : pending ? "Cancel play" : "Play"}
+      aria-busy={pending ? true : undefined}
+      disabled={!playing && !pending && refusal !== null}
+      title={title}
+      // Read at the press, not from this render: the store may have moved on.
+      onClick={() => store.setPlaying(!playOn(store.getState()))}
+    >
+      {playing ? <IconPause /> : pending ? <IconClose /> : <IconPlay />}
+      {pending ? <PlayRing percent={intent.phase === "preparing" ? preparingPercent(intent) : null} /> : null}
+    </button>
+  );
+}
+
+/** The queued Play's ring: the font field's write-in-flight ring
+ *  (`.font-field-ring`, inspector-object.css), so the product has one ring. A
+ *  level while a Play pass counts; with nothing to count, a short arc that
+ *  turns, or a still dashed ring under reduced motion. Each context's sheet
+ *  lays it over the control and holds it back 300ms, so a start that is
+ *  ready at once never flashes it. Drawn on a 36 grid: the dock's ring is
+ *  36px, so the ring's 1.5 stroke draws 1.5px there. */
+function PlayRing(props: { percent: number | null }) {
+  const { percent } = props;
+  return (
+    <span className="play-ring" aria-hidden="true">
+      <svg className={`font-field-ring${percent === null ? " is-indeterminate" : ""}`} viewBox="0 0 36 36">
+        <circle className="font-field-ring-track" cx="18" cy="18" r="17" />
+        <circle
+          className="font-field-ring-level"
+          cx="18"
+          cy="18"
+          r="17"
+          pathLength={100}
+          {...(percent === null ? {} : { strokeDasharray: `${percent} 100` })}
+          transform="rotate(-90 18 18)"
+        />
+      </svg>
+    </span>
+  );
+}

package/src/panels/timeline/PropertyPicker.tsx

@@ -0,0 +1,254 @@
+// "+ property": THE SECOND DOOR INTO KEYFRAMING.
+//
+// ── WHY IT EXISTS AT ALL ────────────────────────────────────────────────────
+//
+// A channel row appears once a property carries animation and not before, which
+// is Lottie's rule (animated properties, not every property) and is right: a
+// layer has thirty trackable paths and nobody wants thirty rows. But it left
+// the inspector as the ONLY way to start one — an author who wanted to animate
+// the stroke width had to know which section holds it and find the diamond in
+// it. The timeline is where you go to animate something, so the timeline is
+// where "animate something else" belongs too.
+//
+// ── THE LIST IS THE TABLE, AND SO ARE THE REFUSALS ──────────────────────────
+//
+// Every entry comes from `TRACKABLE_PATHS` / `SCENE_TRACKABLE_PATHS` — the same
+// single source validate, the agent ops and the inspector diamond read — so a
+// path this offers is a path the gate accepts, by construction rather than by
+// two lists agreeing.
+//
+// A path this layer cannot carry is shown GREYED WITH ITS REASON rather than
+// hidden. `layerTrackRefusal` already returns the sentence ("needs a stroke",
+// "needs a solid fill"), and "why can I not animate the stroke width" is a
+// question the author is entitled to have answered where they asked it. That is
+// the one place this deliberately differs from `KeyframeDot`, which is ABSENT on
+// a refused path: a diamond sits in a row the author is already looking at, and
+// this is a list they opened to go looking.
+import { Popover } from "@dailies-studio/ui";
+import {
+  INSTANCE_PROP_PREFIX,
+  SCENE_TRACKABLE_PATHS,
+  TRACKABLE_PATHS,
+  contractTrackablePath,
+  layerSnapshotContract,
+  layerTrackRefusal,
+  pathAllowsKind,
+  sceneTrackRefusal,
+} from "@dailies-studio/shot/doc";
+import type { Layer3D, Scene3D } from "@dailies-studio/shot/doc";
+import { controlLabel } from "@dailies-studio/contract";
+import type { Contract } from "@dailies-studio/contract";
+import { useMemo, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import { useShotEditor, useStore } from "../../state/context.js";
+
+/** One offer. `refusal` non-null means the row is disabled and says why. */
+interface Offer {
+  path: string;
+  label: string;
+  group: string;
+  tracked: boolean;
+  refusal: string | null;
+}
+
+/** The first path segment, title-cased, is the section an author already knows
+ *  the property by: "transform.opacity" is under Transform, "paint.fill.color"
+ *  under Paint. Derived rather than tabled, because a second column naming the
+ *  group is a second thing to keep in step with the path. A one-segment path
+ *  is a field of the layer itself (`blurPx`, schema v47), which the inspector
+ *  edits in Appearance, so it groups there rather than under its own name. */
+export function groupOf(path: string): string {
+  if (!path.includes(".")) return "Appearance";
+  const head = path.split(".")[0] ?? "";
+  return head.charAt(0).toUpperCase() + head.slice(1);
+}
+
+/**
+ * The array-indexed paths (`paint.shadows.<i>.blurPx`) are offered ONCE PER
+ * SHADOW the layer actually has. The table key carries the placeholder, so a
+ * literal offer would be a path that resolves to nothing and a keyframe that
+ * writes nowhere.
+ */
+function expandIndexed(path: string, layer: Layer3D): string[] {
+  if (!path.includes(".<i>.")) return [path];
+  const shadows = "paint" in layer ? (layer.paint?.shadows ?? []) : [];
+  return shadows.map((_, i) => path.replace(".<i>.", `.${i}.`));
+}
+
+function layerOffers(layer: Layer3D, live: Contract | undefined): Offer[] {
+  const out: Offer[] = [];
+  for (const [key, spec] of Object.entries(TRACKABLE_PATHS)) {
+    // A path that is not a property of this KIND is not a refusal to explain,
+    // it is a property of something else. Those are the only ones left out.
+    if (!pathAllowsKind(spec, layer.kind)) continue;
+    for (const path of expandIndexed(key, layer)) {
+      out.push({
+        path,
+        label: spec.label,
+        group: groupOf(path),
+        tracked: layer.tracks?.[path] !== undefined,
+        refusal: layerTrackRefusal(layer, path),
+      });
+    }
+  }
+  out.push(...instanceOffers(layer, live));
+  return out;
+}
+
+/**
+ * An instance's props, from the CONTRACT rather than from the table — the one
+ * offer family whose list is a property of the component and not of this lane.
+ *
+ * Grouped under "Component" and not under `groupOf`'s "Instance": the inspector
+ * section that edits these props is titled Component, and two names for one
+ * group is what `groupOf`'s own comment is guarding against.
+ *
+ * A non-animatable spec (`slot`, `event`) is LEFT OUT rather than greyed. Every
+ * other refusal in this list is something the author can fix by adding a stroke
+ * or a shadow; "this prop is a slot" is a fact about the component's source, so
+ * a row explaining it would be a row that never becomes pressable.
+ */
+function instanceOffers(layer: Layer3D, live: Contract | undefined): Offer[] {
+  if (layer.kind !== "instance") return [];
+  const contract = live ?? layerSnapshotContract(layer);
+  if (contract === null || contract === undefined) return [];
+  const out: Offer[] = [];
+  for (const spec of Object.values(contract.keys)) {
+    if (contractTrackablePath(spec) === null) continue;
+    const path = `${INSTANCE_PROP_PREFIX}${spec.key}`;
+    out.push({
+      path,
+      label: controlLabel(spec),
+      group: "Component",
+      tracked: layer.tracks?.[path] !== undefined,
+      refusal: layerTrackRefusal(layer, path, live),
+    });
+  }
+  return out;
+}
+
+function sceneOffers(scene: Scene3D): Offer[] {
+  return Object.entries(SCENE_TRACKABLE_PATHS).map(([path, spec]) => ({
+    path,
+    label: spec.label,
+    group: groupOf(path),
+    tracked: scene.tracks?.[path] !== undefined,
+    refusal: sceneTrackRefusal(scene, path),
+  }));
+}
+
+/**
+ * The button and its list. `subject` decides which table is read and which verb
+ * the pick routes through; everything else is one component because every pixel
+ * of it is shared — the `KeyframeDot`/`SceneKeyframeDot` split's own reasoning.
+ */
+export function PropertyPicker({
+  subject,
+  containerId,
+  labelWidth,
+  depth,
+  status = null,
+}: {
+  subject: { kind: "layer"; layer: Layer3D } | { kind: "shot"; scene: Scene3D };
+  containerId: string;
+  labelWidth: number;
+  depth: number;
+  /** The selected-key readout drawn beside the button, from the rows above
+   *  (ChannelRow's `selectedKeyStatus`). Null draws nothing. */
+  status?: string | null;
+}) {
+  const store = useStore();
+  const anchor = useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = useState(false);
+  // The registry's contracts, for the instance-prop offers. `InstanceSection` is
+  // what loads one; until it has, the layer's snapshot answers.
+  const contracts = useShotEditor((s) => s.contracts);
+  const live =
+    subject.kind === "layer" && subject.layer.kind === "instance"
+      ? contracts[subject.layer.instance.component]
+      : undefined;
+
+  const offers = useMemo(
+    () => (subject.kind === "layer" ? layerOffers(subject.layer, live) : sceneOffers(subject.scene)),
+    [subject.kind, subject.kind === "layer" ? subject.layer : subject.scene, live],
+  );
+  const groups = useMemo(() => {
+    const byGroup = new Map<string, Offer[]>();
+    for (const offer of offers) {
+      const at = byGroup.get(offer.group);
+      if (at === undefined) byGroup.set(offer.group, [offer]);
+      else at.push(offer);
+    }
+    return [...byGroup.entries()];
+  }, [offers]);
+
+  const testId = subject.kind === "layer" ? subject.layer.id : containerId;
+
+  const pick = (offer: Offer): void => {
+    setOpen(false);
+    if (offer.refusal !== null) return;
+    // THE ROW'S SUBJECT, NOT THE SELECTION. Both verbs fan out over what is
+    // selected (a diamond in the inspector keys every selected layer), so the
+    // row makes its own layer the selection first — which is what clicking any
+    // row in this dock does anyway.
+    store.focusScene(containerId);
+    if (subject.kind === "layer") {
+      store.select([subject.layer.id]);
+      store.toggleKeyframe([offer.path]);
+    } else {
+      store.toggleSceneKeyframe([offer.path]);
+    }
+  };
+
+  return (
+    <div className="channel-row channel-add-row">
+      <div className="channel-label-cell" style={{ width: labelWidth, "--depth": depth } as CSSProperties}>
+        <button
+          ref={anchor}
+          type="button"
+          className="channel-add"
+          data-testid={`property-add-${testId}`}
+          aria-haspopup="true"
+          aria-expanded={open}
+          title="Animate another property: the first keyframe takes the value it already has, so nothing moves"
+          onClick={() => setOpen((was) => !was)}
+        >
+          + property
+        </button>
+      </div>
+      {/* In the LANE, not the label cell: the label column is one rail track
+          wide and the button already fills its share, while the lane has room
+          for "Opacity 0.42 · frame 24 · Ease Out". */}
+      <div className="channel-lane channel-add-status" data-testid={`property-add-status-${testId}`}>
+        {status}
+      </div>
+      <Popover open={open} anchor={anchor} onClose={() => setOpen(false)} className="property-pop">
+        {groups.map(([group, list]) => (
+          <div key={group} className="property-group">
+            <div className="property-group-label">{group}</div>
+            {list.map((offer) => (
+              <button
+                key={offer.path}
+                type="button"
+                className={`property-item${offer.tracked ? " is-tracked" : ""}`}
+                data-testid={`property-item-${offer.path}`}
+                disabled={offer.refusal !== null}
+                // The refusal IS the title on a disabled row, and the promise on
+                // an available one.
+                title={offer.refusal ?? `Keyframe ${offer.label} at the playhead`}
+                onClick={() => pick(offer)}
+              >
+                <span className="property-item-name">{offer.label}</span>
+                {offer.refusal !== null ? (
+                  <span className="property-item-note">{offer.refusal.replace(/^"[^"]*"\s*/, "")}</span>
+                ) : offer.tracked ? (
+                  <span className="property-item-note">animated</span>
+                ) : null}
+              </button>
+            ))}
+          </div>
+        ))}
+      </Popover>
+    </div>
+  );
+}