@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -4,88 +4,282 @@
 // Every readout is the layer AS PAINTED at the playhead and every commit goes
 // through `setEffectiveField`, so the number typed is the number drawn. See
 // ../useDocWrite.ts for why both halves are required.
-import { InspectorRow, InspectorSection, NumberField, PropertyGrid } from "@dailies-studio/ui";
+//
+// The THIRD half — a drag — is `useTransformScrub` below, and it lives here
+// because it is the seam's bracket plus this section's own vocabulary. Every
+// other section that edits a transform field imports it from here.
+import { InspectorRow, InspectorSection, NumberField, Toggle } from "@dailies-studio/ui";
+import type { ScrubHandlers } from "@dailies-studio/ui";
+import type { ReactNode } from "react";
+import { MAX_LAYER_SIZE, containerFrame, setLayerTrackSpatial } from "@dailies-studio/shot/doc";
 import type { TransformField } from "@dailies-studio/shot/doc";
-import { useSelectionValue, useTransformWrite } from "../useDocWrite.js";
+import { useStore } from "../../../state/context.js";
+import { readField, typeTransformField } from "../../../state/fieldWrite.js";
+import { authoringFrame } from "../../../state/viewMode.js";
+import { KeyframeDot } from "../KeyframeDot.js";
+import {
+  useScrub,
+  useSelectedLayers,
+  useSelectionScrub,
+  useSelectionValue,
+  useTransformWrite,
+} from "../useDocWrite.js";
 import { AlignRow } from "./AlignRow.js";
 
+/** What keys together with each box's diamond, for its tooltip: a track is
+ *  per vector (see `Pair`). */
+const POSITION_PARTS = ["X", "Y", "Z"] as const;
+const SIZE_PARTS = ["W", "H"] as const;
+const TILT_PARTS = ["Tilt X", "Tilt Y"] as const;
+
 export function TransformSection() {
   return (
-    <InspectorSection title="Transform" persistKey="shot:transform">
+    <InspectorSection className="insp-object" title="Transform" persistKey="shot:transform">
       {/* Above the fields, the way Raylight leads its Position section: the
           alignment buttons are how a layout actually gets made, and the
           numbers are how it gets adjusted afterwards. */}
       <AlignRow />
-      <PropertyGrid>
-        <Field field="x" label="X" unit="px" />
-        <Field field="y" label="Y" unit="px" />
-        <Field field="w" label="W" unit="px" min={1} />
-        <Field field="h" label="H" unit="px" min={1} />
-        {/* Depth is the field that makes this lane 3D, so it sits with the
-            position rather than in a section of its own. */}
-        <Field field="z" label="Z" unit="px" />
-        <Field field="roll" label="Roll" unit="°" step={1} />
-        <Field field="tiltX" label="Tilt X" unit="°" step={1} min={-180} max={180} />
-        <Field field="tiltY" label="Tilt Y" unit="°" step={1} min={-180} max={180} />
-      </PropertyGrid>
+      {/* EVERY BOX CARRIES THE DIAMOND OF THE TRACK IT SHOWS, inside it: X
+          and Y each carry Position's (see `Pair` for why one track lights
+          two boxes). The expose pin publishes the whole track, so only a
+          vector's first box carries it (`pin={false}` on the rest). */}
+      <Pair>
+        <Field field="x" label="X" name="Position X" unit="px" keyPath="transform.position" parts={POSITION_PARTS} />
+        <Field field="y" label="Y" name="Position Y" unit="px" keyPath="transform.position" parts={POSITION_PARTS} pin={false} />
+      </Pair>
+      <PathCurveRows />
+      {/* `MAX_LAYER_SIZE` is where the write path saturates (`setEffectiveField`),
+          so the field says the ceiling before the document answers with it. */}
+      <Pair>
+        <Field field="w" label="W" name="Layer width" unit="px" min={1} max={MAX_LAYER_SIZE} keyPath="transform.size" parts={SIZE_PARTS} />
+        <Field field="h" label="H" name="Layer height" unit="px" min={1} max={MAX_LAYER_SIZE} keyPath="transform.size" parts={SIZE_PARTS} pin={false} />
+      </Pair>
+      {/* Depth is the field that makes this lane 3D, so it sits with the
+          position rather than in a section of its own. Its TRACK is the
+          position vec3, so the Z box carries Position's diamond, lit with
+          X's and Y's (and X's box holds Position's one pin); Roll beside it
+          carries its own. One diamond for the pair keyed Roll only, beside a
+          Z it did not key. */}
+      <Pair>
+        <Field field="z" label="Z" name="Position Z" unit="px" keyPath="transform.position" parts={POSITION_PARTS} pin={false} />
+        <Field field="roll" label="Roll" unit="°" step={1} keyPath="transform.rollDeg" />
+      </Pair>
+      <Pair>
+        <Field field="tiltX" label="Tilt X" unit="°" step={1} min={-180} max={180} keyPath="transform.tilt" parts={TILT_PARTS} />
+        <Field field="tiltY" label="Tilt Y" unit="°" step={1} min={-180} max={180} keyPath="transform.tilt" parts={TILT_PARTS} pin={false} />
+      </Pair>
     </InspectorSection>
   );
 }
 
