@ttsc/graph 0.27.0 → 0.28.1

package/src/viewer/legend.ts

@@ -0,0 +1,107 @@
+// The bundled viewer's display vocabulary and the legend it renders from it.
+//
+// Separate from `main.ts` because that module fetches and renders on import, so
+// nothing can read its constants or exercise its legend without a browser. The
+// legend is the surface this file exists to protect: it used to be literal
+// markup in `index.html` with each colour repeated in a `style` attribute, and a
+// new family shipped into the graph with no entry beside it until someone opened
+// both files.
+
+/** The slice of the DOM the legend needs, so a test can drive it without one. */
+export interface LegendElement {
+  className: string;
+  style: { background: string };
+  // `unknown[]`, because the real `Document` types these as `(Node | string)[]`
+  // and a narrower parameter is not assignable to it. `src/viewer` is excluded
+  // from the declaration build, so nothing would have reported that.
+  append(...nodes: unknown[]): void;
+  prepend(...nodes: unknown[]): void;
+}
+
+/** The slice of `document` the legend needs. */
+export interface LegendDocument {
+  getElementById(id: string): LegendElement | null;
+  createElement(tag: string): LegendElement;
+}
+
+/**
+ * Node colour per declaration kind.
+ *
+ * Total over the kinds a dump can carry (`TtscGraphDumpNodeKind`). `module` was
+ * missing, and because the fallback below was the same string as `variable`, a
+ * module was not merely unnamed — it was drawn as a variable.
+ */
+export const NODE_COLORS: Record<string, string> = {
+  // The artifacts. They are one hue family on purpose: a reader tells a document
+  // from a declaration at a glance, and tells the artifacts apart within it.
+  markdown_document: "#e8b4b8",
+  markdown_section: "#d99ba0",
+  prisma_model: "#b8a3e8",
+  prisma_column: "#a08fd0",
+  prisma_relation: "#8a76c0",
+  swagger_operation: "#e8d9a0",
+  module: "#d0d7de",
+  class: "#36e2ee",
+  interface: "#6ea8ff",
+  function: "#3fb950",
+  method: "#2bb673",
+  type: "#f5b042",
+  enum: "#c792ea",
+  variable: "#8b97a8",
+};
+
+/**
+ * Edge colour per display family.
+ *
+ * One definition: the edge colour, the legend swatch, and the legend name all
+ * read this map. `exports` is neutral because it is a structural relation
+ * rather than a use, and it is opaque so it stays apart from the translucent
+ * fallback.
+ */
+export const LINK_COLORS: Record<string, string> = {
+  "value-call": "#3fb950",
+  "type-ref": "#f5b042",
+  "doc-ref": "#c07de0",
+  heritage: "#6ea8ff",
+  exports: "#7d8590",
+};
+
+/**
+ * What an unrecognized node kind is drawn in.
+ *
+ * It has to differ from every value in {@link NODE_COLORS}, or "I do not know
+ * this kind" and "this is a variable" are the same picture.
+ */
+export const UNKNOWN_NODE_COLOR = "#565f6b";
+
+/** What an unrecognized edge kind is drawn in; translucent, unlike a family. */
+export const UNKNOWN_LINK_COLOR = "#ffffff55";
+
+/** Elements whose legend is already built, so a second call adds nothing. */
+const rendered = new WeakSet<LegendElement>();
+
+/**
+ * Fill the footer legend from {@link LINK_COLORS}, so a family cannot be drawn
+ * without being named.
+ *
+ * The swatches are prepended, which puts them ahead of the static note the
+ * markup keeps — the order the hand-written markup had. The website viewer has
+ * always derived its legend this way
+ * (`website/src/components/graph/TtscWebsiteGraphViewer3D.tsx`).
+ */
+export function renderLegend(host: LegendDocument): void {
+  const legend = host.getElementById("legend");
+  if (legend === null || rendered.has(legend)) return;
+  rendered.add(legend);
+  legend.prepend(
+    ...Object.entries(LINK_COLORS).map(([kind, color]) => {
+      const dot = host.createElement("span");
+      dot.className = "dot";
+      const swatch = host.createElement("span");
+      swatch.className = "swatch";
+      swatch.style.background = color;
+      dot.append(swatch, kind);
+      return dot;
+    }),
+  );
+}

package/src/viewer/main.ts

@@ -1,11 +1,21 @@
 // Vanilla 3D code-graph viewer bundled into @ttsc/graph by esbuild and served by
-// `ttsc-graph view`. Mirrors website/src/components/graph/GraphViewer3D.tsx, but
-// standalone (no React): fetch the reduced graph the CLI serves, render it on
-// three.js + three-forcegraph, and let the user orbit it.
+// `ttsc-graph view`. Mirrors website/src/components/graph/TtscWebsiteGraphViewer3D.tsx,
+// but standalone (no React): fetch the reduced graph the CLI serves, render it on
+// three.js + three-forcegraph, and let the user orbit it. The display vocabulary
+// and the legend live in ./legend, which this module has no side effects to hide
+// from a test.
 import * as THREE from "three";
 import ThreeForceGraph from "three-forcegraph";
 import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
 
+import {
+  LINK_COLORS,
+  NODE_COLORS,
+  UNKNOWN_LINK_COLOR,
+  UNKNOWN_NODE_COLOR,
+  renderLegend,
+} from "./legend";
+
 interface GNode {
   id: string;
   name: string;
@@ -27,22 +37,6 @@ interface Payload {
   links: GLink[];
 }
 
-const NODE_COLORS: Record<string, string> = {
-  class: "#36e2ee",
-  interface: "#6ea8ff",
-  function: "#3fb950",
-  method: "#2bb673",
-  type: "#f5b042",
-  enum: "#c792ea",
-  variable: "#8b97a8",
-};
-
-const LINK_COLORS: Record<string, string> = {
-  "value-call": "#3fb950",
-  "type-ref": "#f5b042",
-  heritage: "#6ea8ff",
-};
-
 function escapeHtml(value: string): string {
   return value
     .replace(/&/g, "&amp;")
@@ -56,6 +50,10 @@ function setText(id: string, text: string): void {
 }
 
 async function main(): Promise<void> {
+  // Before the fetch, so a graph that fails to load still shows the legend the
+  // static markup used to guarantee.
+  renderLegend(document);
+
   const container = document.getElementById("graph");
   if (!container) return;
 
@@ -103,8 +101,8 @@ async function main(): Promise<void> {
     .nodeResolution(12)
     .nodeOpacity(0.95)
     .nodeVal((node) => 1 + Math.sqrt(node.degree))
-    .nodeColor((node) => NODE_COLORS[node.kind] ?? "#8b97a8")
-    .linkColor((link) => LINK_COLORS[link.kind] ?? "#ffffff55")
+    .nodeColor((node) => NODE_COLORS[node.kind] ?? UNKNOWN_NODE_COLOR)
+    .linkColor((link) => LINK_COLORS[link.kind] ?? UNKNOWN_LINK_COLOR)
     .linkOpacity(0.4)
     .linkWidth(0)
     .warmupTicks(20)