@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/animate/EaseControl.tsx

@@ -0,0 +1,244 @@
+// The ease editor that camera moves and scene transitions share.
+//
+// ── WHY THIS IS NOT `KeyframeEditor` ───────────────────────────────────
+//
+// `@dailies-studio/timeline`'s ease editor is a fine component and its INPUTS
+// are keyframe-shaped: `refs: KeyframeAddr[]` and a `TimelineGesture` whose
+// capture emits `{kind:"setEase", refs}`. A camera move or a transition has no
+// keyframes, so every one of those would be a fabricated address. What DOES
+// transfer is everything pure: `EASE_PRESETS`, `easeSelection`, `SPRING_DEFAULT`,
+// and the pad geometry `padToPx`/`pxToPad`. Those are imported, not re-derived,
+// so the chromes cannot disagree about what "Ease Out" means.
+import { useEffect, useRef } from "react";
+import {
+  EASE_GROUP_LABELS,
+  EASE_PRESETS,
+  SPRING_DEFAULT,
+  easeSelection,
+  padToPx,
+  pxToPad,
+} from "@dailies-studio/timeline";
+import type { PadGeom } from "@dailies-studio/timeline";
+import { Combobox, InspectorRow, NumberField, useLocked } from "@dailies-studio/ui";
+import type { ComboboxOption } from "@dailies-studio/ui";
+import type { Ease, SpringEase } from "@dailies-studio/engine";
+import type { PointerEvent as ReactPointerEvent } from "react";
+import { useStore } from "../../../state/context.js";
+
+const PAD_GEOM: PadGeom = { width: 216, height: 132, padY: 30 };
+
+// ---- easing ------------------------------------------------------------------
+
+/**
+ * The ease row, plus whichever editor the chosen ease needs.
+ *
+ * Takes an `Ease` and not a subject, because a camera move and a transition both
+ * carry one and read it the same way. Two ease editors would be
+ * two places for "Ease Out" to mean something slightly different, which is the
+ * whole reason `EASE_PRESETS` is imported rather than re-declared.
+ */
+export function EaseControl(props: {
+  ease?: Ease;
+  /** What the select is called. The subject differs between the two callers and
+   *  the accessible name has to say which one the author is looking at. */
+  ariaLabel?: string;
+  onEase(ease: Ease): void;
+  onScrub(ease: Ease): void;
+}) {
+  const ease = props.ease;
+  // `easeSelection` takes a LIST because the shared editor is multi-select. One
+  // ease is a list of one, and reusing it keeps "Custom" meaning exactly what
+  // it means in the other two chromes.
+  const sel = easeSelection(ease === undefined ? [] : [ease]);
+  const options: ComboboxOption[] = [
+    // Grouped — the flat row cannot survive the full named vocabulary.
+    ...EASE_PRESETS.map((p) => ({
+      value: p.id,
+      label: p.label,
+      group: EASE_GROUP_LABELS[p.group ?? "basic"],
+    })),
+    // NOT PRESETS, and not selectable in any useful sense: "custom" is a
+    // hand-dragged bezier and "mixed" is no ease at all. They are listed only
+    // so the closed picker can NAME what it is showing: a value with no option
+    // behind it would read as the raw string. Choosing one is a no-op below,
+    // which is what the disabled <option> they replace did.
+    ...(sel.selectValue === "custom" ? [{ value: "custom", label: "Custom" }] : []),
+    ...(sel.selectValue === "mixed" ? [{ value: "mixed", label: "Mixed" }] : []),
+  ];
+
+  return (
+    <>
+      <InspectorRow label="Ease">
+        <Combobox
+          ariaLabel={props.ariaLabel ?? "Camera move ease"}
+          options={options}
+          value={sel.selectValue}
+          onChange={(next) => {
+            const preset = EASE_PRESETS.find((p) => p.id === next);
+            if (preset !== undefined) props.onEase(preset.ease);
+          }}
+        />
+      </InspectorRow>
+      {sel.ease?.type === "bezier" && <BezierPad handles={sel.ease.handles} onEase={props.onScrub} />}
+      {sel.ease?.type === "spring" && <SpringFields spring={sel.ease} onEase={props.onEase} onScrub={props.onScrub} />}
+    </>
+  );
+}
+
+/**
+ * The bezier handle editor.
+ *
+ * ONE DRAG IS ONE UNDO ENTRY. Every move emits an ease, and each caller's verb
+ * (`setSceneTransition`, `setShotEase`) captures into the open
+ * gesture when there is one. So the drag opens an inspector scrub on press and
+ * closes it on release: without it each pointermove was its own transaction
+ * and one drag flooded the history. A cancel, a lost capture or an unmount
+ * mid-drag discards, which restores the pre-drag ease exactly.
+ *
+ * A viewer's locked panel draws the curve and its handles and takes no press:
+ * the handles carry no listeners and `pointer-events: none`, so neither a
+ * drag nor the grab cursor offers a change the store would refuse.
+ */
+function BezierPad(props: {
+  handles: readonly [number, number, number, number];
+  onEase(ease: Ease): void;
+}) {
+  const store = useStore();
+  const locked = useLocked();
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const drag = useRef<{ index: 0 | 1; base: [number, number, number, number] } | null>(null);
+  // An unmount mid-drag (the subject changed under the pointer) cancels.
+  useEffect(
+    () => () => {
+      if (drag.current === null) return;
+      drag.current = null;
+      store.endScrub(false);
+    },
+    [store],
+  );
+
+  const down =
+    (index: 0 | 1) =>
+    (e: ReactPointerEvent<SVGCircleElement>): void => {
+      if (e.button !== 0) return;
+      e.currentTarget.setPointerCapture(e.pointerId);
+      const h = props.handles;
+      drag.current = { index, base: [h[0], h[1], h[2], h[3]] };
+      store.beginScrub();
+    };
+
+  const move = (e: ReactPointerEvent<SVGCircleElement>): void => {
+    const d = drag.current;
+    const svg = svgRef.current;
+    if (d === null || svg === null) return;
+    const rect = svg.getBoundingClientRect();
+    const [x, y] = pxToPad(PAD_GEOM, e.clientX - rect.left, e.clientY - rect.top);
+    // Rebuilt from the DRAG-START handles, so the untouched one cannot creep as
+    // the live value it is being compared against changes underneath.
+    const handles: [number, number, number, number] =
+      d.index === 0 ? [x, y, d.base[2], d.base[3]] : [d.base[0], d.base[1], x, y];
+    props.onEase({ type: "bezier", handles });
+  };
+
+  const up = (e: ReactPointerEvent<SVGCircleElement>): void => {
+    if (drag.current === null) return;
+    drag.current = null;
+    store.endScrub(true);
+    e.currentTarget.releasePointerCapture(e.pointerId);
+  };
+
+  const h = props.handles;
+  const [ax, ay] = padToPx(PAD_GEOM, 0, 0);
+  const [bx, by] = padToPx(PAD_GEOM, 1, 1);
+  const [x1, y1] = padToPx(PAD_GEOM, h[0], h[1]);
+  const [x2, y2] = padToPx(PAD_GEOM, h[2], h[3]);
+  const cancel = (): void => {
+    if (drag.current === null) return;
+    drag.current = null;
+    store.endScrub(false);
+  };
+  const handle = (index: 0 | 1) =>
+    locked
+      ? { className: "insp-pad-handle", r: 4.5, pointerEvents: "none" }
+      : {
+          className: "insp-pad-handle",
+          r: 4.5,
+          onPointerDown: down(index),
+          onPointerMove: move,
+          onPointerUp: up,
+          onPointerCancel: cancel,
+          // CAPTURE LOSS closes the gesture too, the same pairing `NumberField`'s
+          // drag keeps. Without it a lost capture leaves `drag` armed with no
+          // pointer down, and the next hover across the handle drags it. After
+          // a normal pointerup the ref is already null, so the trailing event
+          // is a no-op.
+          onLostPointerCapture: cancel,
+        };
+
+  return (
+    <svg ref={svgRef} className="insp-pad" width={PAD_GEOM.width} height={PAD_GEOM.height}>
+      <rect
+        className="insp-pad-box"
+        x={0.5}
+        y={PAD_GEOM.padY + 0.5}
+        width={PAD_GEOM.width - 1}
+        height={PAD_GEOM.height - 2 * PAD_GEOM.padY - 1}
+        rx={3}
+      />
+      <path className="insp-pad-curve" d={`M ${ax} ${ay} C ${x1} ${y1} ${x2} ${y2} ${bx} ${by}`} />
+      <line className="insp-pad-arm" x1={ax} y1={ay} x2={x1} y2={y1} />
+      <line className="insp-pad-arm" x1={bx} y1={by} x2={x2} y2={y2} />
+      <circle {...handle(0)} cx={x1} cy={y1} />
+      <circle {...handle(1)} cx={x2} cy={y2} />
+    </svg>
+  );
+}
+
+const SPRING_FIELDS = {
+  stiffness: { label: "Stiffness", min: 1, max: 1000, step: 1 },
+  damping: { label: "Damping", min: 0, max: 200, step: 0.5 },
+  mass: { label: "Mass", min: 0.05, max: 20, step: 0.05 },
+} as const;
+
+/** The spring's rows: Stiffness | Damping, then Mass. The two-box rule: three
+ *  word labels in one row left each box about 70px at the rail's 264px floor,
+ *  and "Stiffness" with its value clipped. */
+const SPRING_ROWS: ReadonlyArray<ReadonlyArray<keyof typeof SPRING_FIELDS>> = [["stiffness", "damping"], ["mass"]];
+
+/**
+ * The spring's three numbers. A DRAG is one undo entry that moves the stage
+ * under the pointer, the bezier pad's rule: the panel scrub opens on the
+ * drag, every move goes through `onScrub`, whose verb (`setShotEase`,
+ * `setSceneTransition`) captures into it, and the release closes it.
+ */
+function SpringFields(props: { spring: SpringEase; onEase(ease: Ease): void; onScrub(ease: Ease): void }) {
+  const store = useStore();
+  const field = (key: keyof typeof SPRING_FIELDS) => {
+    const f = SPRING_FIELDS[key];
+    const ease = (v: number): Ease => ({ ...SPRING_DEFAULT, ...props.spring, [key]: v });
+    return (
+      <NumberField
+        key={key}
+        value={props.spring[key]}
+        label={f.label}
+        ariaLabel={`Spring ${f.label.toLowerCase()}`}
+        min={f.min}
+        max={f.max}
+        step={f.step}
+        onScrubStart={() => store.beginScrub()}
+        onScrub={(v) => props.onScrub(ease(v))}
+        onScrubEnd={(commit) => store.endScrub(commit)}
+        onCommit={(v) => props.onEase(ease(v))}
+      />
+    );
+  };
+  return (
+    <>
+      {SPRING_ROWS.map((row) => (
+        <InspectorRow key={row.join("|")}>
+          {row.length === 1 ? field(row[0]!) : <div className="insp-vec">{row.map(field)}</div>}
+        </InspectorRow>
+      ))}
+    </>
+  );
+}

