@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/material/MaterialNodePalette.tsx

@@ -0,0 +1,349 @@
+// The Add-node list, at the cursor.
+//
+// ── WHY IT MOVED OFF THE TOOLBAR ────────────────────────────────────────
+//
+// v1 pinned it under a button in the canvas's top-left corner. Every node
+// therefore arrived in the top-left corner too, and the author's next gesture
+// was always the same: drag it to where they had been looking. A palette that
+// opens where the pointer is, and drops the node there, removes that gesture
+// entirely — which is why every node editor an author has used works this way.
+// The bar's Add node button came back as the DISCOVERABLE opener only: it asks
+// with no point, like Tab, so its node lands in the middle, not the corner.
+//
+// ── THE FOUR OPENERS, AND WHY THE WIRE DROP IS THE IMPORTANT ONE ────────
+//
+//   Tab / ⇧A / the bar's Add node — the keymap's `graphPalette` or
+//     `openMaterialPalette(null)`, with no point, so the node lands wherever
+//     the canvas considers the middle.
+//   Double-click on empty pane — the point is the pointer.
+//   A WIRE DROPPED IN EMPTY SPACE — the point is where it was let go, and the
+//     palette is FILTERED to the kinds that could actually take that wire, then
+//     auto-wires the one that is picked (`addMaterialNode`'s `from`).
+//
+// The wire drop is the one that makes a graph fast to build: "I want something that
+// eats this vec3" is the question an author actually has, and answering it by
+// listing 114 kinds and letting them find out by being refused is the failure
+// this filter removes.
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  MATERIAL_GRAPH_GENERATORS,
+  MATERIAL_GRAPH_NODE_SPECS,
+  socketAccepts,
+} from "@dailies-studio/shot/doc";
+import type {
+  MaterialGraphNodeCategory,
+  MaterialGraphNodeKind,
+  MaterialGraphNodeSpec,
+  MaterialGraphResolvedType,
+  MaterialGraphSocketSpec,
+} from "@dailies-studio/shot/doc";
+import { useStore } from "../../state/context.js";
+import type { MaterialPaletteRequest, MaterialPaletteSource } from "../../state/types.js";
+
+/** Shelf order. A category this build does not know cannot exist (the union is
+ *  closed), so this is a total ordering rather than a preference with a
+ *  fallback — but the sort still appends an unlisted one rather than dropping
+ *  it, because a vanished node is a worse bug than a misplaced shelf. */
+const CATEGORY_ORDER: readonly MaterialGraphNodeCategory[] = [
+  "input",
+  "source",
+  "geometry",
+  "uv",
+  "math",
+  "vector",
+  "construct",
+  "logic",
+  "color",
+  "noise",
+  "generator",
+  "texture",
+  "function",
+  "editor",
+  "output",
+];
+
+const CATEGORY_LABELS: Record<MaterialGraphNodeCategory, string> = {
+  source: "Surface",
+  input: "Input",
+  geometry: "Geometry",
+  math: "Math",
+  vector: "Vector",
+  construct: "Construct",
+  logic: "Logic",
+  color: "Colour",
+  noise: "Noise",
+  generator: "Materials",
+  uv: "UV",
+  texture: "Texture",
+  function: "Function",
+  editor: "Editor",
+  output: "Output",
+};
+
+/**
+ * The kinds a palette may ever offer.
+ *
+ * The output node is excluded because a graph has exactly one and already has
+ * it. The three FUNCTION kinds are excluded because each is half of a boundary
+ * that Collapse and Expand create together — one added on its own is a card
+ * whose sockets name a signature nothing declared. `group` is excluded because
+ * a box with nothing in it is not a thing an author wants; Group acts on a
+ * selection. Every one of those is also refused by `addMaterialNode`, so this
+ * is the menu agreeing with the door rather than a second rule.
+ */
+const HIDDEN: ReadonlySet<MaterialGraphNodeKind> = new Set<MaterialGraphNodeKind>([
+  "subgraph",
+  "fn-input",
+  "fn-output",
+  "group",
+]);
+
+export interface MaterialPaletteRow {
+  kind: MaterialGraphNodeKind;
+  label: string;
+  category: MaterialGraphNodeCategory;
+  /** Set only on the synthesised generator rows: which of the tsl-textures
+   *  materials the `tsl-texture` card this row adds should run. */
+  generator?: string;
+}
+
+/**
+ * `tsl-texture` is skipped here because the loop below offers it FORTY TIMES
+ * OVER, once per generator. Bare, it would be a card whose sockets appear only
+ * after the author works out that a dropdown decides them — the opposite of
+ * what a palette is for. Unlike `HIDDEN`, this is not a kind the door refuses;
+ * it is a kind that arrives by a better row.
+ */
+function offerable(spec: MaterialGraphNodeSpec): boolean {
+  return spec.category !== "output" && !HIDDEN.has(spec.kind) && spec.kind !== "tsl-texture";
+}
+
+/** Does any of a row's searchable text contain what was typed? */
+function matches(needle: string, terms: readonly (string | undefined)[]): boolean {
+  return (
+    needle === "" || terms.some((term) => term !== undefined && term.toLowerCase().includes(needle))
+  );
+}
+
+/**
+ * Could a wire held at `from` land on these sockets at all?
+ *
+ * Takes the SOCKETS rather than the spec, because a generator row's sockets are
+ * its generator's parameter list — the `tsl-texture` spec's own inputs are
+ * empty until a generator is named, and judging forty rows by that would offer
+ * every one of them to a wire none of them could take.
+ *
+ * `"numeric"` on either side is the GENERIC and matches anything that is not a
+ * texture handle: `socketAccepts` takes a RESOLVED type as its second argument
+ * and `numeric` is not one, so asking it directly would be a type error dressed
+ * up as a filter that hid every generic node.
+ */
+function acceptsWire(
+  io: { inputs: readonly MaterialGraphSocketSpec[]; outputs: readonly MaterialGraphSocketSpec[] },
+  from: MaterialPaletteSource,
+): boolean {
+  const generic = from.type === "numeric";
+  if (from.side === "source") {
+    // The author holds an OUTPUT and wants something to feed.
+    return io.inputs.some((input) =>
+      generic
+        ? input.type !== "texture"
+        : socketAccepts(input.type, from.type as MaterialGraphResolvedType, input.accepts),
+    );
+  }
+  // The author holds an INPUT and wants something to produce.
+  return io.outputs.some((output) => {
+    if (output.type === "numeric") return from.type !== "texture";
+    if (generic) return output.type !== "texture";
+    return socketAccepts(from.type, output.type as MaterialGraphResolvedType);
+  });
+}
+
+/**
+ * The list, filtered. A pure function so `materialPalette.test.tsx` can check
+ * both halves — the keyword search and the socket filter — without a canvas.
+ *
+ * Search matches the LABEL, the kind's own id, its category and its declared
+ * keywords. The keywords are what an author would type: `1-x` finds One Minus,
+ * `voronoi` finds Worley, `if` finds Select.
+ *
+ * The second loop is the tsl-textures library. It is ONE node kind carrying a
+ * `generator` field, but an author looking for marble types "marble" and not
+ * "texture generator", so the palette synthesises a row per material and the
+ * pick carries the name through to the door. Each row also answers to the
+ * kind's own terms, so "procedural" still surfaces the whole shelf.
+ */
+export function materialPaletteRows(
+  query: string,
+  from?: MaterialPaletteSource,
+): MaterialPaletteRow[] {
+  const needle = query.trim().toLowerCase();
+  const rows: MaterialPaletteRow[] = [];
+  for (const spec of Object.values(MATERIAL_GRAPH_NODE_SPECS)) {
+    if (!offerable(spec)) continue;
+    if (from !== undefined && !acceptsWire(spec, from)) continue;
+    if (!matches(needle, [spec.label, spec.kind, spec.category, ...(spec.keywords ?? [])])) continue;
+    rows.push({ kind: spec.kind, label: spec.label, category: spec.category });
+  }
+  const tsl = MATERIAL_GRAPH_NODE_SPECS["tsl-texture"];
+  for (const [generator, entry] of Object.entries(MATERIAL_GRAPH_GENERATORS)) {
+    if (from !== undefined && !acceptsWire({ inputs: entry.inputs, outputs: tsl.outputs }, from)) {
+      continue;
+    }
+    if (
+      !matches(needle, [
+        entry.label,
+        generator,
+        tsl.label,
+        tsl.category,
+        ...(entry.keywords ?? []),
+        ...(tsl.keywords ?? []),
+      ])
+    ) {
+      continue;
+    }
+    rows.push({ kind: "tsl-texture", label: entry.label, category: tsl.category, generator });
+  }
+  return rows.sort((a, b) => {
+    const ai = CATEGORY_ORDER.indexOf(a.category);
+    const bi = CATEGORY_ORDER.indexOf(b.category);
+    const ao = ai < 0 ? CATEGORY_ORDER.length : ai;
+    const bo = bi < 0 ? CATEGORY_ORDER.length : bi;
+    return ao === bo ? a.label.localeCompare(b.label) : ao - bo;
+  });
+}
+
+export interface MaterialNodePaletteProps {
+  materialId: string;
+  path: readonly string[];
+  request: MaterialPaletteRequest;
+  /** Where the list sits, in CLIENT px — the canvas converts the request's
+   *  graph point, because only it knows the viewport transform. */
+  screenAt: { x: number; y: number };
+  /** Where the picked node lands, in GRAPH px. */
+  graphAt: readonly [number, number];
+}
+
+export function MaterialNodePalette({
+  materialId,
+  path,
+  request,
+  screenAt,
+  graphAt,
+}: MaterialNodePaletteProps) {
+  const store = useStore();
+  const [query, setQuery] = useState("");
+  const [active, setActive] = useState(0);
+  const listRef = useRef<HTMLDivElement | null>(null);
+  const rows = useMemo(() => materialPaletteRows(query, request.from), [query, request.from]);
+
+  // A new request is a new palette. `materialPalette` is a fresh-identity
+  // mailbox, so this fires on the second Tab at the same point too — which is
+  // what makes re-opening feel like re-opening rather than like nothing.
+  useEffect(() => {
+    setQuery("");
+    setActive(0);
+  }, [request]);
+
+  useEffect(() => {
+    setActive((current) => (current >= rows.length ? Math.max(0, rows.length - 1) : current));
+  }, [rows.length]);
+
+  // The active row scrolled into view, so holding ArrowDown walks the list
+  // rather than walking off the bottom of it.
+  useEffect(() => {
+    const row = listRef.current?.querySelector<HTMLElement>("[data-active='true']");
+    // jsdom implements no `scrollIntoView`, and a runtime guard here is cheaper
+    // than a stub every suite that mounts a palette would have to install.
+    if (typeof row?.scrollIntoView === "function") row.scrollIntoView({ block: "nearest" });
+  }, [active]);
+
+  const pick = (row: MaterialPaletteRow): void => {
+    store.addMaterialNode(
+      materialId,
+      path,
+      row.kind,
+      [graphAt[0], graphAt[1]],
+      request.from,
+      row.generator,
+    );
+  };
+
+  let shelf: MaterialGraphNodeCategory | null = null;
+  return (
+    <div
+      className="material-node-palette nodrag nowheel"
+      role="dialog"
+      aria-label="Add shader node"
+      data-testid="material-node-palette"
+      style={{ left: `${screenAt.x}px`, top: `${screenAt.y}px` }}
+    >
+      <input
+        autoFocus
+        type="search"
+        className="material-node-search"
+        value={query}
+        placeholder={request.from === undefined ? "Search nodes" : "Search nodes that fit"}
+        aria-label="Search shader nodes"
+        onChange={(event) => setQuery(event.currentTarget.value)}
+        onKeyDown={(event) => {
+          if (event.key === "ArrowDown") {
+            event.preventDefault();
+            setActive((current) => (rows.length === 0 ? 0 : (current + 1) % rows.length));
+          } else if (event.key === "ArrowUp") {
+            event.preventDefault();
+            setActive((current) => (rows.length === 0 ? 0 : (current - 1 + rows.length) % rows.length));
+          } else if (event.key === "Enter") {
+            event.preventDefault();
+            const row = rows[active];
+            if (row !== undefined) pick(row);
+          } else if (event.key === "Escape") {
+            // STOPPED HERE. The shell's keymap listens on `window`, and letting
+            // Escape reach it would run the whole material ladder — closing the
+            // palette AND dropping the selection behind it, two rungs for one
+            // press.
+            event.preventDefault();
+            event.stopPropagation();
+            store.closeMaterialPalette();
+          }
+        }}
+      />
+      <div className="material-node-palette-scroll" ref={listRef}>
+        {rows.length === 0 ? (
+          <p className="material-empty-copy">
+            {request.from === undefined
+              ? `No node matches “${query.trim()}”.`
+              : "No node takes that connection."}
+          </p>
+        ) : (
+          rows.map((row, index) => {
+            const heading = row.category === shelf ? null : (
+              <h3 key={`shelf-${row.category}`}>{CATEGORY_LABELS[row.category]}</h3>
+            );
+            shelf = row.category;
+            return (
+              <div className="material-node-category" key={row.generator ?? row.kind}>
+                {heading}
+                <button
+                  type="button"
+                  data-active={index === active}
+                  className={index === active ? "is-active" : ""}
+                  // POINTER-DOWN, not click. The search field has focus and a
+                  // click fires after the blur, which is one more chance for
+                  // the palette to close under the cursor before the pick lands.
+                  onPointerDown={(event) => {
+                    event.preventDefault();
+                    pick(row);
+                  }}
+                  onMouseEnter={() => setActive(index)}
+                >
+                  <span>{row.label}</span>
+                </button>
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+}