@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -6,39 +6,66 @@
 // ponytail: uniform radius only; add the per-corner expander when a template
 // needs one.
 import { InspectorRow, InspectorSection, NumberField } from "@dailies-studio/ui";
-import type { CornerRadius } from "@dailies-studio/shot/doc";
-import { useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+import { KeyframeDot } from "../KeyframeDot.js";
+import type { CornerRadius, Layer3D, LayerPaint } from "@dailies-studio/shot/doc";
+import { useSelectedLayers, useSelectionScrub, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+
+/** The four corners this section's one field writes, in the schema's own key
+ *  order — which is also the order codegen prints them in. */
+const RADIUS_PATHS = ["paint.radius.tl", "paint.radius.tr", "paint.radius.br", "paint.radius.bl"] as const;
+/** The same four, as the diamond's tooltip names what it keys together. */
+const RADIUS_PARTS = ["Top left", "top right", "bottom right", "bottom left"] as const;
 
 export function CornerSection() {
   const write = useSelectionWrite();
   const radius = useSelectionValue((layer) => uniformOf(layer.paint.radius));
+  // Mixed INSIDE one layer too: an edit writes one value to all four corners,
+  // so a layer with per-corner radii reads Mixed before that flattens it.
+  const cornersDiffer = useSelectedLayers().some((layer) => !isUniform(layer.paint.radius));
+  // ONE builder for the typed value and the drag, because a capture is handed a
+  // layer out of the gesture's BASE document: a drag that re-derived the corner
+  // from what the panel last rendered would compound its own moves.
+  const scrub = useSelectionScrub((layer, raw) => withRadius(layer, raw as number));
 
   return (
-    <InspectorSection title="Corner" persistKey="shot:corner">
+    <InspectorSection className="insp-object" title="Corner" persistKey="shot:corner">
+      {/* ONE diamond for FOUR paths: the control writes all four corners, so it
+          has one value and one keyframe gesture, and no expose pin (a pin
+          publishes one target, and one corner is not what this row edits).
+          See KeyframeDot. */}
       <InspectorRow>
         <NumberField
           value={radius.value ?? 0}
-          mixed={radius.mixed}
+          mixed={radius.mixed || cornersDiffer}
           label="Radius"
           ariaLabel="Corner radius"
           unit="px"
           min={0}
+          // No upper limit: a big enough radius is a pill shape.
           step={1}
-          onCommit={(next) =>
-            write((layer) => ({
-              ...layer,
-              paint:
-                next <= 0
-                  ? withoutRadius(layer.paint)
-                  : { ...layer.paint, radius: { tl: next, tr: next, br: next, bl: next } },
-            }))
-          }
+          trailing={<KeyframeDot path={RADIUS_PATHS} label="Radius" parts={RADIUS_PARTS} />}
+          onCommit={(next) => write((layer) => withRadius(layer, next))}
+          onScrubStart={scrub.start}
+          onScrub={scrub.move}
+          onScrubEnd={scrub.end}
         />
       </InspectorRow>
     </InspectorSection>
   );
 }
 
+/** 0 or less DELETES the key rather than storing a zero radius: absent already
+ *  means square corners, and codegen prints the block by key order. */
+function withRadius(layer: Layer3D, next: number): Layer3D {
+  return {
+    ...layer,
+    paint:
+      next <= 0
+        ? withoutRadius(layer.paint)
+        : { ...layer.paint, radius: { tl: next, tr: next, br: next, bl: next } },
+  } as Layer3D;
+}
+
 /** The largest corner, so a document with mixed corners reads as the shape the
  *  author sees rather than as zero. */
 function uniformOf(radius: CornerRadius | undefined): number {
@@ -46,7 +73,11 @@ function uniformOf(radius: CornerRadius | undefined): number {
   return Math.max(radius.tl, radius.tr, radius.br, radius.bl);
 }
 
-function withoutRadius(paint: { radius?: CornerRadius }): typeof paint {
+function isUniform(radius: CornerRadius | undefined): boolean {
+  return radius === undefined || (radius.tl === radius.tr && radius.tr === radius.br && radius.br === radius.bl);
+}
+
+function withoutRadius(paint: LayerPaint): LayerPaint {
   const { radius: _drop, ...rest } = paint;
   return rest;
 }

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

@@ -0,0 +1,315 @@
+// THE PROPS PLAYGROUND: a definition's published surface, LIVE.
+//
+// The ledger this replaces listed the props and let you rename or retire them,
+// which meant the one panel naming a component's controls was the one place
+// they could not be turned. An author had to place an instance to find out what
+// their own component's Colour prop did.
+//
+// So every row is now the control itself, and it is deliberately the SAME row
+// as the instance panel's: one `PropRow` over the control the prop's target
+// describes (`exposedRowOf`: a published 0..1 opacity is a bounded field, a
+// published enum keeps its options, a published text keeps its line breaks),
+// with one drag bracket per row. What differs is only the subject: there the
+// value belongs to a placement, here it belongs to the definition.
+//
+// ── WHAT A ROW READS, AND WHY IT IS NOT `prop.default` ──────────────────
+//
+// The interior layer is the RUNTIME truth: `applyOverrides` skips a prop no
+// instance overrides, so an un-overridden placement renders the layer's own
+// stored value. `prop.default` is a mirror, kept in step by `setExposedValue`
+// writing both halves in one transaction, and it drifts the moment the
+// published field is edited anywhere else (the layer's own section, a stage
+// drag, an agent's `update_layer`). This panel reads the layer, else what the
+// definition draws there (`exposedMasterValue`), so it can never show a number
+// the stage disagrees with.
+//
+// ── TRY FIRST, SAVE ON PURPOSE ──────────────────────────────────────────
+//
+// With "Apply to all instances" off (the default) a turn is only TRIED:
+// `playComponentProp` holds it and the stage draws it the way a placement's
+// overrides are drawn. The document is untouched until the box is ticked,
+// which saves what was tried in one undo step (`setComponentApplyAll`).
+//
+// THE HEAD'S RESET DROPS WHAT IS TRIED, and nothing else, so it is drawn
+// only while Apply is off. With Apply on, a turn writes the master itself:
+// nothing is ever tried, no row differs from the master, and undo takes a
+// turn back, so a Reset there could never be pressed. One there once put
+// each prop back to its published `default`, and that only ever did anything
+// where the default had drifted: it wrote the stale value back over the
+// author's later edit.
+//
+// ── ONE IMPLEMENTATION, TWO FACES ───────────────────────────────────────
+//
+// The inspector renders this for a definition on both faces (the Studio face
+// and the Layers face with nothing selected). A second copy would be two
+// widget vocabularies over one document field.
+import { IconClose, IconDots, InspectorSection, PropRow, useContextMenu, useLocked, usePrompt } from "@dailies-studio/ui";
+import type { PromptRequest, PropControlAsset } from "@dailies-studio/ui";
+import { controlLabel } from "@dailies-studio/contract";
+import { exposedMasterValue, readAtPath, setExposedValue } from "@dailies-studio/shot/doc";
+import type { ComponentDef3D, ExposedProp3D } from "@dailies-studio/shot/doc";
+import type { Value } from "@dailies-studio/engine";
+import { useMemo, useRef } from "react";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { ApplyAllToggle } from "../../studio/componentParts.js";
+import { coercePropValue, exposedRowOf, masterRowValue, projectAssetsOf, propEditOf, shownPropValue } from "../propValue.js";
+import { useScrub } from "../useDocWrite.js";
+
+export function DefinitionProps({ def }: { def: ComponentDef3D }) {
+  // ONE dialog for the whole section, not one per row: `usePrompt` mounts a
+  // `PromptDialog`, and a definition with a dozen props would otherwise mount a
+  // dozen of them to show at most one.
+  const { prompt, dialog } = usePrompt();
+  const store = useStore();
+  const viewer = useShotEditor((s) => s.readOnly);
+  const saving = useShotEditor((s) => s.componentApplyAll) && !viewer;
+  const tried = useShotEditor((s) => Object.keys(s.componentPlay).length);
+  const assetTable = useShotEditor((s) => s.doc?.assets);
+  const assets = useMemo(() => projectAssetsOf(assetTable), [assetTable]);
+  // RESET: drop every tried value. Only while Apply is off (see the header).
+  const reset = saving ? null : (
+    <button
+      type="button"
+      className="props-head-reset"
+      data-testid="definition-props-reset"
+      disabled={tried === 0}
+      title={tried === 0 ? "Nothing tried" : "Drop every tried value"}
+      onClick={(e) => {
+        e.stopPropagation();
+        store.resetComponentPlay();
+      }}
+    >
+      Reset
+    </button>
+  );
+  return (
+    <InspectorSection className="insp-object" title="Properties" persistKey="shot:definition-exposed" action={reset}>
+      {dialog}
+      {def.exposed.length === 0 ? null : <ApplyAllToggle disabled={viewer} disabledReason="View only" />}
+      {def.exposed.length === 0 ? (
+        // NAMES THE ONE WAY IN. An empty panel that only says it is empty is a
+        // dead end, and the affordance it points at is not on this face: the
+        // pin sits beside the keyframe diamond, inside a field box of the layer
+        // that owns the field, on the Layers face.
+        <p className="insp-empty">
+          Nothing published yet. Open the <strong>Edit</strong> tab, select a layer, and press the pin
+          inside any property&apos;s field to publish it. Every instance can then override it.
+        </p>
+      ) : (
+        def.exposed.map((prop) => (
+          <ExposedPropRow key={prop.key} def={def} prop={prop} prompt={prompt} saving={saving} assets={assets} />
+        ))
+      )}
+    </InspectorSection>
+  );
+}
+
+/**
+ * One published property: turn it, relabel it, retire it.
+ *
+ * A component and not inline JSX because the drag bracket is a HOOK and there
+ * is one gesture per prop. A colour picker's SV square, its hue bar, its alpha
+ * bar and a range field's slider route a drag ENTIRELY through `scrub.move`
+ * and never call `commit` while the pointer is down, so a row wired to the
+ * typed half alone has a control whose thumb moves and whose document does not.
+ */
+function ExposedPropRow({
+  def,
+  prop,
+  prompt,
+  saving,
+  assets,
+}: {
+  def: ComponentDef3D;
+  prop: ExposedProp3D;
+  prompt: (req: PromptRequest) => Promise<string | null>;
+  /** "Apply to all instances" is on: turns write the definition. Off = tried. */
+  saving: boolean;
+  assets: readonly PropControlAsset[];
+}) {
+  const store = useStore();
+  const materials = useShotEditor((s) => s.doc?.materials);
+  const contracts = useShotEditor((s) => s.contracts);
+  const tried = useShotEditor((s) => s.componentPlay[prop.key]);
+  // The row's verbs are plain buttons in its label column (PropRow's
+  // `actions`), so they take the panel's lock here: a read-only row's control
+  // is locked by the row itself, and its retire must stay live (it is how an
+  // orphan or an undescribed prop is fixed).
+  const locked = useLocked();
+  const menu = useContextMenu();
+  const defId = def.id;
+  const row = exposedRowOf(prop, def, materials, contracts);
+  const { spec } = row;
+  const label = controlLabel(spec);
+  const layer = def.layersById[prop.target.layer];
+  // What the row shows untried: the layer's own value (what an un-overridden
+  // placement renders, shown as it is stored, malformed or not), else what
+  // the definition draws there (`exposedMasterValue`: a derived value, a
+  // graph parameter's or a contract prop's default), never the published
+  // `default`, which drifts from the layer.
+  const live = layer === undefined ? undefined : (readAtPath(layer, prop.target.path) as Value | undefined);
+  const fallback = live ?? masterRowValue(spec, exposedMasterValue(def, prop, { materials, contracts }));
+
+  // Re-read from the document it is HANDED, never from a value closed over at
+  // render: every capture re-derives from the gesture's base, so a builder that
+  // remembered would re-apply the whole drag on top of itself per pointer event.
+  // A value the target cannot hold writes nothing.
+  const saveScrub = useScrub((next, raw) => {
+    const value = coercePropValue(spec, raw);
+    return value === null ? next : setExposedValue(next, defId, prop.key, value);
+  });
+  // TRYING: every move IS the edit, so a cancelled gesture puts back the
+  // value it started from.
+  const before = useRef<Value | undefined>(undefined);
+  const scrub = saving
+    ? saveScrub
+    : {
+        start: () => {
+          before.current = tried;
+        },
+        move: (raw: unknown) => {
+          const value = coercePropValue(spec, raw);
+          if (value !== null) store.playComponentProp(prop.key, value);
+        },
+        end: (commit: boolean) => {
+          if (!commit) store.playComponentProp(prop.key, before.current ?? null);
+        },
+      };
+  const commit = (raw: unknown): void => {
+    const edit = propEditOf(spec, raw, fallback);
+    if (edit.kind === "refused") {
+      store.reportError(edit.reason);
+      return;
+    }
+    // "No asset" over a value that is already none: drop what is tried, and
+    // the saved value (none) shows again.
+    if (edit.kind === "clear") {
+      if (!saving) store.playComponentProp(prop.key, null);
+      return;
+    }
+    if (saving) store.setExposedPropValue(defId, prop.key, edit.value);
+    else store.playComponentProp(prop.key, edit.value);
+  };
+
+  // THE ROW'S VERBS LIVE IN ITS LABEL COLUMN (PropRow's `actions`), as ONE
+  // "More" that opens Rename… and Stop publishing. A verb never changes the
+  // control's width, and it is drawn once per row: as a box's accessory it
+  // was drawn in every box of a vector, and two of them took a third-width
+  // box's prefix and unit at the default width and spilled past its edge at
+  // the 264px floor. In the label column a vector's three boxes keep their
+  // whole width for the value. Rename is a PROMPT rather than an inline field
+  // for the same reason the component's own name is: it is a rare edit, and a
+  // permanently mounted input costs a row its readability every time it is
+  // not being used.
+  const retire = (): void => store.deleteExposedProp(defId, prop.key);
+  const rename = (): void => {
+    void prompt({
+      title: "Rename property",
+      label: "Name",
+      initialValue: prop.label,
+      confirmLabel: "Rename",
+    }).then((next) => {
+      if (next !== null && next !== "") store.renameExposedProp(defId, prop.key, next);
+    });
+  };
+  const more = (
+    <button
+      type="button"
+      className="insp-key"
+      aria-label={`More for ${label}`}
+      aria-haspopup="menu"
+      aria-expanded={menu.menu !== null}
+      title="Rename or stop publishing"
+      disabled={locked}
+      onClick={(e) => {
+        const at = e.currentTarget.getBoundingClientRect();
+        menu.open({ x: at.left, y: at.bottom }, [
+          {
+            kind: "action",
+            id: "rename",
+            label: "Rename…",
+            title: "The key instances override by does not change",
+            onSelect: rename,
+          },
+          {
+            kind: "action",
+            id: "retire",
+            label: "Stop publishing",
+            danger: true,
+            title: "Instance overrides stay stored",
+            onSelect: retire,
+          },
+        ]);
+      }}
+    >
+      <IconDots />
+    </button>
+  );
+  // An orphan's one verb, pressed directly: there is nothing else to choose.
+  const remove = (
+    <button
+      type="button"
+      className="insp-key is-danger"
+      aria-label={`Stop publishing ${label}`}
+      title="Stop publishing: instance overrides stay stored"
+      disabled={locked}
+      onClick={retire}
+    >
+      <IconClose />
+    </button>
+  );
+  // The key is override identity, not a caption, so it rides the label's
+  // tooltip beside the target it writes rather than taking the line the
+  // author reads.
+  const where = `Key ${prop.key} · ${layer?.label ?? prop.target.layer} · ${prop.target.path}`;
+
+  if (layer === undefined) {
+    // AN ORPHAN, said plainly. `setExposedValue` and `applyOverrides` both skip
+    // a prop whose target is gone, so a live control here would be a widget
+    // that writes nothing, and the save gate names this prop anyway. The value
+    // it last held stays on screen, read-only, and retire is the only verb
+    // left, so it is the only one offered. Nothing can be tried on it, so
+    // its dot lane stays empty, but it is reserved: without it the label
+    // started 10px left of every live row's above and below it.
+    return (
+      <PropRow
+        spec={spec}
+        value={shownPropValue(spec, prop.default)}
+        commit={() => {}}
+        scrub={saveScrub}
+        readOnly
+        changed={false}
+        actions={remove}
+        description={where}
+        error="Its layer is gone, so nothing drives this any more."
+        assets={assets}
+        rowProps={{ "data-definition-prop": prop.key }}
+      />
+    );
+  }
+
+  return (
+    <>
+      <PropRow
+        spec={spec}
+        value={shownPropValue(spec, tried ?? fallback)}
+        commit={commit}
+        scrub={scrub}
+        // THE BLUE DOT: a value tried here, not saved.
+        changed={tried !== undefined}
+        changedLabel="Tried, not saved"
+        dotProps={{ "data-tried": prop.key }}
+        {...(row.undescribed ? { readOnly: true } : {})}
+        {...(row.opaqueColor ? { opaqueColor: true } : {})}
+        actions={more}
+        description={where}
+        assets={assets}
+        // A hook for the row, not a style: nothing restyles a published
+        // prop's row, which is the house PropRow.
+        rowProps={{ "data-definition-prop": prop.key }}
+      />
+      {/* The menu the row's More opens, once per row, beside it. */}
+      {menu.menu}
+    </>
+  );
+}

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

@@ -0,0 +1,136 @@
+// The open DEFINITION itself — the component context's control panel when
+// nothing inside it is selected (unify P2), and the Component Studio's whole
+// right rail. The def-level twin of SceneSection: what it publishes and how
+// big it is. The mo1 read: this is the module's own
+// property sheet.
+//
+// ── THE ORDER IS THE QUESTION AN AUTHOR ASKS ────────────────────────────
+//
+// Properties first, then the canvas. It used to run the other
+// way, which put the definition's WIDTH above the surface every instance of it
+// is driven through — right while the panel was a ledger nobody could turn, and
+// wrong the moment the props became live controls (`DefinitionProps`). The two
+// faces share this component, so the order is one decision rather than two.
+//
+// EXPOSED PROPS are created by the agent's `expose_prop` and by the chrome's
+// own pin (`inspector/ExposeDot.tsx`, inside a row's field box beside the
+// keyframe diamond, on the layers face). Everything after that is
+// `DefinitionProps`: the value, the label and the retire, all respecting the
+// key-is-identity rule (a rename never touches the key, a delete leaves stored
+// overrides quarantined in place).
+import { InspectorRow, InspectorSection, NumberField, TextField } from "@dailies-studio/ui";
+import type { ScrubHandlers } from "@dailies-studio/ui";
+import {
+  componentDefsOf,
+  defDurationFrames,
+  instancesOf,
+  setComponentDuration,
+  setComponentSize,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { useScrub } from "../useDocWrite.js";
+import { DefinitionProps } from "./DefinitionProps.js";
+
+/** A whole, positive number of pixels or frames, the floor these fields keep. */
+const whole = (n: number): number => Math.max(1, Math.round(n));
+
+/** One canvas side, written into the definition the drag is HANDED (a scrub
+ *  re-derives every move from its base), the other side kept as it is there. */
+function sizeWrite(defId: string, axis: 0 | 1): (doc: Doc3D, raw: unknown) => Doc3D {
+  return (doc, raw) => {
+    const def = componentDefsOf(doc)[defId];
+    if (def === undefined || typeof raw !== "number" || !Number.isFinite(raw)) return doc;
+    const size: [number, number] = [def.size[0], def.size[1]];
+    size[axis] = whole(raw);
+    return setComponentSize(doc, defId, size);
+  };
+}
+
+/** A NumberField's drag half, from the store's scrub trio. */
+function dragOf(scrub: ScrubHandlers): {
+  onScrubStart: () => void;
+  onScrub: (value: number) => void;
+  onScrubEnd: (commit: boolean) => void;
+} {
+  return { onScrubStart: scrub.start, onScrub: scrub.move, onScrubEnd: scrub.end };
+}
+
+export function DefinitionSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const def = editingDef === null ? undefined : doc?.components?.[editingDef];
+  const defId = def?.id ?? "";
+  // THE DRAG HALVES: a drag on W, H or Frames moves the definition while the
+  // pointer is down, one undo entry, instead of waiting for the release.
+  const width = useScrub(sizeWrite(defId, 0));
+  const height = useScrub(sizeWrite(defId, 1));
+  const frames = useScrub((next, raw) =>
+    typeof raw === "number" && Number.isFinite(raw) ? setComponentDuration(next, defId, whole(raw)) : next,
+  );
+  if (doc === null || def === undefined) return null;
+
+  const placed = instancesOf(doc, def.id).length;
+
+  return (
+    <>
+      <DefinitionProps key={def.id} def={def} />
+
+      <InspectorSection className="insp-object" title="Component" persistKey="shot:definition" collapsible={false}>
+        <InspectorRow label="Name">
+          <TextField
+            value={def.name}
+            ariaLabel="Component name"
+            onCommit={(name) => store.renameComponent(def.id, name)}
+          />
+        </InspectorRow>
+        {/* THE CANVAS, a W | H pair like the Transform section's: two field
+            boxes side by side, each named inside, rather than two fields
+            flattened into one labelled pill. */}
+        <InspectorRow>
+          <div className="insp-vec">
+            <NumberField
+              value={def.size[0]}
+              label="W"
+              ariaLabel="Component width"
+              unit="px"
+              min={1}
+              step={1}
+              onCommit={(w) => store.setComponentSize(def.id, [whole(w), def.size[1]])}
+              {...dragOf(width)}
+            />
+            <NumberField
+              value={def.size[1]}
+              label="H"
+              ariaLabel="Component height"
+              unit="px"
+              min={1}
+              step={1}
+              onCommit={(h) => store.setComponentSize(def.id, [def.size[0], whole(h)])}
+              {...dragOf(height)}
+            />
+          </div>
+        </InspectorRow>
+        <InspectorRow>
+          <NumberField
+            value={defDurationFrames(def)}
+            label="Frames"
+            ariaLabel="Component duration"
+            min={1}
+            step={1}
+            onCommit={(f) => store.setComponentDuration(def.id, Math.round(f))}
+            {...dragOf(frames)}
+          />
+        </InspectorRow>
+        <p className="insp-note">
+          {placed === 0
+            ? "Not placed yet. Use it in a shot or add it to the storyboard."
+            : placed === 1
+              ? "Placed once. Edits here reach it."
+              : `Placed ${placed} times. Edits here reach all of them.`}
+        </p>
+      </InspectorSection>
+    </>
+  );
+}