@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/material/MaterialParameterControls.tsx

@@ -0,0 +1,525 @@
+// A REUSABLE GRAPH'S EXPOSED CONTROLS, in the Material section of the mesh
+// that wears it (MaterialSection.tsx): first the controls themselves, each a
+// card editing its definition on the graph, then the per-mesh rows, which edit
+// THIS mesh's value and keyframes.
+//
+// Both are `PropRow`s, the one row every ControlSpec surface renders, so a
+// float with a range is the range field, a colour is the colour field, and a
+// vector's axes are named boxes, exactly as a component's props are. Listed in
+// the graph's own order (its declaration), never alphabetically, the rule
+// every ControlSpec list follows.
+import { useEffect, useMemo, useRef, useState } from "react";
+import { IconClose, PropRow, useLocked } from "@dailies-studio/ui";
+import type { PropRowReset, ScrubHandlers } from "@dailies-studio/ui";
+import type { ControlSpec } from "@dailies-studio/contract";
+import { valueEquals, type Value } from "@dailies-studio/engine";
+import {
+  containerFrame,
+  homeOf,
+  isGraphMaterial,
+  isMaterialGraphValueForType,
+  materialBindingForSlot,
+  materialGraphParamPath,
+  materialGraphParameterValue,
+  resolveTracksAt,
+} from "@dailies-studio/shot/doc";
+import type {
+  MaterialGraph3D,
+  MaterialGraphParameter,
+  MaterialGraphValue,
+} from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { writeMeshGraphOverride } from "../../state/store.js";
+import { useExposeOffered } from "../inspector/ExposeDot.js";
+import { KeyframeDot } from "../inspector/KeyframeDot.js";
+import { isVectorSpec } from "../inspector/propValue.js";
+import { useScrub } from "../inspector/useDocWrite.js";
+import {
+  clampParameterValues,
+  valuesOutsideRange,
+  withParameterRange,
+  writeParameterDefault,
+} from "./parameterValues.js";
+import type { ParameterRange } from "./parameterValues.js";
+
+export function MaterialParameterControls({
+  graph,
+  containerId,
+  layerId,
+  slot,
+}: {
+  graph: MaterialGraph3D;
+  containerId: string;
+  layerId: string;
+  /** The binding slot `graph` is bound on (`governingMaterialSlot`): a
+   *  submesh with its own graph, or null for the whole model. Values, keys and
+   *  writes all address that binding. */
+  slot: number | null;
+}) {
+  const parameters = Object.values(graph.parameters);
+  if (parameters.length === 0) {
+    return <p className="material-empty-copy">No exposed controls yet. Add one to animate a graph value per mesh.</p>;
+  }
+  return (
+    <div className="material-parameter-list">
+      {parameters.map((parameter) => (
+        <MaterialParameterRow
+          key={parameter.id}
+          graph={graph}
+          parameter={parameter}
+          containerId={containerId}
+          layerId={layerId}
+          slot={slot}
+        />
+      ))}
+    </div>
+  );
+}
+
+/** Definition-side lifecycle. These values belong to the reusable graph;
+ * MaterialParameterControls above edits this mesh's binding and keyframes. */
+export function MaterialParameterDefinitions({ graph }: { graph: MaterialGraph3D }) {
+  const parameters = Object.values(graph.parameters);
+  if (parameters.length === 0) return null;
+  return (
+    <div className="material-parameter-definitions">
+      {parameters.map((parameter) => (
+        <ParameterDefinition key={parameter.id} graph={graph} parameter={parameter} />
+      ))}
+    </div>
+  );
+}
+
+/** A float parameter's range, as `ParameterRange` reads it. */
+function rangeOf(parameter: MaterialGraphParameter): ParameterRange {
+  return {
+    ...(parameter.min === undefined ? {} : { min: parameter.min }),
+    ...(parameter.max === undefined ? {} : { max: parameter.max }),
+  };
+}
+
+/** A range in words, for the clamp offer: "0 to 1", "at least 0". */
+function rangeWords(range: ParameterRange): string {
+  if (range.min !== undefined && range.max !== undefined) return `${range.min} to ${range.max}`;
+  return range.min !== undefined ? `at least ${range.min}` : `at most ${range.max ?? 0}`;
+}
+
+/** A number field's spec for one of the definition's own numbers (a bound, the
+ *  step): always a plain field, never a slider, since these numbers have no
+ *  scale of their own. */
+function fieldSpec(key: string, label: string, limits: ParameterRange, step: number): ControlSpec {
+  return {
+    key,
+    propName: key,
+    label,
+    kind: "number",
+    animatable: false,
+    as: "field",
+    default: Number.NaN,
+    step,
+    ...limits,
+  } as ControlSpec;
+}
+
+/**
+ * A DRAG ON A NUMBER WITH NO PICTURE TO PREVIEW (a bound, the step): the field
+ * shows the dragged value live, and the release commits it ONCE, through the
+ * same commit a typed value takes, so a bound dragged past a mesh's value
+ * still asks the clamp question rather than writing into a refusal. A row's
+ * field always routes its drag through its scrub halves, so without these a
+ * drag would move nothing at all.
+ */
+function useReleaseDrag(commit: (value: number) => void): { scrub: ScrubHandlers; live: number | null } {
+  const [live, setLive] = useState<number | null>(null);
+  const last = useRef<number | null>(null);
+  const latest = useRef(commit);
+  latest.current = commit;
+  return {
+    live,
+    scrub: {
+      start: () => {
+        last.current = null;
+      },
+      move: (raw) => {
+        if (typeof raw !== "number" || !Number.isFinite(raw)) return;
+        last.current = raw;
+        setLive(raw);
+      },
+      end: (keep) => {
+        const value = last.current;
+        last.current = null;
+        setLive(null);
+        if (keep && value !== null) latest.current(value);
+      },
+    },
+  };
+}
+
+/**
+ * ONE CONTROL'S DEFINITION: its label, its default, and for a float its range
+ * and step, in a card under the parameter's name.
+ *
+ * ── A RANGE THAT TELLS THE TRUTH ────────────────────────────────────────
+ *
+ * An absent bound shows EMPTY (the field's dash), never a 0 or a 1 the graph
+ * does not hold, and a set one carries a Clear in its box that opens it
+ * again. Minimum is held under Maximum and Maximum over Minimum by their own
+ * limits, so the pair cannot cross. A new bound moves the default inside it in
+ * the same step (the graph refuses a default outside its range), and when a
+ * mesh already holds a value or a keyframe outside it, the bound is not
+ * written blind into a refusal: the card says how many and offers to clamp
+ * them with it, in one undo step, or to keep the range as it was.
+ */
+function ParameterDefinition({ graph, parameter }: { graph: MaterialGraph3D; parameter: MaterialGraphParameter }) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  // The card's own buttons write, so a viewer's locked panel disables them
+  // with every field in it.
+  const locked = useLocked();
+  const [pending, setPending] = useState<{ range: ParameterRange; count: number } | null>(null);
+  const float = parameter.type === "float";
+  const range = rangeOf(parameter);
+  const name = parameter.label;
+  // An offer is about the range it was asked against: once the bounds move
+  // under it (an undo, another tab), it is a question nobody is asking.
+  useEffect(() => setPending(null), [parameter.min, parameter.max]);
+
+  const patch = (
+    change: (found: MaterialGraphParameter) => MaterialGraphParameter,
+    alsoDoc?: Parameters<typeof store.updateProjectMaterial>[2],
+  ): void => {
+    store.updateProjectMaterial(
+      graph.id,
+      (current) => {
+        const found = current.parameters[parameter.id];
+        if (found === undefined) return current;
+        const next = change(found);
+        return next === found ? current : { ...current, parameters: { ...current.parameters, [parameter.id]: next } };
+      },
+      alsoDoc,
+    );
+  };
+
+  const applyRange = (next: ParameterRange, clamp: boolean): void => {
+    setPending(null);
+    patch(
+      (found) => withParameterRange(found, next),
+      clamp ? (d) => clampParameterValues(d, graph.id, parameter.id, next) : undefined,
+    );
+  };
+  const setBound = (which: "min" | "max", value: number | null): void => {
+    const next: ParameterRange = { ...range };
+    if (value === null) delete next[which];
+    else next[which] = value;
+    // Opening a bound leaves every value inside; narrowing one may not.
+    const outside = value === null || doc === null ? 0 : valuesOutsideRange(doc, graph.id, parameter.id, next);
+    if (outside > 0) setPending({ range: next, count: outside });
+    else applyRange(next, false);
+  };
+
+  // A drag on the default moves the graph's default while the pointer is down,
+  // one undo entry, through the narrow write a scrub may make. The bounds and
+  // the step commit on release (`useReleaseDrag`): they change no picture to
+  // preview, and a new bound has the clamp question to ask first.
+  const defaultScrub = useScrub((next, raw) => writeParameterDefault(next, graph.id, parameter.id, raw));
+  const defaultSpec = useMemo(() => controlSpec(parameter), [parameter]);
+  const setStep = (raw: unknown): void => {
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+      patch((found) => (found.step === raw ? found : { ...found, step: raw }));
+    }
+  };
+  const minDrag = useReleaseDrag((value) => setBound("min", value));
+  const maxDrag = useReleaseDrag((value) => setBound("max", value));
+  const stepDrag = useReleaseDrag(setStep);
+
+  // A CLEAR GOES WITH THE NUMBER IT CLEARS, so it unmounts under the press,
+  // and the focus fell to <body>: no ring, nothing announced, and the next
+  // keys went to the window's keymap. It hands the focus to the field it sat
+  // in, which stays, as a PropRow's reset does.
+  const clear = (words: string, title: string, run: () => void) => (
+    <button
+      type="button"
+      className="insp-key"
+      aria-label={`Clear ${name} ${words}`}
+      title={title}
+      disabled={locked}
+      onClick={(e) => {
+        const field = e.currentTarget.closest(".numfield")?.querySelector<HTMLElement>(".numfield-input");
+        run();
+        field?.focus();
+      }}
+    >
+      <IconClose />
+    </button>
+  );
+  const clearStep = (): void =>
+    patch((found) => {
+      if (found.step === undefined) return found;
+      const { step: _step, ...rest } = found;
+      return rest;
+    });
+  // The label is typed, never dragged.
+  const noScrub: ScrubHandlers = { start: () => {}, move: () => {}, end: () => {} };
+  // A field's accessible name starts with the words its row shows ("Minimum,
+  // Roughness"), the house rule, so speech input can say what it sees, and the
+  // control's name tells the cards apart.
+  const named = (words: string): string => `${words}, ${name}`;
+
+  return (
+    <details className="material-parameter-definition">
+      <summary>
+        <span>{parameter.label}</span>
+        <small>{parameter.type}</small>
+      </summary>
+      <div className="material-parameter-definition-body">
+        <PropRow
+          spec={{ key: "label", propName: "label", label: "Label", kind: "string", animatable: false, default: "" } as ControlSpec}
+          value={parameter.label}
+          name={named("Label")}
+          commit={(raw) => {
+            if (typeof raw === "string") patch((found) => (found.label === raw.trim() ? found : { ...found, label: raw.trim() }));
+          }}
+          scrub={noScrub}
+        />
+        <PropRow
+          spec={defaultSpec}
+          label="Default"
+          name={named("Default")}
+          value={parameter.default}
+          // Graph colours are `#rrggbb`: the picker offers no alpha.
+          {...(parameter.type === "color" ? { opaqueColor: true } : {})}
+          commit={(raw) => {
+            if (isMaterialGraphValueForType(raw, parameter.type)) {
+              patch((found) => (valueEquals(found.default as Value, raw as Value) ? found : { ...found, default: raw }));
+            }
+          }}
+          scrub={defaultScrub}
+        />
+        {float ? (
+          <>
+            <PropRow
+              spec={fieldSpec("min", "Minimum", parameter.max === undefined ? {} : { max: parameter.max }, parameter.step ?? 0.01)}
+              name={named("Minimum")}
+              value={minDrag.live ?? parameter.min ?? Number.NaN}
+              commit={(raw) => {
+                if (typeof raw === "number" && Number.isFinite(raw)) setBound("min", raw);
+              }}
+              scrub={minDrag.scrub}
+              {...(parameter.min === undefined
+                ? {}
+                : { trailing: clear("minimum", "Clear the minimum: the control is open below", () => setBound("min", null)) })}
+            />
+            <PropRow
+              spec={fieldSpec("max", "Maximum", parameter.min === undefined ? {} : { min: parameter.min }, parameter.step ?? 0.01)}
+              name={named("Maximum")}
+              value={maxDrag.live ?? parameter.max ?? Number.NaN}
+              commit={(raw) => {
+                if (typeof raw === "number" && Number.isFinite(raw)) setBound("max", raw);
+              }}
+              scrub={maxDrag.scrub}
+              {...(parameter.max === undefined
+                ? {}
+                : { trailing: clear("maximum", "Clear the maximum: the control is open above", () => setBound("max", null)) })}
+            />
+            {pending === null ? null : (
+              <div className="insp-notice is-warn" role="status" data-testid="material-parameter-clamp">
+                <span>
+                  {pending.count === 1
+                    ? `A mesh holds a value outside ${rangeWords(pending.range)}.`
+                    : `Meshes hold ${pending.count} values outside ${rangeWords(pending.range)}.`}
+                </span>
+                {/* The two answers on the house row of buttons: 28px house
+                    buttons, 6px apart, sharing the row by their words. */}
+                <div className="insp-buttons material-parameter-clamp-actions">
+                  <button
+                    type="button"
+                    className="btn"
+                    data-testid="material-parameter-clamp-apply"
+                    disabled={locked}
+                    title="Set the range and move those values to its nearest end, in one undo step"
+                    onClick={() => applyRange(pending.range, true)}
+                  >
+                    Clamp them
+                  </button>
+                  <button
+                    type="button"
+                    className="btn"
+                    data-testid="material-parameter-clamp-cancel"
+                    onClick={() => setPending(null)}
+                  >
+                    Keep the range
+                  </button>
+                </div>
+              </div>
+            )}
+            <PropRow
+              spec={fieldSpec("step", "Step", { min: 0.0001 }, 0.01)}
+              name={named("Step")}
+              value={stepDrag.live ?? parameter.step ?? Number.NaN}
+              commit={setStep}
+              scrub={stepDrag.scrub}
+              {...(parameter.step === undefined
+                ? {}
+                : { trailing: clear("step", "Clear the step: the field moves by its range's own quantum", clearStep) })}
+            />
+          </>
+        ) : null}
+        <div className="insp-buttons material-delete-parameter">
+          <button
+            type="button"
+            className="btn is-danger"
+            disabled={locked}
+            onClick={() => store.deleteProjectMaterialParameter(graph.id, parameter.id)}
+          >
+            Delete control
+          </button>
+        </div>
+      </div>
+    </details>
+  );
+}
+
+/**
+ * One control's value ON THIS MESH: the row, its diamond, its reset.
+ *
+ * The value shown is the binding's AT THE FRAME (an animated control shows its
+ * sampled value); whether the mesh stores a value of its own, and whether a
+ * track drives it, are read off the AUTHORED binding.
+ */
+function MaterialParameterRow({
+  graph,
+  parameter,
+  containerId,
+  layerId,
+  slot,
+}: {
+  graph: MaterialGraph3D;
+  parameter: MaterialGraphParameter;
+  containerId: string;
+  layerId: string;
+  slot: number | null;
+}) {
+  const store = useStore();
+  const doc = useShotEditor((state) => state.doc);
+  const frame = useShotEditor((state) => state.frame);
+  const defFrame = useShotEditor((state) => state.defFrame);
+  const editingDef = useShotEditor((state) => state.editingDef);
+  const layer = doc === null ? undefined : homeOf(doc, containerId)?.layersById[layerId];
+  const localFrame =
+    doc === null ? 0 : containerFrame(doc, containerId, editingDef === containerId ? defFrame : frame);
+  const effective =
+    doc === null || layer === undefined ? undefined : resolveTracksAt(layer, localFrame, doc.fps);
+  const binding = effective?.kind === "mesh" && isGraphMaterial(effective.mesh.material)
+    ? materialBindingForSlot(effective.mesh.material, slot)
+    : undefined;
+  const value = materialGraphParameterValue(graph, binding?.overrides, parameter.id) ?? parameter.default;
+  const authored =
+    layer?.kind === "mesh" && isGraphMaterial(layer.mesh.material)
+      ? materialBindingForSlot(layer.mesh.material, slot)
+      : undefined;
+  const override = authored?.overrides?.[parameter.id];
+  const path = materialGraphParamPath(parameter.id, slot);
+  const tracked = layer?.tracks?.[path] !== undefined;
+  const spec = controlSpec(parameter);
+  const vector = isVectorSpec(spec);
+  // The column draws a slot for whatever it is handed, even a pin that
+  // renders nothing, so the row asks before it hands one over.
+  const pinOffered = useExposeOffered(path);
+  const scrub = useScrub((base, raw) => {
+    const current = store.getState();
+    const next = graphValue(raw, parameter);
+    if (next === null) return base;
+    return writeMeshGraphOverride(
+      base,
+      containerId,
+      layerId,
+      parameter.id,
+      next,
+      containerFrame(base, containerId, current.editingDef === containerId ? current.defFrame : current.frame),
+      slot,
+    );
+  });
+
+  // THE RESET, in the label column, so the box and its diamond never move
+  // when it appears. Shown while this mesh holds a value of its own or a track
+  // drives the control, the rule a component's rows follow (InstanceSection,
+  // THIS USE): drawn on every row, it took a 16px lane and a gap from every
+  // untouched mesh's name, which then read "Roughn…" at the default width.
+  // Under a track it is refused with the way out: a reset would take the
+  // keyframes with it (clearing a tracked value reads to the router as
+  // "remove its animation").
+  const reset: PropRowReset | undefined =
+    override === undefined && !tracked
+      ? undefined
+      : {
+          onReset: () => store.setMeshGraphOverride(layerId, parameter.id, null, slot),
+          title: "Use the material's default on this mesh",
+          ...(tracked
+            ? {
+                refused: `${parameter.label} is animated on this mesh: its keyframes drive it. Remove them on the timeline to use the material's default.`,
+              }
+            : {}),
+        };
+
+  return (
+    <PropRow
+      spec={spec}
+      value={value}
+      commit={(raw) => {
+        const next = graphValue(raw, parameter);
+        if (next !== null) store.setMeshGraphOverride(layerId, parameter.id, next, slot);
+      }}
+      scrub={scrub}
+      // Every box of a vec2 or vec3 parameter carries its one track's
+      // diamond, naming the axes that key together. Its one expose pin sits
+      // in the label column instead, once per row (KeyframeDot's header):
+      // beside the first box's diamond it overflowed that third of the row.
+      // A one-box parameter keeps both in its box.
+      trailing={({ axes }) => <KeyframeDot path={path} label={parameter.label} pin={!vector} parts={axes} />}
+      {...(vector && pinOffered ? { actions: <KeyframeDot path={path} label={parameter.label} diamond={false} /> } : {})}
+      {...(reset === undefined ? {} : { reset })}
+      // THE BLUE DOT: this mesh holds its own value, not the material's.
+      changed={override !== undefined && !valueEquals(override as Value, parameter.default as Value)}
+      changedLabel="Changed on this mesh"
+      inherited={override === undefined && !tracked}
+      // A graph colour is `#rrggbb` (`isMaterialGraphValueForType`): the
+      // picker offers no alpha, so a drag cannot write a value it refuses.
+      {...(parameter.type === "color" ? { opaqueColor: true } : {})}
+      description={`Material parameter ${parameter.id}`}
+      rowProps={{ "data-material-parameter": parameter.id }}
+    />
+  );
+}
+
+function controlSpec(parameter: MaterialGraphParameter): ControlSpec {
+  const base = {
+    key: parameter.id,
+    propName: parameter.id,
+    label: parameter.label,
+    animatable: true as const,
+  };
+  if (parameter.type === "float") {
+    return {
+      ...base,
+      kind: "number",
+      default: parameter.default as number,
+      ...(parameter.min === undefined ? {} : { min: parameter.min }),
+      ...(parameter.max === undefined ? {} : { max: parameter.max }),
+      ...(parameter.step === undefined ? {} : { step: parameter.step }),
+    };
+  }
+  if (parameter.type === "color") return { ...base, kind: "color", default: parameter.default as string };
+  if (parameter.type === "vec2") {
+    return { ...base, kind: "vec2", default: parameter.default as [number, number], step: parameter.step ?? 0.01 };
+  }
+  return {
+    ...base,
+    kind: "vec3",
+    default: parameter.default as [number, number, number],
+    step: parameter.step ?? 0.01,
+  };
+}
+
+function graphValue(raw: unknown, parameter: MaterialGraphParameter): MaterialGraphValue | null {
+  return isMaterialGraphValueForType(raw, parameter.type) ? raw : null;
+}

