@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/design/MediaSection.tsx

@@ -6,25 +6,54 @@
 //
 // `image` and `video` are one pipeline everywhere it matters: the runtime
 // collapses both to {asset, fit, crop} and draws them through one plane. So the
-// controls they share are authored once here, and the two fields that differ —
-// `alt` on an image, `offsetFrames` on a video — are rows that only their own
-// kind renders rather than a second section.
+// controls they share are authored once here, and the one field that differs —
+// `alt` on an image — is a row that only its own kind renders rather than a
+// second section.
 //
 // ── WHY THIS SECTION HAD TO EXIST ───────────────────────────────────────
 //
-// `fit`, `crop`, `alt` and `offsetFrames` were all reachable ONLY through an
-// MCP call. A document can therefore hold a crop or a source offset that the
-// author cannot see, let alone undo, from the chrome that wrote the layer.
+// `fit`, `crop` and `alt` were all reachable ONLY through an MCP call. A
+// document can therefore hold a crop the author cannot see, let alone undo,
+// from the chrome that wrote the layer.
+//
+// ── WHAT THIS SECTION IS NOT, AND WHERE THOSE THREE WENT ────────────────
+//
+// `offsetFrames` ("Starts at"), `loop` ("Past end") and `timeScale` ("Rate")
+// USED TO BE HERE and are now `TimeSection`'s, because all three are WHEN and
+// this section is WHAT. Each had exactly one home before and still does: a
+// field with two homes is two readouts of one number that disagree the moment
+// either one compensates and the other does not.
+//
+// They did not simply move, either. The source offset is now spelled in the
+// ruler an author states an edit in — "play the recording from source frame
+// 120", through `setVideoSource` — and the rate goes through `retimeVideo`, so
+// a speed change keeps the window and the frame it opens on instead of scrubbing
+// the footage sideways under a cut that is already timed. Neither behaviour was
+// reachable from the raw fields that stood here.
 import {
+  IconMinus,
+  IconPlus,
   InspectorRow,
   InspectorSection,
   NumberField,
   PropertyGrid,
   SegmentedControl,
   TextField,
+  useLocked,
+  wordOptions,
 } from "@dailies-studio/ui";
+import { useRef, useState } from "react";
+import { KeyframeDot } from "../KeyframeDot.js";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { IMAGE_ACCEPT, VIDEO_ACCEPT } from "../../toolbar/useAddRows.js";
+import { cropAnchor, cropMagnification, zoomCrop } from "@dailies-studio/shot/doc";
 import type { Crop, ImageLayer3D, Layer3D, LayerFit, VideoLayer3D } from "@dailies-studio/shot/doc";
