@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/material/MaterialNode.tsx

@@ -0,0 +1,453 @@
+// One compute card: its sockets, its inline widgets, and its thumbnail.
+//
+// ── THE WIDGETS ARE DERIVED, NOT DECLARED ───────────────────────────────
+//
+// A card's fields come from `spec.fields`, which the registry already keeps
+// because both signatures are computed from it. Nothing here adds a "widget"
+// entry to the spec, and that is deliberate: a second list would be a second
+// place for "does this kind carry a wrap?" to be answered, and the two would
+// drift the first time a kind grew a field. The registry says WHAT a node
+// carries; this file says how one of those is typed into.
+//
+// ── AND THEY COMMIT THROUGH THE STORE, NEVER THE DOCUMENT ───────────────
+//
+// `MaterialParameterControls.tsx`'s pattern, one level in. A typed value goes
+// through `setMaterialNodeValue` — the validated door, one undo entry. A DRAG
+// goes through `useScrub` over the exported pure `writeMaterialNodeValue`, so
+// sixty pointer moves are one history entry and one save rather than sixty.
+// Wiring only the commit half gives a field whose number moves and whose
+// document never changes.
+//
+// Every widget root carries `nodrag nowheel`, which are React Flow's own
+// opt-outs: without `nodrag` a pointer-down inside a field drags the CARD and
+// the field never sees the gesture, and without `nowheel` a scroll over a
+// number pans the canvas.
+import { createContext, memo, useContext } from "react";
+import type { ReactNode } from "react";
+import { Handle, Position, useConnection } from "@xyflow/react";
+import type { NodeProps } from "@xyflow/react";
+import { ColorPicker, Combobox, NumberField, TextField, Toggle } from "@dailies-studio/ui";
+import { MATERIAL_GRAPH_GENERATORS, MATERIAL_GRAPH_TEXTURE_WRAPS } from "@dailies-studio/shot/doc";
+import type {
+  Doc3D,
+  MaterialGraphEndpoint,
+  MaterialGraphNode,
+  MaterialGraphSocketSpec,
+  MaterialGraphValue,
+} from "@dailies-studio/shot/doc";
+import { useStore } from "../../state/context.js";
+import { writeMaterialNodeValue } from "../../state/store.js";
+import { useScrub } from "../inspector/useDocWrite.js";
+import { socketGlyphClass, socketTitle } from "./socketGlyph.js";
+import type { MaterialSocketDrop } from "./socketGlyph.js";
+import { NodePreview } from "./NodePreview.js";
+import type { MaterialFlowData, MaterialFlowNode } from "./flowModel.js";
+
+/**
+ * "May a wire from here land there?", as the canvas's memoised type index
+ * answers it.
+ *
+ * A CONTEXT rather than a prop, because the answer depends on the GRAPH and the
+ * question is asked by every handle: threading it through `data` would put a
+ * function into the memo key and re-render every card whenever the graph
+ * changed, which is exactly what `flowModel.ts` exists to stop. The value here
+ * changes on the same beat — once per graph — and only handles read it.
+ */
+const CanConnectContext = createContext<(source: MaterialGraphEndpoint, target: MaterialGraphEndpoint) => boolean>(
+  () => false,
+);
+
+export function MaterialConnectProvider({
+  canConnect,
+  children,
+}: {
+  canConnect: (source: MaterialGraphEndpoint, target: MaterialGraphEndpoint) => boolean;
+  children: ReactNode;
+}) {
+  return <CanConnectContext.Provider value={canConnect}>{children}</CanConnectContext.Provider>;
+}
+
+/**
+ * What a live drag says about ONE handle.
+ *
+ * `useConnection` is React Flow 12's own subscription to the in-flight
+ * connection, so a drag re-renders the handles and nothing else — the canvas
+ * itself never re-renders for a pointer move. The three answers are the three
+ * the design system allows: ringed in accent, dimmed, or exactly as it was.
+ */
+export function useSocketDrop(nodeId: string, socket: string, side: "source" | "target"): MaterialSocketDrop {
+  const canConnect = useContext(CanConnectContext);
+  const from = useConnection((connection) => (connection.inProgress ? connection.fromHandle : null));
+  // React Flow types a handle's id as optional, because a node may declare one
+  // unnamed handle. This lane never does — every socket is a named registry id
+  // — so an absent one is a handle this canvas did not draw.
+  const held = from === null || from.id == null ? null : { nodeId: from.nodeId, socket: from.id };
+  if (from === null || held === null) return "idle";
+  // A handle on the same side as the one in hand is not a candidate at all, and
+  // neither is anything on the node the drag started from. Dimming those would
+  // grey out most of the canvas for a gesture that was never aimed at them.
+  if (from.nodeId === nodeId) return "idle";
+  if (from.type === side) return "idle";
+  const wire =
+    side === "target"
+      ? { source: held, target: { nodeId, socket } }
+      : { source: { nodeId, socket }, target: held };
+  return canConnect(wire.source, wire.target) ? "ok" : "blocked";
+}
+
+function MaterialSocketHandle({
+  nodeId,
+  socket,
+  side,
+  connected,
+}: {
+  nodeId: string;
+  socket: MaterialGraphSocketSpec;
+  side: "source" | "target";
+  connected: boolean;
+}) {
+  const drop = useSocketDrop(nodeId, socket.id, side);
+  return (
+    <Handle
+      type={side}
+      position={side === "target" ? Position.Left : Position.Right}
+      id={socket.id}
+      className={socketGlyphClass(socket.type, { connected, drop })}
+      title={socketTitle(socket.label, socket.type)}
+    />
+  );
+}
+
+/** The card. `memo` is the second half of `flowModel.ts`'s bargain: the props
+ *  come back identical for an untouched node, and this is what turns that into
+ *  a skipped render. */
+export const MaterialNodeCard = memo(function MaterialNodeCard({ data }: NodeProps<MaterialFlowNode>) {
+  const { node, spec, inputs, outputs, connected, problem } = data;
+  return (
+    <article
+      className={`material-node material-node-${spec.category}${problem === null ? "" : " is-problem"}`}
+      aria-label={`${spec.label} shader node`}
+      data-node-kind={node.kind}
+      data-testid={`material-node-${node.id}`}
+    >
+      <header className="material-node-title">
+        <span>{spec.label}</span>
+        {data.outputType === null ? null : <small>{data.outputType}</small>}
+      </header>
+      {problem === null ? null : (
+        <p className="material-node-problem" role="status">
+          {problem}
+        </p>
+      )}
+      <MaterialNodeFields data={data} />
+      {node.preview === true ? <NodePreview nodeId={node.id} /> : null}
+      <div className="material-node-sockets">
+        <div className="material-node-inputs">
+          {inputs.map((socket) => (
+            <div className="material-socket-row is-input" key={socket.id}>
+              <MaterialSocketHandle
+                nodeId={node.id}
+                socket={socket}
+                side="target"
+                connected={connected.has(`in:${socket.id}`)}
+              />
+              <span>{socket.label}</span>
+            </div>
+          ))}
+        </div>
+        <div className="material-node-outputs">
+          {outputs.map((socket) => (
+            <div className="material-socket-row is-output" key={socket.id}>
+              <span>{socket.label}</span>
+              <MaterialSocketHandle
+                nodeId={node.id}
+                socket={socket}
+                side="source"
+                connected={connected.has(`out:${socket.id}`)}
+              />
+            </div>
+          ))}
+        </div>
+      </div>
+    </article>
+  );
+});
+
+/** Which literal kinds carry an editable `value`, and how wide it is. The four
+ *  vector widths are the only place a component count is spelled. */
+const VECTOR_WIDTH: Readonly<Record<string, 2 | 3 | 4>> = { vec2: 2, vec3: 3, vec4: 4 };
+const AXES = ["X", "Y", "Z", "W"] as const;
+
+/**
+ * The inline fields of one card, derived from `spec.fields`.
+ *
+ * Exported on its own because it is the half worth testing: it needs the store
+ * and nothing else, where the card around it needs a mounted React Flow.
+ */
+export function MaterialNodeFields({ data }: { data: MaterialFlowData }) {
+  const { spec, node } = data;
+  const rows: ReactNode[] = [];
+  for (const field of spec.fields) {
+    if (field === "value") rows.push(<ValueField key="value" data={data} />);
+    else if (field === "mask") rows.push(<MaskField key="mask" data={data} />);
+    else if (field === "wrap") rows.push(<WrapField key="wrap" data={data} />);
+    else if (field === "index") rows.push(<IndexField key="index" data={data} />);
+    else if (field === "assetId") rows.push(<AssetField key="assetId" data={data} />);
+    else if (field === "parameterId") rows.push(<ParameterField key="parameterId" data={data} />);
+    else if (field === "generator") rows.push(<GeneratorField key="generator" data={data} />);
+    // `functionId` and `socket` are deliberately absent: both are written by
+    // Collapse and Expand, which move a whole region at once, and a dropdown
+    // that re-pointed one call site at another function would leave its wires
+    // naming sockets that signature does not have.
+    //
+    // `generator` shares that shape and gets a widget anyway, because the two
+    // are not the same problem. A function boundary is authored elsewhere and
+    // this card merely calls it; a generator is not authored anywhere — picking
+    // one IS the node — and `setMaterialNodeValue` drops the wires the new
+    // parameter list no longer has a socket for as part of the same swap.
+  }
+  if (rows.length === 0) return null;
+  return (
+    <div className="material-node-fields nodrag nowheel" data-testid={`material-fields-${node.id}`}>
+      {rows}
+    </div>
+  );
+}
+
+/** The one commit seam every widget below uses. */
+function useCommit(data: MaterialFlowData) {
+  const store = useStore();
+  return (patch: Parameters<typeof store.setMaterialNodeValue>[3]): void =>
+    store.setMaterialNodeValue(data.materialId, data.path, data.node.id, patch);
+}
+
+/** …and the one DRAG seam. Narrow on purpose (see `writeMaterialNodeValue`'s
+ *  header): a scrub may change a literal and may never change the graph's
+ *  shape. */
+function useValueScrub(data: MaterialFlowData, build: (node: MaterialGraphNode, raw: unknown) => MaterialGraphValue | null) {
+  return useScrub((doc: Doc3D, raw: unknown) => {
+    const node = doc.materials?.[data.materialId]?.nodesById[data.node.id];
+    if (node === undefined) return doc;
+    const next = build(node, raw);
+    if (next === null) return doc;
+    return writeMaterialNodeValue(doc, data.materialId, data.path, data.node.id, next);
+  });
+}
+
+function ValueField({ data }: { data: MaterialFlowData }) {
+  const store = useStore();
+  const commit = useCommit(data);
+  const { node, spec } = data;
+  const width = VECTOR_WIDTH[node.kind];
+  const label = spec.label;
+
+  const scalarScrub = useValueScrub(data, (_node, raw) => (typeof raw === "number" ? raw : null));
+  const colorScrub = useValueScrub(data, (_node, raw) => (typeof raw === "string" ? raw : null));
+
+  /**
+   * One component of a vector, dragged.
+   *
+   * Built here rather than through `useScrub` because it is needed PER
+   * COMPONENT and a hook cannot be called from a loop. It is the same three
+   * store calls that hook returns, with the other components re-read from the
+   * base document at capture time so a drag on Y cannot flatten X.
+   */
+  const vectorScrub = (index: number, components: 2 | 3 | 4) => ({
+    start: (): void => store.beginScrub(),
+    move: (raw: unknown): void => {
+      if (typeof raw !== "number") return;
+      store.scrubCapture((doc: Doc3D) => {
+        const found = doc.materials?.[data.materialId]?.nodesById[node.id];
+        if (found === undefined) return doc;
+        return writeMaterialNodeValue(
+          doc,
+          data.materialId,
+          data.path,
+          node.id,
+          componentsOf(found.value, components, index, raw),
+        );
+      });
+    },
+    end: (ok: boolean): void => store.endScrub(ok),
+  });
+
+  if (node.kind === "color") {
+    return (
+      <div className="material-node-field is-color">
+        <ColorPicker
+          value={typeof node.value === "string" ? node.value : "#ffffff"}
+          ariaLabel={`${label} value`}
+          commit={(hex) => commit({ value: hex })}
+          scrub={colorScrub}
+        />
+      </div>
+    );
+  }
+  if (node.kind === "bool") {
+    return (
+      <div className="material-node-field">
+        <Toggle
+          checked={node.value === true}
+          ariaLabel={`${label} value`}
+          onChange={(checked) => commit({ value: checked })}
+        />
+      </div>
+    );
+  }
+  if (width !== undefined) {
+    const vector = Array.isArray(node.value) ? node.value : [];
+    return (
+      <div className="material-node-field is-vector">
+        {Array.from({ length: width }, (_unused, index) => {
+          const scrub = vectorScrub(index, width);
+          return (
+            <NumberField
+              key={index}
+              value={typeof vector[index] === "number" ? vector[index]! : 0}
+              ariaLabel={`${label} ${AXES[index]}`}
+              label={AXES[index]}
+              step={0.01}
+              onCommit={(next) => commit({ value: componentsOf(node.value, width, index, next) })}
+              onScrubStart={scrub.start}
+              onScrub={scrub.move}
+              onScrubEnd={scrub.end}
+            />
+          );
+        })}
+      </div>
+    );
+  }
+  // float and int. An integer's quantum is 1, which is also what makes the
+  // field print it without a decimal point.
+  const step = node.kind === "int" ? 1 : 0.01;
+  return (
+    <div className="material-node-field">
+      <NumberField
+        value={typeof node.value === "number" ? node.value : 0}
+        ariaLabel={`${label} value`}
+        step={step}
+        onCommit={(next) => commit({ value: node.kind === "int" ? Math.round(next) : next })}
+        onScrubStart={scalarScrub.start}
+        onScrub={scalarScrub.move}
+        onScrubEnd={scalarScrub.end}
+      />
+    </div>
+  );
+}
+
+/** A vector with one component replaced, padded to width. */
+function componentsOf(
+  value: MaterialGraphValue | undefined,
+  width: 2 | 3 | 4,
+  index: number,
+  next: number,
+): MaterialGraphValue {
+  const current = Array.isArray(value) ? value : [];
+  const out = Array.from({ length: width }, (_unused, at) =>
+    at === index ? next : typeof current[at] === "number" ? current[at]! : 0,
+  );
+  return out as unknown as MaterialGraphValue;
+}
+
+function MaskField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <TextField
+        value={data.node.mask ?? "xyz"}
+        ariaLabel="Swizzle mask"
+        // REFUSED SILENTLY rather than written and reported. A mask is four
+        // characters and the field shows what it has; typing "q" and watching
+        // it snap back says more than a sentence in the overlay strip would,
+        // and the validator's refusal for a bad mask is about a document that
+        // should never have been written.
+        onCommit={(text) => {
+          const mask = text.trim().toLowerCase();
+          if (/^[xyzw]{1,4}$/.test(mask)) commit({ mask });
+        }}
+      />
+    </div>
+  );
+}
+
+function WrapField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <Combobox
+        value={data.node.wrap ?? "clamp"}
+        ariaLabel="Texture wrap"
+        options={MATERIAL_GRAPH_TEXTURE_WRAPS.map((wrap) => ({ value: wrap, label: wrap }))}
+        onChange={(wrap) => commit({ wrap: wrap as (typeof MATERIAL_GRAPH_TEXTURE_WRAPS)[number] })}
+      />
+    </div>
+  );
+}
+
+function IndexField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <NumberField
+        value={data.node.index ?? 0}
+        ariaLabel="Set index"
+        min={0}
+        max={3}
+        step={1}
+        onCommit={(next) => commit({ index: Math.round(next) })}
+      />
+    </div>
+  );
+}
+
+function AssetField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <Combobox
+        value={data.node.assetId ?? ""}
+        ariaLabel="Texture image"
+        placeholder="Choose image"
+        options={[...data.choices.images]}
+        onChange={(assetId) => commit({ assetId })}
+      />
+    </div>
+  );
+}
+
+/** Every material in the library, by the name an author reads. Module-level and
+ *  sorted once: the table ships with the build and cannot change at runtime, so
+ *  rebuilding it per card would be forty allocations for a constant. */
+const GENERATOR_OPTIONS = Object.entries(MATERIAL_GRAPH_GENERATORS)
+  .map(([value, entry]) => ({ value, label: entry.label }))
+  .sort((a, b) => a.label.localeCompare(b.label));
+
+function GeneratorField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <Combobox
+        value={data.node.generator ?? ""}
+        ariaLabel="Procedural material"
+        placeholder="Choose material"
+        options={GENERATOR_OPTIONS}
+        onChange={(generator) => commit({ generator })}
+      />
+    </div>
+  );
+}
+
+function ParameterField({ data }: { data: MaterialFlowData }) {
+  const commit = useCommit(data);
+  return (
+    <div className="material-node-field">
+      <Combobox
+        value={data.node.parameterId ?? ""}
+        ariaLabel="Exposed control"
+        placeholder="Choose control"
+        options={[...data.choices.parameters]}
+        onChange={(parameterId) => commit({ parameterId })}
+      />
+    </div>
+  );
+}