+/**
+ * Two fields side by side, each its own box with its diamond inside it.
+ *
+ * A TRACK IS PER VECTOR, not per component: `transform.position` carries x, y
+ * and z in one vec3, so keying any of them keys all three. That is the
+ * schema's own shape (one writer per FIELD, which is why validate refuses
+ * `transform.position` beside `transform.position.z`). So every box that
+ * shows a part of the vector carries the VECTOR's diamond, the same state in
+ * each, and a press in any of them keys the whole vector; the tooltip says
+ * which parts key together, so the Y box's diamond never reads as Y's own.
+ */
+function Pair({ children }: { children: ReactNode }) {
+  return (
+    <InspectorRow>
+      <div className="insp-vec">{children}</div>
+    </InspectorRow>
+  );
+}
+
+/** The tension a path takes when "Curved path" turns on. */
+const DEFAULT_TENSION = 0.5;
+
+/**
+ * "Curved path" (gap 3): the Position track's `spatialInterp`, which bends the
+ * motion path through the keys while each key's ease keeps the timing.
+ *
+ * A splineFollow layer's path is the spline, so it gets a note instead. With
+ * no Position keys there is no path to curve: the switch is disabled and says
+ * why. Over a multi-selection that disagrees each switch reads Mixed, and a
+ * press turns it on for every layer, in one undo step (the one policy every
+ * switch in the inspector keeps).
+ */
+function PathCurveRows() {
+  const store = useStore();
+  const layers = useSelectedLayers();
+  // THE TENSION'S DRAG HALF, over the same op the typed value takes, on every
+  // selected layer, re-derived from the gesture's base on each capture. The
+  // ids are read live, as `useSelectionScrub` reads them.
+  const tensionScrub = useScrub((doc, raw) => {
+    const s = store.getState();
+    const container = s.editingDef ?? s.sceneId;
+    if (container === null) return doc;
+    let next = doc;
+    for (const id of s.selection) {
+      next = setLayerTrackSpatial(next, container, id, "transform.position", {
+        type: "catmull-rom",
+        tension: Number(raw),
+      }).doc;
+    }
+    return next;
+  });
+  if (layers.length === 0) return null;
+  if (layers.some((l) => l.splineFollow !== undefined)) {
+    return <p className="insp-note">Path follows the spline.</p>;
+  }
+  const tracks = layers.map((l) => l.tracks?.["transform.position"]);
+  const keyed = tracks.every((t) => t !== undefined && t.keyframes.length > 0);
+  const curves = tracks.map((t) => t?.spatialInterp);
+  const on = keyed && curves.every((c) => c !== undefined);
+  const curvedMixed = keyed && !on && curves.some((c) => c !== undefined);
+  // Bezier handles (schema v40) replace the tension: the curve is then the
+  // handles, dragged on the stage.
+  const handles = on && curves.every((c) => c?.type === "bezier");
+  const handlesMixed = on && !handles && curves.some((c) => c?.type === "bezier");
+  const tensioned = on && curves.every((c) => c?.type === "catmull-rom");
+  const tensions = curves.map((c) => (c?.type === "catmull-rom" ? (c.tension ?? 0) : 0));
+  const ids = layers.map((l) => l.id);
+  return (
+    <>
+      <InspectorRow label="Curved path">
+        <Toggle
+          checked={on}
+          mixed={curvedMixed}
+          disabled={!keyed}
+          ariaLabel="Curved path"
+          onChange={(next) =>
+            store.setPathCurve(ids, next ? { type: "catmull-rom", tension: DEFAULT_TENSION } : null)
+          }
+        />
+      </InspectorRow>
+      {keyed ? null : <p className="insp-note">Key Position to curve its path.</p>}
+      {on ? (
+        <InspectorRow label="Path handles">
+          <Toggle
+            checked={handles}
+            mixed={handlesMixed}
+            ariaLabel="Path handles"
+            onChange={(next) =>
+              store.setPathCurve(ids, next ? { type: "bezier" } : { type: "catmull-rom", tension: DEFAULT_TENSION })
+            }
+          />
+        </InspectorRow>
+      ) : null}
+      {handles ? <p className="insp-note">Press a path dot to drag its handles.</p> : null}
+      {tensioned ? (
+        // The explanation is the ROW's tooltip: an unlabelled row puts it on
+        // the row itself (InspectorRow), where it used to be dropped.
+        <InspectorRow labelTitle="0 is the roundest curve, 1 runs straight through the keys">
+          <NumberField
+            value={tensions[0]!}
+            mixed={tensions.some((t) => t !== tensions[0])}
+            label="Tension"
+            ariaLabel="Path tension"
+            min={0}
+            max={1}
+            step={0.05}
+            precision={2}
+            onCommit={(tension) => store.setPathCurve(ids, { type: "catmull-rom", tension })}
+            onScrubStart={tensionScrub.start}
+            onScrub={tensionScrub.move}
+            onScrubEnd={tensionScrub.end}
+          />
+        </InspectorRow>
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * `useTransformWrite`'s DRAG half.
+ *
+ * Without it a NumberField still commits once at release — the seam's own
+ * fallback — but the STAGE does not move until the pointer comes up, so
+ * dragging W is a number that changes over a picture that does not. Live is the
+ * whole reason a drag handle exists.
+ *
+ * It lives here rather than at the seam because it is the seam PLUS this lane's
+ * transform vocabulary: the typed path's own builder (`typeTransformField`),
+ * re-derived from the gesture's base on every capture. With Animate on, the
+ * scrub's commit records the result as keys (`noteChange`), so one drag leaves
+ * one key per field rather than one per pointermove.
+ *
+ * Exported for AppearanceSection: `opacity` is a TransformField like every
+ * other, it just does not live in this grid.
+ */
+export function useTransformScrub(field: TransformField): ScrubHandlers {
+  const store = useStore();
+  return useSelectionScrub((layer, raw) => {
+    const s = store.getState();
+    const doc = s.doc;
+    const container = s.editingDef ?? s.sceneId;
+    if (doc === null || container === null) return layer;
+    // The frame is read LIVE, exactly as the typed path reads it: compensating
+    // against the inspector's coalesced frame would land the value up to 100ms
+    // of playhead away from where the stage is drawing it.
+    //
+    // AND ON THE CONTAINER'S OWN CLOCK. This used to read `sceneLocalFrame` off
+    // `s.sceneId` unconditionally — but `sceneId` stays set while a definition
+    // is open (it follows the playhead), so dragging W inside a component
+    // compensated against master-derived time while the def stage drew
+    // `defFrame`. The typed path next door already took this branch; the drag
+    // half did not, so the same edit did two different things depending on
+    // whether the author typed it or dragged it.
+    const at = containerFrame(doc, container, authoringFrame(s));
+    return typeTransformField(layer, field, raw as number, at, doc.fps);
+  });
+}
+
+/** One field box, carrying the diamond of the track it shows (`keyPath`);
+ *  its row comes from the `Pair` around it. */
 function Field({
   field,
   label,
+  name = label,
   unit,
   step = 1,
   min,
   max,
+  keyPath,
+  parts,
+  pin = true,
 }: {
   field: TransformField;
   label: string;
+  /** The full name: the accessible name, and the text above the pill when
+   *  Field labels is Named. Defaults to the glyph when that is already a word. */
+  name?: string;
   unit?: string;
   step?: number;
   min?: number;
   max?: number;
+  /** The track this box's value belongs to: the vector's, for a part of one. */
+  keyPath: string;
+  /** The vector's parts, which key together. */
+  parts?: readonly string[];
+  /** False for a vector's later boxes: its first box carries the one pin. */
+  pin?: boolean;
 }) {
   const write = useTransformWrite();
+  const scrub = useTransformScrub(field);
   const { value, mixed } = useSelectionValue((_layer, effective) => readField(effective, field));
   if (value === undefined) return null;
   return (
-    <InspectorRow>
-      <NumberField
-        value={value}
-        mixed={mixed}
-        label={label}
-        ariaLabel={label}
-        {...(unit === undefined ? {} : { unit })}
-        step={step}
-        {...(min === undefined ? {} : { min })}
-        {...(max === undefined ? {} : { max })}
-        onCommit={(next) => write(field, next)}
-      />
-    </InspectorRow>
+    <NumberField
+      value={value}
+      mixed={mixed}
+      label={label}
+      ariaLabel={name}
+      {...(unit === undefined ? {} : { unit })}
+      step={step}
+      {...(min === undefined ? {} : { min })}
+      {...(max === undefined ? {} : { max })}
+      trailing={<KeyframeDot path={keyPath} pin={pin} {...(parts === undefined ? {} : { parts })} />}
+      onCommit={(next) => write(field, next)}
+      onScrubStart={scrub.start}
+      onScrub={scrub.move}
+      onScrubEnd={scrub.end}
+    />
   );
 }
 
-function readField(t: { position: readonly number[]; size: readonly number[]; tilt: readonly number[]; rollDeg: number; opacity: number }, field: TransformField): number {
-  switch (field) {
-    case "x":
-      return t.position[0]!;
-    case "y":
-      return t.position[1]!;
-    case "z":
-      return t.position[2]!;
-    case "w":
-      return t.size[0]!;
-    case "h":
-      return t.size[1]!;
-    case "tiltX":
-      return t.tilt[0]!;
-    case "tiltY":
-      return t.tilt[1]!;
-    case "roll":
-      return t.rollDeg;
-    case "opacity":
-      return t.opacity;
-  }
-}