-import { useSelectedLayers, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+import {
+  useSelectedLayers,
+  useSelectionScrub,
+  useSelectionValue,
+  useSelectionWrite,
+} from "../useDocWrite.js";
 
 /**
  * The two content blocks as ONE shape.
@@ -46,132 +75,211 @@ const FITS = ["fill", "fit", "stretch"] as const satisfies readonly LayerFit[];
  *  source" is exactly what an absent crop already means. */
 const FULL_CROP: Crop = { x: 0, y: 0, w: 1, h: 1 };
 
+/**
+ * The crop's quantum, and it is NOT 0.01.
+ *
+ * These edges are min 0 / max 1. What 0.05 buys is the KEYBOARD and the drag's
+ * snap — an arrow key crosses the source in 20 presses instead of 100, and the
+ * pill lands on 21 stops rather than 101 two-pixel ones. It is also what the
+ * rest of this chrome already picked for a bounded 0..1 field (EffectsSection's
+ * vignette and ghost amounts). Alt divides the quantum by ten and places
+ * continuously; typing is unquantised either way.
+ */
+const CROP_STEP = 0.05;
+
+/** The crop's four edges, the order the fields list them in, and how the
+ *  Zoom diamond's tooltip names them (it keys all four together). */
+const CROP_AXES = ["x", "y", "w", "h"] as const satisfies readonly (keyof Crop)[];
+const CROP_PARTS = ["Crop X", "Crop Y", "Crop W", "Crop H"] as const;
+
 export function MediaSection() {
   const write = useSelectionWrite();
   const layers = useSelectedLayers();
-  const media = useSelectionValue((layer) => mediaOf(layer));
+  // A SCALAR, one hook per row, and it is `CropField` below that holds the last
+  // of them. This section used to read the whole media block here and hand its
+  // `mixed` to every field, and `useSelectionValue` compares with `Object.is` —
+  // so every multi-selection reported "Mixed" on all five fields, including a
+  // selection whose blocks are identical, for ever and with no way to tell it
+  // from a real disagreement.
+  //
+  // The zoom's own drag bracket. Re-derived from the gesture's BASE document
+  // like every other capture here, so a drag compounds nothing: without it the
+  // magnification would read its own last write and run away from the cursor.
+  const zoomScrub = useSelectionScrub((layer, raw) =>
+    applyMedia(layer, (m) => ({ ...m, crop: zoomCrop(cropAnchor(m.crop), raw as number) })),
+  );
+  // Mixed over what the Zoom field SHOWS, the magnification, per layer: two
+  // crops of one size at different places agree on it.
+  const zoom = useSelectionValue((layer) => {
+    const own = mediaOf(layer)?.crop;
+    return own === undefined ? undefined : cropMagnification(own);
+  });
   // The first media layer in the selection, which is what the title names and
   // what the per-kind rows are chosen by. Read from the LIST rather than from
   // `media.value` (which is the first SELECTED layer's, media or not), so a
   // rect clicked before an image does not empty the section.
   const subject = layers.find(isMedia);
+  const store = useStore();
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+  // The crop action and Replace are plain buttons, so they read a viewer's
+  // lock here; every other row is a widget that reads it itself.
+  const locked = useLocked();
+  const assetPath = useShotEditor((s) => {
+    const id = subject === undefined ? undefined : mediaOf(subject)?.asset;
+    return id === undefined ? undefined : s.doc?.assets[id]?.path;
+  });
   if (subject === undefined) return null;
   const block = mediaOf(subject);
   if (block === undefined) return null;
 
-  /** Every write goes through one mapper, KIND-GUARDED INSIDE IT: the seam fans
-   *  out over the whole selection, and a rect has no `fit` to set.
-   *
-   *  `only` narrows that fan-out further, and the per-kind rows MUST use it.
-   *  The rows are chosen by the first media layer in the selection, but the
-   *  write reaches every one of them — so with an image and a video selected
-   *  together, the image's Alt row would otherwise write `alt` into the video
-   *  block and the video's Start row would write `offsetFrames` into the image.
-   *  `MediaBlock` is the intersection of the two, which makes both foreign keys
-   *  type-legal, and `validateShotDoc` is deliberately not stricter than the
-   *  resolver, so nothing downstream refuses them. They surface much later, as
-   *  an excess-property error in the generated `satisfies Doc3D` literal. */
   const patch = (next: (media: MediaBlock) => MediaBlock, only?: "image" | "video"): void =>
-    write((layer) =>
-      layer.kind === "image" && only !== "video"
-        ? { ...layer, image: next(layer.image) }
-        : layer.kind === "video" && only !== "image"
-          ? { ...layer, video: next(layer.video) }
-          : layer,
-    );
-
-  const setCrop = (key: keyof Crop, value: number): void =>
-    patch((m) => ({ ...m, crop: { ...(m.crop ?? FULL_CROP), [key]: clamp01(value) } }));
+    write((layer) => applyMedia(layer, next, only));
 
   const crop = block.crop;
+  // ONE media layer only: a replace swaps one layer's file, and with two
+  // selected there is no single file for the row to name.
+  const media = subject;
+  const medias = layers.filter(isMedia);
+  const replaceable = medias.length === 1;
+  // Mixed among the layers each row WRITES, as the Html rows ask theirs: Fit
+  // reaches every media layer and Alt every image, and a rect beside them has
+  // no fit or description to disagree with. Both rows used to show the first
+  // media layer's value as if the selection shared it.
+  const fitMixed = medias.some((l) => mediaOf(l)?.fit !== block.fit);
+  const altMixed = medias.some((l) => l.kind === "image" && (l.image.alt ?? "") !== (block.alt ?? ""));
+  const pick = (file: File): void => {
+    setBusy(true);
+    void store
+      .replaceLayerMedia(media.id, file)
+      .catch((e: unknown) => store.reportError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setBusy(false));
+  };
 
   return (
     <InspectorSection
+      className="insp-object"
       title={subject.kind === "video" ? "Video" : "Image"}
       persistKey="shot:media"
       action={
         <button
           type="button"
-          className="section-action"
+          className="btn is-icon insp-section-action"
           title={crop === undefined ? "Add crop" : "Remove crop"}
+          aria-label={crop === undefined ? "Add crop" : "Remove crop"}
+          disabled={locked}
           onClick={() =>
             patch((m) => (m.crop === undefined ? { ...m, crop: FULL_CROP } : without(m, "crop")))
           }
         >
-          {crop === undefined ? "+" : "−"}
+          {crop === undefined ? <IconPlus /> : <IconMinus />}
         </button>
       }
     >
+      {replaceable ? (
+        <InspectorRow label="Source">
+          {/* A file NAME, so the row's own type and not the numeral face a
+              number reads in; it ellipsizes before the button. */}
+          <span className="insp-dim is-text" title={assetPath}>
+            {assetPath === undefined ? "File missing" : assetPath.replace(/^[0-9a-f]{8}-/u, "")}
+          </span>
+          <button type="button" className="btn" disabled={locked || busy} onClick={() => fileRef.current?.click()}>
+            Replace…
+          </button>
+          <input
+            ref={fileRef}
+            type="file"
+            hidden
+            aria-label={subject.kind === "video" ? "Replace video file" : "Replace image file"}
+            accept={subject.kind === "video" ? VIDEO_ACCEPT : IMAGE_ACCEPT}
+            onChange={(event) => {
+              const file = event.currentTarget.files?.[0];
+              event.currentTarget.value = "";
+              if (file !== undefined) pick(file);
+            }}
+          />
+        </InspectorRow>
+      ) : null}
+
       <InspectorRow label="Fit">
         <SegmentedControl
           ariaLabel="Media fit"
-          value={block.fit}
-          options={FITS.map((fit) => ({ value: fit, label: fit }))}
+          // An unmatched value is how a segmented control says Mixed.
+          value={fitMixed ? "" : block.fit}
+          options={wordOptions(FITS)}
           onChange={(next) => patch((m) => ({ ...m, fit: next as LayerFit }))}
         />
       </InspectorRow>
 
+      {/* THE PUNCH-IN, as one number.
+
+          "Zoom into that button" is this product class's defining gesture, and
+          it was expressible only by typing four crop edges by hand. It is a CROP
+          and not a scale or a camera move, because those two magnify the wrong
+          thing: a camera `zoom` takes the background and the border with it, and
+          a layer scale works about `transform.position`, which IS the layer's
+          centre — `Transform3D` has no anchor, so a scale can only ever punch
+          into the middle of a recording.
+
+          It writes the same four `video.crop.*` / `image.crop.*` numbers the
+          edges below do, so an ANIMATED punch-in is the diamond workflow: key
+          the zoom at 1x, move the playhead, key it at 2x. Its box carries ONE
+          diamond over the four crop tracks, keyed together like the Corner
+          row's four radii. */}
+      {crop !== undefined ? (
+        <InspectorRow>
+          <NumberField
+            value={cropMagnification(crop)}
+            mixed={zoom.mixed}
+            label="Zoom"
+            title="Magnify a region of the source. Keeps the plate, the border and the background where they are"
+            ariaLabel="Media zoom"
+            unit="x"
+            min={1}
+            // Below 1 there is no source left to sample.
+            step={0.1}
+            trailing={
+              <KeyframeDot
+                path={CROP_AXES.map((axis) => `${subject.kind}.crop.${axis}`)}
+                label="Zoom"
+                parts={CROP_PARTS}
+              />
+            }
+            onScrubStart={zoomScrub.start}
+            onScrub={zoomScrub.move}
+            onScrubEnd={zoomScrub.end}
+            onCommit={(next) =>
+              write((layer) =>
+                applyMedia(layer, (m) => ({ ...m, crop: zoomCrop(cropAnchor(m.crop), next) })),
+              )
+            }
+          />
+        </InspectorRow>
+      ) : null}
+
       {/* Fractions of the SOURCE, not of the box, and y counts DOWN from the
           top row the way a screenshot's own pixels are numbered — media.ts owns
           the flip into uv space, so these are the numbers a design tool would
           report for the same rectangle. */}
       {crop !== undefined ? (
         <PropertyGrid>
-          <InspectorRow>
-            <NumberField
-              value={crop.x}
-              mixed={media.mixed}
-              label="X"
-              ariaLabel="Crop x"
-              min={0}
-              max={1}
-              step={0.01}
-              onCommit={(next) => setCrop("x", next)}
-            />
-          </InspectorRow>
-          <InspectorRow>
-            <NumberField
-              value={crop.y}
-              mixed={media.mixed}
-              label="Y"
-              ariaLabel="Crop y"
-              min={0}
-              max={1}
-              step={0.01}
-              onCommit={(next) => setCrop("y", next)}
-            />
-          </InspectorRow>
-          <InspectorRow>
-            <NumberField
-              value={crop.w}
-              mixed={media.mixed}
-              label="W"
-              ariaLabel="Crop width"
-              min={0}
-              max={1}
-              step={0.01}
-              onCommit={(next) => setCrop("w", next)}
-            />
-          </InspectorRow>
-          <InspectorRow>
-            <NumberField
-              value={crop.h}
-              mixed={media.mixed}
-              label="H"
-              ariaLabel="Crop height"
-              min={0}
-              max={1}
-              step={0.01}
-              onCommit={(next) => setCrop("h", next)}
-            />
-          </InspectorRow>
+          {/* THE KEN BURNS MOVE. The track path is per KIND — there is no
+              top-level `crop`, each media kind owns one — so the subject's own
+              kind names it. A mixed image+video selection hides the diamonds by
+              itself: `KeyframeDot` needs every selected layer to accept the
+              path, and neither kind accepts the other's. */}
+          <CropField axis="x" label="X" ariaLabel="Crop x" value={crop.x} kind={subject.kind} />
+          <CropField axis="y" label="Y" ariaLabel="Crop y" value={crop.y} kind={subject.kind} />
+          <CropField axis="w" label="W" ariaLabel="Crop width" value={crop.w} kind={subject.kind} />
+          <CropField axis="h" label="H" ariaLabel="Crop height" value={crop.h} kind={subject.kind} />
         </PropertyGrid>
       ) : null}
 
       {subject.kind === "image" ? (
         <InspectorRow label="Alt">
           <TextField
-            value={block.alt ?? ""}
+            value={altMixed ? "" : (block.alt ?? "")}
+            {...(altMixed ? { placeholder: "Mixed" } : {})}
             ariaLabel="Alt text"
             onCommit={(next) =>
               patch((m) => {
@@ -185,46 +293,91 @@ export function MediaSection() {
           />
         </InspectorRow>
       ) : null}
-
-      {subject.kind === "video" ? (
-        // PLACEMENT, NOT A TRIM. This is the scene frame the source's own t=0
-        // lands on, so every frame before it holds the source's FIRST frame and
-        // nothing is cut off the head. Audio's identically-named `offsetFrames`
-        // is the other thing — a trim into the source — and confusing the two
-        // is why the label says "starts at" rather than "start".
-        <InspectorRow label="Starts at" labelTitle="The scene frame this clip's first frame lands on — a delay, never a trim into the source">
-          <NumberField
-            value={block.offsetFrames ?? 0}
-            mixed={media.mixed}
-            ariaLabel="Video start frame"
-            unit="f"
-            step={1}
-            // NO `min`. NumberField clamps against it on every commit path —
-            // typing, the stepper and the drag — so `min={0}` would turn the
-            // one value this feature exists to preserve into 0 the first time
-            // the author touched the field, and the `frames === 0` branch below
-            // would then DELETE it, jumping the footage. A negative offset is
-            // what `splitScene` produces for a clip already playing at the cut,
-            // and it is untypeable, so erasing one is unrecoverable.
-            //
-            // 0 DELETES the key: absent already means "starts at frame 0", and
-            // an explicit 0 is a second way to say the same thing that codegen
-            // then prints. `Math.round` covers the only bound the save gate
-            // actually holds — the value must be an integer.
-            onCommit={(next) => {
-              const frames = Math.round(next);
-              patch(
-                (m) => (frames === 0 ? without(m, "offsetFrames") : { ...m, offsetFrames: frames }),
-                "video",
-              );
-            }}
-          />
-        </InspectorRow>
-      ) : null}
     </InspectorSection>
   );
 }
 
+/**
+ * One crop edge, and its own drag bracket.
+ *
+ * A row rather than inline JSX because a bracket is a HOOK and there is one
+ * gesture per edge. Both halves go through `withCrop`, because a capture is
+ * handed a layer out of the gesture's BASE document: an edge that re-derived
+ * itself from what the panel last rendered would compound its own moves and run
+ * away from the cursor.
+ */
+function CropField(props: {
+  axis: keyof Crop;
+  label: string;
+  ariaLabel: string;
+  value: number;
+  kind: Layer3D["kind"];
+}) {
+  const { axis } = props;
+  const write = useSelectionWrite();
+  // This edge's own agreement, read as the SCALAR the row displays.
+  const { mixed } = useSelectionValue((layer) => mediaOf(layer)?.crop?.[axis]);
+  const scrub = useSelectionScrub((layer, raw) =>
+    applyMedia(layer, (m) => withCrop(m, axis, raw as number)),
+  );
+  return (
+    <InspectorRow>
+      <NumberField
+        value={props.value}
+        mixed={mixed}
+        label={props.label}
+        ariaLabel={props.ariaLabel}
+        min={0}
+        max={1}
+        step={CROP_STEP}
+        trailing={<KeyframeDot path={`${props.kind}.crop.${axis}`} label={props.ariaLabel} />}
+        onCommit={(next) => write((layer) => applyMedia(layer, (m) => withCrop(m, axis, next)))}
+        onScrubStart={scrub.start}
+        onScrub={scrub.move}
+        onScrubEnd={scrub.end}
+      />
+    </InspectorRow>
+  );
+}
+
+/**
+ * Every write goes through one mapper, KIND-GUARDED INSIDE IT: the seam fans
+ * out over the whole selection, and a rect has no `fit` to set.
+ *
+ * `only` narrows that fan-out further, and the per-kind rows MUST use it. The
+ * rows are chosen by the first media layer in the selection, but the write
+ * reaches every one of them — so with an image and a video selected together,
+ * the image's Alt row would otherwise write `alt` into the video block.
+ * `MediaBlock` is the intersection of the two, which makes such a foreign key
+ * type-legal, and `validateShotDoc` is deliberately not stricter than the
+ * resolver, so nothing downstream refuses it. It surfaces much later, as an
+ * excess-property error in the generated `satisfies Doc3D` literal.
+ *
+ * ONE row uses it today (`alt`), because the three video-only rows that used to
+ * need it are `TimeSection`'s now and that section writes through the clip ops
+ * over ONE layer. The parameter stays: `only` is the rule, not a workaround for
+ * the rows that happened to exist, and the next per-kind field needs it on its
+ * first day.
+ *
+ * PURE and module-level rather than closed over `write`, because the drag needs
+ * the same mapper and a capture only ever gets a layer handed to it.
+ */
+function applyMedia(
+  layer: Layer3D,
+  next: (media: MediaBlock) => MediaBlock,
+  only?: "image" | "video",
+): Layer3D {
+  return layer.kind === "image" && only !== "video"
+    ? { ...layer, image: next(layer.image) }
+    : layer.kind === "video" && only !== "image"
+      ? { ...layer, video: next(layer.video) }
+      : layer;
+}
+
+function withCrop(media: MediaBlock, key: keyof Crop, value: number): MediaBlock {
+  return { ...media, crop: { ...(media.crop ?? FULL_CROP), [key]: clamp01(value) } };
+}
+
 function isMedia(layer: Layer3D): boolean {
   return layer.kind === "image" || layer.kind === "video";
 }
@@ -238,7 +391,7 @@ function mediaOf(layer: Layer3D): MediaBlock | undefined {
 /** Drop one optional key, rather than setting it to `undefined`. Under
  *  exactOptionalPropertyTypes those are different values, and codegen prints
  *  the block by key order — a present-but-undefined key is a key. */
-function without(media: MediaBlock, key: "crop" | "alt" | "offsetFrames"): MediaBlock {
+function without(media: MediaBlock, key: "crop" | "alt"): MediaBlock {
   const { [key]: _drop, ...rest } = media;
   return rest;
 }