package/src/panels/inspector/animate/PresetsSection.tsx

@@ -0,0 +1,135 @@
+// MOTION: one-click entrances, loops and exits, as STAMPS (motionPresets.ts).
+//
+// Picking a preset writes ordinary keyframes on every selected layer and
+// selects them; nothing is stored about the preset. So this section never
+// shows "In: Rise" afterwards, and has no state of its own to keep in step
+// with the document: the diamonds, the dock and Graph mode are the record.
+// Each row is always an offer ("Add an entrance"), never a current value.
+//
+// THE LIST IS WHAT EVERY SELECTED LAYER CAN TAKE (`motionPresetRefusal`), so a
+// Draw on is offered only over a spline and a Count up only over a component
+// with a numeric progress. The stamp asks again at write time with the window,
+// and its refusal is the error line's.
+//
+// Length and Ease apply to the next pick. "Preset's own" is each preset's
+// default; a During loop fills the gap around the playhead whatever its length.
+//
+// The active row PREVIEWS on the stage (bridge v53), the font picker's model:
+// nothing writes until a pick.
+import { useMemo, useState } from "react";
+import { Combobox, InspectorRow, InspectorSection, useLocked } from "@dailies-studio/ui";
+import type { ComboboxOption } from "@dailies-studio/ui";
+import { EASE_GROUP_LABELS, EASE_PRESETS } from "@dailies-studio/timeline";
+import { MOTION_PRESETS, homeOf, motionPresetRefusal } from "@dailies-studio/shot/doc";
+import type { Layer3D, MotionPresetRequest, MotionPresetSlot } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { formatDuration } from "../../timeline/model.js";
+
+const SLOTS: readonly { slot: MotionPresetSlot; label: string; placeholder: string }[] = [
+  { slot: "in", label: "In", placeholder: "Add an entrance" },
+  { slot: "during", label: "During", placeholder: "Add a loop" },
+  { slot: "out", label: "Out", placeholder: "Add an exit" },
+];
+
+/** Lengths offered for In and Out, seconds. */
+const LENGTHS_S = [0.2, 0.33, 0.5, 0.75, 1, 1.5, 2] as const;
+const OWN = "";
+
+export function PresetsSection() {
+  const store = useStore();
+  const locked = useLocked();
+  const doc = useShotEditor((s) => s.doc);
+  const container = useShotEditor((s) => s.editingDef ?? s.sceneId);
+  const selection = useShotEditor((s) => s.selection);
+  const contracts = useShotEditor((s) => s.contracts);
+  const [lengthS, setLengthS] = useState(OWN);
+  const [easeId, setEaseId] = useState(OWN);
+
+  // The STORED layers: `motionPresetRefusal` reads the document's own fields,
+  // not the track-resolved values the other sections show.
+  const layers = useMemo((): Layer3D[] => {
+    if (doc === null || container === null) return [];
+    const home = homeOf(doc, container);
+    return home === null ? [] : selection.map((id) => home.layersById[id]).filter((l): l is Layer3D => l !== undefined);
+  }, [doc, container, selection]);
+
+  const offered = useMemo(() => {
+    const out = new Map<MotionPresetSlot, ComboboxOption[]>();
+    if (doc === null || container === null || layers.length === 0) return out;
+    for (const preset of MOTION_PRESETS) {
+      const fits = layers.every(
+        (layer) =>
+          motionPresetRefusal(doc, container, layer, preset.id, layer.kind === "instance" ? contracts[layer.instance.component] : undefined) === null,
+      );
+      if (!fits) continue;
+      out.set(preset.slot, [...(out.get(preset.slot) ?? []), { value: preset.id, label: preset.label }]);
+    }
+    return out;
+  }, [doc, container, layers, contracts]);
+
+  if (doc === null || layers.length === 0) return null;
+  const fps = doc.fps.num / doc.fps.den;
+  const easeOptions: ComboboxOption[] = [
+    { value: OWN, label: "Preset's own" },
+    ...EASE_PRESETS.map((p) => ({ value: p.id, label: p.label, group: EASE_GROUP_LABELS[p.group ?? "basic"] })),
+  ];
+  const lengthOptions: ComboboxOption[] = [
+    { value: OWN, label: "Preset's own" },
+    ...LENGTHS_S.map((s) => ({ value: String(s), label: formatDuration(s) })),
+  ];
+  const request = (preset: string): Omit<MotionPresetRequest, "at"> => {
+    const ease = EASE_PRESETS.find((p) => p.id === easeId)?.ease;
+    return {
+      preset,
+      ...(lengthS === OWN ? {} : { lengthFrames: Math.max(1, Math.round(Number(lengthS) * fps)) }),
+      ...(ease === undefined ? {} : { ease }),
+    };
+  };
+  const hasText = layers.some((l) => l.kind === "text");
+
+  return (
+    <InspectorSection
+      title="Motion"
+      persistKey="shot:presets"
+      note="· writes keyframes"
+    >
+      {SLOTS.map(({ slot, label, placeholder }) => {
+        const options = offered.get(slot) ?? [];
+        return (
+          <InspectorRow key={slot} label={label}>
+            <Combobox
+              ariaLabel={`${label} preset`}
+              options={options}
+              value=""
+              placeholder={options.length === 0 ? "None fits this selection" : placeholder}
+              disabled={options.length === 0}
+              onChange={(id) => void store.applyMotionPreset(request(id))}
+              onActive={(id) => store.previewMotion(id === null ? null : request(id))}
+            />
+          </InspectorRow>
+        );
+      })}
+      <InspectorRow label="Length">
+        <Combobox ariaLabel="Preset length" options={lengthOptions} value={lengthS} onChange={setLengthS} />
+      </InspectorRow>
+      <InspectorRow label="Ease">
+        <Combobox ariaLabel="Preset ease" options={easeOptions} value={easeId} onChange={setEaseId} />
+      </InspectorRow>
+      {hasText ? (
+        <InspectorRow label="Letters">
+          <div className="insp-buttons">
+            <button
+              type="button"
+              className="btn"
+              disabled={locked}
+              title="Per-letter and per-word reveals are library components: typewriter-text, word-stream, rise-per-char"
+              onClick={() => store.setLibraryBrowserOpen(true, "component")}
+            >
+              Per-letter effects in the Library
+            </button>
+          </div>
+        </InspectorRow>
+      ) : null}
+    </InspectorSection>
+  );
+}