package/src/panels/material/MaterialRerouteNode.tsx

@@ -0,0 +1,42 @@
+// A wire's elbow: one dot, one input, one output.
+//
+// The registry types it `passthrough`, so it is genuinely transparent — the
+// compiler emits the upstream expression and the dot costs nothing. It exists
+// because a graph with a wire crossing the whole canvas is a graph nobody can
+// read, and dragging a card sideways to fix that changes the layout of the
+// thing rather than the route of the wire.
+//
+// Drawn small on purpose. It is punctuation, not a card, and giving it a title
+// bar would make an author look for a value in it.
+import { memo } from "react";
+import { Handle, Position } from "@xyflow/react";
+import type { NodeProps } from "@xyflow/react";
+import { socketGlyphClass, socketTitle } from "./socketGlyph.js";
+import { useSocketDrop } from "./MaterialNode.js";
+import type { MaterialFlowNode } from "./flowModel.js";
+
+export const MaterialRerouteNode = memo(function MaterialRerouteNode({ data }: NodeProps<MaterialFlowNode>) {
+  const { node, connected, outputType } = data;
+  // The dot wears the type it is CARRYING once one is resolved, so a chain of
+  // reroutes still says what is flowing through it. Unresolved (nothing wired
+  // in yet) falls back to the generic dashed circle its spec declares.
+  const type = outputType === null || outputType === "texture" ? "numeric" : outputType;
+  const inDrop = useSocketDrop(node.id, "value", "target");
+  const outDrop = useSocketDrop(node.id, "value", "source");
+  return (
+    <div className="material-reroute" data-testid={`material-node-${node.id}`} title={socketTitle("Reroute", type)}>
+      <Handle
+        type="target"
+        position={Position.Left}
+        id="value"
+        className={socketGlyphClass(type, { connected: connected.has("in:value"), drop: inDrop })}
+      />
+      <Handle
+        type="source"
+        position={Position.Right}
+        id="value"
+        className={socketGlyphClass(type, { connected: connected.has("out:value"), drop: outDrop })}
+      />
+    </div>
+  );
+});