@reventlessdev/reventless-graph 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,79 @@
+# @reventlessdev/reventless-graph
+
+The **graph view mode** for Reventless AutoUI, built on the framework-agnostic
+[`@reventlessdev/rescript-cytoscape`](../../rescript/cytoscape) bindings:
+
+- `ReventlessGraph.GraphMode.init()` — registers the `"graph"` view mode.
+  Offered automatically wherever a read model's (or nested collection's)
+  schema carries an entity-ref field — a `*Id` / `*Ids` foreign key, the same
+  heuristic the table cells link through.
+- `ReventlessGraph.GraphView` — the underlying Cytoscape.js component the
+  `"graph"` mode renders (pan / zoom / fit, layered `dagre` layout by default).
+- `ReventlessGraph.GraphData` — the pure adapter: `buildGraph(source)` →
+  `{nodes, edges}`, with no cytoscape or React in sight.
+
+Each loaded row becomes a node and each entity reference a directed edge. When
+a referenced id is itself a loaded row the edge resolves to that row's label —
+so **self-referential fields (`managerId`, `dependsOnIds`, `parentId`) form
+trees, org charts and dependency DAGs**. Ids pointing at unloaded entities
+render as short stub nodes grouped by their stem.
+
+This package is an **optional add-on**: reventless-ui never imports it, so
+apps without relationship graphs pay no bundle cost.
+
+## Setup
+
+```bash
+pnpm add @reventlessdev/reventless-graph cytoscape cytoscape-dagre cytoscape-fcose
+```
+
+`rescript.json`:
+
+```json
+"dependencies": ["@reventlessdev/reventless-graph"]
+```
+
+App entry (once, before the first auto page renders):
+
+```rescript
+ReventlessGraph.GraphMode.init()
+// or pick another layout for every graph view:
+// ReventlessGraph.GraphMode.init(~layout="cose", ())
+```
+
+Layouts: `dagre` (layered, the default — bottom-to-top, so a referenced row
+sits above the rows referencing it), `fcose` (force / cluster, and the only
+one that lays out compound cluster boxes properly), `cose` (the built-in force
+layout), `breadthfirst`, `concentric`, `grid`, `circle`.
+
+Node colours come from the theme (`Tokens.Color.brand` for the home read
+model, a literal palette for cross-entity stub groups). A canvas cannot read
+`var(--rv-…)`, so GraphView resolves the tokens against its container element
+and re-applies the stylesheet when the theme preset changes.
+
+## Building in this repo
+
+`pnpm run build` here uses `rescript-legacy`: the ReScript v12 build
+orchestrator still panics (UTF-8 underline bug) when invoked from a downstream
+package that walks into reventless-ui's bs-dependencies. Build in order —
+`rescript/cytoscape`, then this package, then **reventless-ui last**: a build
+here walks into ui and deletes its tracked dev-source `.res.mjs`
+(`stories/`, `tests/`), which only `rescript-legacy clean && build` in ui
+restores. Never use `-with-deps` from here, and `clean` this package after any
+change to the bindings.
+
+## Stories
+
+Storybook lives in `reventless/ui`, but this package sits **downstream** of
+reventless-ui, so its stories compile without the build cycle that a story
+placed inside ui would create. Author graph stories under `stories/` here;
+ui's Storybook picks them up via a glob that also scans `../../graph/stories`,
+and ui carries cytoscape + this package as **dev**-only dependencies so the
+bundler resolves them (the published ui surface stays cytoscape-free).
+
+## Tests
+
+`GraphData` is pure and covered by `tests/GraphDataTests.res` (`pnpm test`
+here, or from the repo root — the root jest config lists this package as a
+project). Layout is the library's, so there is nothing left to unit-test in
+the renderer.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@reventlessdev/reventless-graph",
+  "version": "0.1.0-alpha.1",
+  "description": "Graph view mode (GraphView, GraphMode, GraphData) for Reventless AutoUI, built on @reventlessdev/rescript-cytoscape. Optional add-on: apps without relationship graphs never load it.",
+  "license": "MIT",
+  "files": [
+    "src/**/*.res",
+    "src/**/*.res.mjs",
+    "rescript.json"
+  ],
+  "scripts": {
+    "build": "rescript-legacy build",
+    "start": "rescript-legacy build -w",
+    "clean": "rescript-legacy clean",
+    "test": "jest"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.22.4",
+    "@glennsl/rescript-jest": "0.13.1",
+    "@rescript/react": "^0.13.1",
+    "@reventlessdev/rescript-cytoscape": "0.1.0-alpha.1",
+    "@reventlessdev/reventless-ui": "3.0.0-alpha.40",
+    "babel-jest": "^29.7.0",
+    "cytoscape": "^3.34.0",
+    "cytoscape-dagre": "^4.0.0",
+    "cytoscape-fcose": "^2.2.0",
+    "jest": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rescript": "^12.3.0"
+  },
+  "peerDependencies": {
+    "@rescript/react": "^0.13.1",
+    "@reventlessdev/rescript-cytoscape": ">=0.1.0-alpha.0",
+    "@reventlessdev/reventless-ui": ">=3.0.0-alpha.39",
+    "cytoscape": ">=3.30.0",
+    "cytoscape-dagre": ">=2.5.0",
+    "cytoscape-fcose": ">=2.2.0",
+    "react": "^18.3.1",
+    "rescript": "^12.3.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "gitHead": "ee9a72b1a1f76e7fdeab58922e4fb653a1b20cec"
+}

package/rescript.json

@@ -0,0 +1,19 @@
+{
+  "name": "@reventlessdev/reventless-graph",
+  "namespace": "ReventlessGraph",
+  "jsx": { "version": 4 },
+  "sources": [
+    { "dir": "src", "subdirs": true },
+    { "dir": "stories", "subdirs": true, "type": "dev" },
+    { "dir": "tests", "subdirs": true, "type": "dev" }
+  ],
+  "package-specs": { "module": "esmodule", "in-source": true },
+  "suffix": ".res.mjs",
+  "warnings": { "number": "-3" },
+  "dependencies": [
+    "@rescript/react",
+    "@glennsl/rescript-jest",
+    "@reventlessdev/reventless-ui",
+    "@reventlessdev/rescript-cytoscape"
+  ]
+}

package/src/GraphData.res

@@ -0,0 +1,122 @@
+// Pure source → node/edge mapping for GraphView. Kept free of cytoscape and
+// React (the MapData analog) so the shapes stay jest-testable and reusable.
+//
+// Each loaded row is a node; each entity-ref field (KEntityId /
+// KArrayOfEntityIds — the same *Id/*Ids foreign-key heuristic the table cells
+// link through) draws a directed edge to the referenced id. When a referenced
+// id is itself a loaded row, the edge resolves to that row's label — so
+// self-referential fields (managerId, dependsOnIds, parentId) form trees /
+// org charts / dependency DAGs; ids pointing at unloaded entities render as
+// short stub nodes grouped by their stem.
+
+type node = {
+  id: string,
+  label: string,
+  group?: string, // colours the node by its home entity / ref stem
+  accent?: string, // explicit colour override
+}
+
+type edge = {
+  from: string,
+  to_: string,
+  label?: string,
+}
+
+type graph = {
+  nodes: array<node>,
+  edges: array<edge>,
+}
+
+// Entity-ref fields of a schema: (fieldKey, stem, isMulti). Reuses
+// AutoColumns.classify so the graph sees exactly the refs the table links.
+let entityRefFields = (schema: Js.Json.t): array<(string, string, bool)> =>
+  ReventlessUi.AutoSemantics.properties(schema)->Array.filterMap(((key, propSchema)) => {
+    let ann = ReventlessUi.SchemaAnnotations.fromProp(propSchema)
+    switch ReventlessUi.AutoColumns.classify(~key, ~propSchema, ~ann) {
+    | ReventlessUi.AutoColumns.KEntityId(stem) => Some((key, stem, false))
+    | ReventlessUi.AutoColumns.KArrayOfEntityIds(stem) => Some((key, stem, true))
+    | _ => None
+    }
+  })
+
+let graphCapable = (schema: Js.Json.t): bool => Array.length(entityRefFields(schema)) > 0
+
+// Referenced ids for one ref field of one row (multi fans to many).
+let refTargetIds = (
+  row: ReventlessUi.AutoModes.preparedRow,
+  field: string,
+  isMulti: bool,
+): array<string> =>
+  if isMulti {
+    Js.Dict.get(row.dict, field)
+    ->Option.flatMap(Js.Json.decodeArray)
+    ->Option.getOr([])
+    ->Array.filterMap(Js.Json.decodeString)
+  } else {
+    ReventlessUi.AutoModes.stringAt(row.dict, field)->Option.mapOr([], v => [v])
+  }
+
+// Pure graph derivation (exported for tests). Row nodes first, then target
+// nodes; dedup by id keeps the row node so a referenced-and-loaded row keeps
+// its real label.
+let buildGraph = (source: ReventlessUi.AutoViewMode.source): graph => {
+  let refFields = entityRefFields(source.schema)
+  let rows = ReventlessUi.AutoModes.prepareRows(source)
+  let rowLabel = Js.Dict.empty()
+  rows->Array.forEach(r => Js.Dict.set(rowLabel, r.key, ReventlessUi.AutoModes.titleOf(source, r)))
+  let shortId = (id: string): string =>
+    String.length(id) > 8 ? String.slice(id, ~start=0, ~end=8) ++ `…` : id
+
+  let rowNodes: array<node> =
+    rows->Array.map(r => {
+      id: r.key,
+      label: ReventlessUi.AutoModes.titleOf(source, r),
+      group: source.readModelName,
+    })
+
+  let targetNodes: array<node> =
+    rows->Array.flatMap(r =>
+      refFields->Array.flatMap(((field, stem, isMulti)) =>
+        refTargetIds(r, field, isMulti)->Array.map(targetId => {
+          switch Js.Dict.get(rowLabel, targetId) {
+          // A referenced row that is also loaded → real label, home group.
+          | Some(label) => {id: targetId, label, group: source.readModelName}
+          // Cross-entity stub → short id, grouped by the ref stem.
+          | None => {
+              id: targetId,
+              label: shortId(targetId),
+              group: ReventlessUi.Humanize.humanizeKey(stem),
+            }
+          }
+        })
+      )
+    )
+
+  let nodes =
+    Array.concat(rowNodes, targetNodes)->Array.reduce([], (acc, node) =>
+      acc->Array.some(n => n.id == node.id) ? acc : Array.concat(acc, [node])
+    )
+
+  let edges: array<edge> =
+    rows->Array.flatMap(r =>
+      refFields->Array.flatMap(((field, _stem, isMulti)) =>
+        refTargetIds(r, field, isMulti)->Array.map(targetId => {
+          from: r.key,
+          to_: targetId,
+          label: ReventlessUi.Humanize.humanizeKey(field),
+        })
+      )
+    )
+
+  {nodes, edges}
+}
+
+// Distinct group names in first-seen order — the stylesheet assigns one
+// colour per group in exactly this order.
+let groupsOf = (nodes: array<node>): array<string> =>
+  nodes->Array.reduce([], (acc, n) =>
+    switch n.group {
+    | Some(g) if !(acc->Array.includes(g)) => Array.concat(acc, [g])
+    | _ => acc
+    }
+  )

package/src/GraphData.res.mjs

@@ -0,0 +1,130 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Js_dict from "@rescript/runtime/lib/es6/Js_dict.js";
+import * as Js_json from "@rescript/runtime/lib/es6/Js_json.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Humanize$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/Humanize.res.mjs";
+import * as AutoModes$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/AutoModes.res.mjs";
+import * as AutoColumns$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/AutoColumns.res.mjs";
+import * as AutoSemantics$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/AutoSemantics.res.mjs";
+import * as SchemaAnnotations$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/SchemaAnnotations.res.mjs";
+
+function entityRefFields(schema) {
+  return Stdlib_Array.filterMap(AutoSemantics$ReventlessUi.properties(schema), param => {
+    let propSchema = param[1];
+    let key = param[0];
+    let ann = SchemaAnnotations$ReventlessUi.fromProp(propSchema);
+    let stem = AutoColumns$ReventlessUi.classify(key, propSchema, ann);
+    if (typeof stem !== "object") {
+      return;
+    }
+    switch (stem.TAG) {
+      case "KEntityId" :
+        return [
+          key,
+          stem._0,
+          false
+        ];
+      case "KArrayOfEntityIds" :
+        return [
+          key,
+          stem._0,
+          true
+        ];
+      default:
+        return;
+    }
+  });
+}
+
+function graphCapable(schema) {
+  return entityRefFields(schema).length !== 0;
+}
+
+function refTargetIds(row, field, isMulti) {
+  if (isMulti) {
+    return Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Js_dict.get(row.dict, field), Js_json.decodeArray), []), Js_json.decodeString);
+  } else {
+    return Stdlib_Option.mapOr(AutoModes$ReventlessUi.stringAt(row.dict, field), [], v => [v]);
+  }
+}
+
+function buildGraph(source) {
+  let refFields = entityRefFields(source.schema);
+  let rows = AutoModes$ReventlessUi.prepareRows(source);
+  let rowLabel = {};
+  rows.forEach(r => {
+    rowLabel[r.key] = AutoModes$ReventlessUi.titleOf(source, r);
+  });
+  let shortId = id => {
+    if (id.length > 8) {
+      return id.slice(0, 8) + `…`;
+    } else {
+      return id;
+    }
+  };
+  let rowNodes = rows.map(r => ({
+    id: r.key,
+    label: AutoModes$ReventlessUi.titleOf(source, r),
+    group: source.readModelName
+  }));
+  let targetNodes = rows.flatMap(r => refFields.flatMap(param => {
+    let stem = param[1];
+    return refTargetIds(r, param[0], param[2]).map(targetId => {
+      let label = Js_dict.get(rowLabel, targetId);
+      if (label !== undefined) {
+        return {
+          id: targetId,
+          label: label,
+          group: source.readModelName
+        };
+      } else {
+        return {
+          id: targetId,
+          label: shortId(targetId),
+          group: Humanize$ReventlessUi.humanizeKey(stem)
+        };
+      }
+    });
+  }));
+  let nodes = Stdlib_Array.reduce(rowNodes.concat(targetNodes), [], (acc, node) => {
+    if (acc.some(n => n.id === node.id)) {
+      return acc;
+    } else {
+      return acc.concat([node]);
+    }
+  });
+  let edges = rows.flatMap(r => refFields.flatMap(param => {
+    let field = param[0];
+    return refTargetIds(r, field, param[2]).map(targetId => ({
+      from: r.key,
+      to_: targetId,
+      label: Humanize$ReventlessUi.humanizeKey(field)
+    }));
+  }));
+  return {
+    nodes: nodes,
+    edges: edges
+  };
+}
+
+function groupsOf(nodes) {
+  return Stdlib_Array.reduce(nodes, [], (acc, n) => {
+    let g = n.group;
+    if (g !== undefined && !acc.includes(g)) {
+      return acc.concat([g]);
+    } else {
+      return acc;
+    }
+  });
+}
+
+export {
+  entityRefFields,
+  graphCapable,
+  refTargetIds,
+  buildGraph,
+  groupsOf,
+}
+/* Humanize-ReventlessUi Not a pure module */

package/src/GraphMode.res

@@ -0,0 +1,56 @@
+// Registers the "graph" view mode with reventless-ui's registry.
+// Registration is an explicit opt-in (GraphMode.init() from the host app),
+// never a module side effect of reventless-ui: apps without relationship
+// graphs never load this package or cytoscape.
+
+let defaultLayout = "dagre"
+
+let layoutRef = ref(defaultLayout)
+
+let graphIcon =
+  <span ariaHidden=true style={ReactDOM.Style.make(~fontSize="0.9em", ~lineHeight="1", ())}>
+    {React.string(`◈`)}
+  </span>
+
+module ModeView = {
+  @react.component
+  let make = (~source: ReventlessUi.AutoViewMode.source) => {
+    let rows = ReventlessUi.AutoModes.prepareRows(source)
+    let g = GraphData.buildGraph(source)
+    // Only loaded-row ids match openRow's find, so stub nodes are inert.
+    <GraphView
+      nodes=g.nodes
+      edges=g.edges
+      layout=layoutRef.contents
+      onOpenNode={id => ReventlessUi.AutoModes.openRow(source, rows, id)}
+    />
+  }
+}
+
+// Call once at app startup, before the first auto page renders. `layout`
+// picks the cytoscape layout the mode renders with: "dagre" (layered — the
+// default, best for the hierarchical data entity refs usually describe),
+// "fcose" / "cose" (force / cluster), "breadthfirst", "concentric", "grid",
+// "circle".
+let init = (~layout: option<string>=?, ()): unit => {
+  layout->Option.forEach(l => layoutRef := l)
+  ReventlessUi.AutoViewMode.register({
+    id: "graph",
+    label: "Graph",
+    icon: graphIcon,
+    // Single-source: a canvas spanning several read models (compound parents
+    // per source) is not supported yet.
+    arity: Single,
+    // Needs at least one entity-ref field (*Id/*Ids foreign key) to draw edges.
+    isCapable: GraphData.graphCapable,
+    render: sources =>
+      switch sources->Array.get(0) {
+      | Some(source) => <ModeView source />
+      | None => React.null
+      },
+    // Keep in sync with the `optionalModes` entry in ui's ComponentManifest —
+    // this registration only exists at app runtime, so the manifest can't
+    // read it from the registry.
+    capability: "entity-ref fields — one or more *Id/*Ids foreign keys drawn as a node-link diagram (self-referential fields form trees)",
+  })
+}

package/src/GraphMode.res.mjs

@@ -0,0 +1,72 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as JsxRuntime from "react/jsx-runtime";
+import * as AutoModes$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/AutoModes.res.mjs";
+import * as AutoViewMode$ReventlessUi from "@reventlessdev/reventless-ui/src/auto/AutoViewMode.res.mjs";
+import * as GraphData$ReventlessGraph from "./GraphData.res.mjs";
+import * as GraphView$ReventlessGraph from "./GraphView.res.mjs";
+
+let defaultLayout = "dagre";
+
+let layoutRef = {
+  contents: defaultLayout
+};
+
+let graphIcon = JsxRuntime.jsx("span", {
+  children: `◈`,
+  "aria-hidden": true,
+  style: {
+    fontSize: "0.9em",
+    lineHeight: "1"
+  }
+});
+
+function GraphMode$ModeView(props) {
+  let source = props.source;
+  let rows = AutoModes$ReventlessUi.prepareRows(source);
+  let g = GraphData$ReventlessGraph.buildGraph(source);
+  return JsxRuntime.jsx(GraphView$ReventlessGraph.make, {
+    nodes: g.nodes,
+    edges: g.edges,
+    onOpenNode: id => AutoModes$ReventlessUi.openRow(source, rows, id),
+    layout: layoutRef.contents
+  });
+}
+
+let ModeView = {
+  make: GraphMode$ModeView
+};
+
+function init(layout, param) {
+  Stdlib_Option.forEach(layout, l => {
+    layoutRef.contents = l;
+  });
+  AutoViewMode$ReventlessUi.register({
+    id: "graph",
+    label: "Graph",
+    icon: graphIcon,
+    arity: "Single",
+    isCapable: GraphData$ReventlessGraph.graphCapable,
+    render: sources => {
+      let source = sources[0];
+      if (source !== undefined) {
+        return JsxRuntime.jsx(GraphMode$ModeView, {
+          source: source
+        });
+      } else {
+        return null;
+      }
+    },
+    capability: "entity-ref fields — one or more *Id/*Ids foreign keys drawn as a node-link diagram (self-referential fields form trees)"
+  });
+}
+
+export {
+  defaultLayout,
+  layoutRef,
+  graphIcon,
+  ModeView,
+  init,
+}
+/* graphIcon Not a pure module */

package/src/GraphView.res

@@ -0,0 +1,339 @@
+// The graph view mode's renderer: a Cytoscape.js instance over GraphData's
+// nodes/edges. Registered by GraphMode.init() (never by reventless-ui
+// itself), so apps without relationship graphs pay no bundle cost.
+//
+// Cytoscape owns a canvas inside the container element and brings its own
+// camera (pan / zoom / fit) and layouts — `dagre` (layered, the default: our
+// data is mostly hierarchical) plus the built-in `cose` / `concentric` /
+// `breadthfirst` / `grid` / `circle`.
+//
+// Theming: a canvas cannot read `var(--rv-…)`, and ThemeProvider scopes those
+// custom properties to a wrapper class rather than :root — so the stylesheet
+// resolves each token against the *container element* via getComputedStyle
+// and is re-applied whenever the theme preset changes.
+
+module Cy = Cytoscape.CytoscapeBindings
+
+type cssStyleDeclaration
+@val external getComputedStyle: Dom.element => cssStyleDeclaration = "getComputedStyle"
+@send external getPropertyValue: (cssStyleDeclaration, string) => string = "getPropertyValue"
+
+type resizeObserver
+@new external makeResizeObserver: (unit => unit) => resizeObserver = "ResizeObserver"
+@send external observe: (resizeObserver, Dom.element) => unit = "observe"
+@send external disconnect: resizeObserver => unit = "disconnect"
+
+// `dagre` (layered) and `fcose` (compound-aware force) are extensions,
+// registered globally on the cytoscape module — do it once, lazily, from the
+// only place that can need them (registering twice makes cytoscape warn).
+let extensionsRegistered = ref(false)
+let ensureExtensions = (): unit =>
+  if !extensionsRegistered.contents {
+    extensionsRegistered := true
+    Cy.use(Cy.dagre)
+    Cy.use(Cy.fcose)
+  }
+
+let tokenValue = (el: Dom.element, token: string, ~fallback: string): string => {
+  let v = getComputedStyle(el)->getPropertyValue(token)->String.trim
+  v == "" ? fallback : v
+}
+
+// Literal colours for groups past the first (which takes the brand token) —
+// custom properties never reach the canvas, so this mirrors MapData's
+// literalPalette.
+let literalPalette = ["#7c9c5e", "#b0743c", "#7466a3", "#4d8a8a", "#a35f74"]
+
+// Group names become element classes, so strip anything not class-safe.
+let groupClass = (group: string): string =>
+  "grp-" ++ group->String.replaceRegExp(%re("/[^a-zA-Z0-9_-]+/g"), "-")
+
+let elementsOf = (~nodes: array<GraphData.node>, ~edges: array<GraphData.edge>): array<
+  Cy.element,
+> => {
+  let ids = nodes->Array.map(n => n.id)
+  let nodeEls = nodes->Array.map(n =>
+    Cy.nodeElement({
+      data: {id: n.id, label: n.label},
+      classes: switch n.group {
+      | Some(g) => groupClass(g)
+      | None => ""
+      },
+    })
+  )
+  // Cytoscape throws on an edge with an unknown endpoint; buildGraph always
+  // emits stub nodes for its targets, but a hand-built graph may not.
+  let edgeEls =
+    edges
+    ->Array.filter(e => ids->Array.includes(e.from) && ids->Array.includes(e.to_))
+    ->Array.mapWithIndex((e, i) =>
+      Cy.edgeElement({
+        data: {
+          // Ids are unique across nodes AND edges in cytoscape, and node ids
+          // are row ids we don't control — hence a prefix a row id can't be.
+          id: "__edge__" ++ Int.toString(i),
+          source: e.from,
+          target: e.to_,
+          label: ?e.label,
+        },
+      })
+    )
+  Array.concat(nodeEls, edgeEls)
+}
+
+let stylesheet = (~el: Dom.element, ~groups: array<string>): array<Cy.styleRule> => {
+  let brand = tokenValue(el, ReventlessUi.Tokens.Color.brand, ~fallback="#3b6ea5")
+  let text = tokenValue(el, ReventlessUi.Tokens.Color.textPrimary, ~fallback="#1a1a1a")
+  let border = tokenValue(el, ReventlessUi.Tokens.Color.border, ~fallback="#d4d4d4")
+  let surface = tokenValue(el, ReventlessUi.Tokens.Color.surface, ~fallback="#ffffff")
+  let colorFor = (i: int): string =>
+    i == 0 ? brand : literalPalette->Array.getUnsafe(mod(i - 1, Array.length(literalPalette)))
+
+  let base = [
+    Cy.rule(
+      ~selector="node",
+      [
+        ("background-color", brand),
+        ("border-width", "2"),
+        ("border-color", surface),
+        ("width", "18"),
+        ("height", "18"),
+        ("label", "data(label)"),
+        ("color", text),
+        ("font-size", "11px"),
+        ("text-valign", "center"),
+        ("text-halign", "right"),
+        ("text-margin-x", "6"),
+        ("text-wrap", "ellipsis"),
+        ("text-max-width", "150"),
+        // Labels fade out rather than pile up when zoomed far out.
+        ("min-zoomed-font-size", "7"),
+      ],
+    ),
+    // Compound parents (cluster boxes) — only present when a caller sets
+    // `parent` on the element data.
+    Cy.rule(
+      ~selector="node:parent",
+      [
+        ("background-color", border),
+        ("background-opacity", "0.12"),
+        ("border-width", "1"),
+        ("border-color", border),
+        ("text-valign", "top"),
+        ("text-halign", "center"),
+        ("font-size", "12px"),
+        ("color", text),
+        ("padding", "12"),
+      ],
+    ),
+    Cy.rule(
+      ~selector="edge",
+      [
+        ("width", "1.5"),
+        ("line-color", border),
+        ("target-arrow-color", border),
+        ("target-arrow-shape", "triangle"),
+        ("arrow-scale", "0.9"),
+        ("curve-style", "bezier"),
+      ],
+    ),
+  ]
+  let groupRules =
+    groups->Array.mapWithIndex((g, i) =>
+      Cy.rule(~selector="." ++ groupClass(g), [("background-color", colorFor(i))])
+    )
+  Array.concat(base, groupRules)
+}
+
+// Per-layout tuning. Unknown names fall through with the shared options —
+// cytoscape ignores what a layout doesn't understand.
+let layoutFor = (name: string): Cy.layoutOptions =>
+  switch name {
+  | "dagre" => {
+      name: "dagre",
+      // Edges run row → referenced row (report → manager, task → its
+      // prerequisite), so bottom-to-top puts the referenced end on top: the
+      // CEO above their reports, prerequisites above what depends on them.
+      rankDir: "BT",
+      nodeSep: 28,
+      rankSep: 56,
+      padding: 24,
+      fit: true,
+      animate: false,
+      nodeDimensionsIncludeLabels: true,
+    }
+  // The force/cluster layout. fcose is the one that understands compound
+  // parents — the built-in `cose` piles cluster boxes on top of each other.
+  | "fcose" => {
+      name: "fcose",
+      quality: "proof",
+      padding: 24,
+      fit: true,
+      animate: false,
+      randomize: true,
+      idealEdgeLength: 80,
+      nodeSeparation: 90,
+      nodeRepulsion: 6000,
+      gravityCompound: 1.5,
+      nodeDimensionsIncludeLabels: true,
+    }
+  | "cose" => {
+      name: "cose",
+      padding: 24,
+      fit: true,
+      animate: false,
+      idealEdgeLength: 90,
+      nodeRepulsion: 9000,
+      componentSpacing: 80,
+      numIter: 800,
+      // cose relaxes from the *current* positions, which on a first render
+      // are undefined — it needs its own random seeding to spread out. The
+      // picture therefore varies run to run; that is force layout, and it is
+      // why `dagre` (stable and layered) is the mode's default.
+      randomize: true,
+    }
+  | "breadthfirst" => {
+      name: "breadthfirst",
+      directed: true,
+      padding: 24,
+      fit: true,
+      animate: false,
+      spacingFactor: 1.1,
+      nodeDimensionsIncludeLabels: true,
+    }
+  | "concentric" => {
+      name: "concentric",
+      padding: 24,
+      fit: true,
+      animate: false,
+      minNodeSpacing: 40,
+      nodeDimensionsIncludeLabels: true,
+    }
+  | other => {name: other, padding: 24, fit: true, animate: false}
+  }
+
+module Style = {
+  let v = token => `var(${token})`
+
+  let wrap = (~height: string) =>
+    ReactDOM.Style.make(
+      ~width="100%",
+      ~height,
+      ~background=v(ReventlessUi.Tokens.Color.surface),
+      ~border=`1px solid ${v(ReventlessUi.Tokens.Color.border)}`,
+      ~borderRadius=v(ReventlessUi.Tokens.Radius.md),
+      ~overflow="hidden",
+      (),
+    )
+
+  let empty = ReactDOM.Style.make(
+    ~padding=v(ReventlessUi.Tokens.Spacing.lg),
+    ~color=v(ReventlessUi.Tokens.Color.textSecondary),
+    ~fontSize=v(ReventlessUi.Tokens.Typography.sizeSm),
+    (),
+  )
+}
+
+// Content signature — producers rebuild the node/edge arrays on every render,
+// so effects key off what the graph *is* rather than array identity (which
+// would tear the instance down, and reset the camera, on every render).
+let signatureOf = (nodes: array<GraphData.node>, edges: array<GraphData.edge>): string =>
+  nodes
+  ->Array.map(n => `${n.id}|${n.label}|${n.group->Option.getOr("")}`)
+  ->Array.join(",") ++
+  "//" ++
+  edges->Array.map(e => `${e.from}>${e.to_}`)->Array.join(",")
+
+@react.component
+let make = (
+  ~nodes: array<GraphData.node>,
+  ~edges: array<GraphData.edge>,
+  ~onOpenNode: option<string => unit>=?,
+  ~layout: string="dagre",
+  ~height: string="520px",
+) => {
+  let containerRef = React.useRef(Js.Nullable.null)
+  let cyRef: React.ref<option<Cy.t>> = React.useRef(None)
+  // The tap handler registers once per instance, and the resync effect reads
+  // the data, but both must see the CURRENT values (the producer re-renders
+  // with fresh rows).
+  let onOpenRef = React.useRef(onOpenNode)
+  onOpenRef.current = onOpenNode
+  let dataRef = React.useRef((nodes, edges))
+  dataRef.current = (nodes, edges)
+  let theme = ReventlessUi.ThemeContext.useTheme()
+  let signature = signatureOf(nodes, edges)
+  // Creation already used the current data; the resync effect skips its
+  // first run rather than immediately rebuilding what was just built.
+  let pristine = React.useRef(true)
+
+  React.useEffect0(() => {
+    switch containerRef.current->Js.Nullable.toOption {
+    | None => None
+    | Some(el) =>
+      ensureExtensions()
+      let cy = Cy.make({
+        container: el,
+        elements: elementsOf(~nodes, ~edges),
+        style: stylesheet(~el, ~groups=GraphData.groupsOf(nodes)),
+        layout: layoutFor(layout),
+        minZoom: 0.2,
+        maxZoom: 3.0,
+      })
+      Cy.onSelector(cy, "tap", "node", e =>
+        onOpenRef.current->Option.forEach(f => f(Cy.Event.targetId(e)))
+      )
+      cyRef.current = Some(cy)
+      // The canvas is sized from the container, so a container resize
+      // (drawer, split view, window) has to be pushed in.
+      let observer = makeResizeObserver(() => {
+        Cy.resize(cy)
+        Cy.fit(cy, 24)
+      })
+      observer->observe(el)
+      Some(
+        () => {
+          cyRef.current = None
+          observer->disconnect
+          Cy.destroy(cy)
+        },
+      )
+    }
+  })
+
+  // New rows or a new layout → swap the elements and re-run the layout on the
+  // live instance (keeping the instance, and its extensions, alive).
+  React.useEffect2(() => {
+    if pristine.current {
+      pristine.current = false
+    } else {
+      switch (cyRef.current, containerRef.current->Js.Nullable.toOption) {
+      | (Some(cy), Some(el)) =>
+        let (nodes, edges) = dataRef.current
+        let _ = Cy.remove(cy, Cy.elements(cy))
+        let _ = Cy.add(cy, elementsOf(~nodes, ~edges))
+        Cy.style(cy, stylesheet(~el, ~groups=GraphData.groupsOf(nodes)))
+        Cy.layout(cy, layoutFor(layout))->Cy.run
+      | _ => ()
+      }
+    }
+    None
+  }, (signature, layout))
+
+  // Theme switch → re-resolve the tokens and swap the whole stylesheet.
+  React.useEffect1(() => {
+    switch (cyRef.current, containerRef.current->Js.Nullable.toOption) {
+    | (Some(cy), Some(el)) =>
+      let (nodes, _) = dataRef.current
+      Cy.style(cy, stylesheet(~el, ~groups=GraphData.groupsOf(nodes)))
+    | _ => ()
+    }
+    None
+  }, [theme.preset])
+
+  if Array.length(nodes) == 0 {
+    <div style=Style.empty> {React.string("No relationships to graph.")} </div>
+  } else {
+    <div ref={ReactDOM.Ref.domRef(containerRef)} style={Style.wrap(~height)} />
+  }
+}

package/src/GraphView.res.mjs

@@ -0,0 +1,429 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as React from "react";
+import Cytoscape from "cytoscape";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import CytoscapeDagre from "cytoscape-dagre";
+import CytoscapeFcose from "cytoscape-fcose";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as JsxRuntime from "react/jsx-runtime";
+import * as Tokens$ReventlessUi from "@reventlessdev/reventless-ui/src/tokens/Tokens.res.mjs";
+import * as GraphData$ReventlessGraph from "./GraphData.res.mjs";
+import * as ThemeContext$ReventlessUi from "@reventlessdev/reventless-ui/src/tokens/ThemeContext.res.mjs";
+import * as CytoscapeBindings$Cytoscape from "@reventlessdev/rescript-cytoscape/src/CytoscapeBindings.res.mjs";
+
+let extensionsRegistered = {
+  contents: false
+};
+
+function ensureExtensions() {
+  if (!extensionsRegistered.contents) {
+    extensionsRegistered.contents = true;
+    CytoscapeBindings$Cytoscape.use(CytoscapeDagre);
+    return CytoscapeBindings$Cytoscape.use(CytoscapeFcose);
+  }
+}
+
+function tokenValue(el, token, fallback) {
+  let v = getComputedStyle(el).getPropertyValue(token).trim();
+  if (v === "") {
+    return fallback;
+  } else {
+    return v;
+  }
+}
+
+let literalPalette = [
+  "#7c9c5e",
+  "#b0743c",
+  "#7466a3",
+  "#4d8a8a",
+  "#a35f74"
+];
+
+function groupClass(group) {
+  return "grp-" + group.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+
+function elementsOf(nodes, edges) {
+  let ids = nodes.map(n => n.id);
+  let nodeEls = nodes.map(n => {
+    let g = n.group;
+    return {
+      data: {
+        id: n.id,
+        label: n.label
+      },
+      classes: g !== undefined ? groupClass(g) : ""
+    };
+  });
+  let edgeEls = edges.filter(e => {
+    if (ids.includes(e.from)) {
+      return ids.includes(e.to_);
+    } else {
+      return false;
+    }
+  }).map((e, i) => ({
+    data: {
+      id: "__edge__" + i.toString(),
+      source: e.from,
+      target: e.to_,
+      label: e.label
+    }
+  }));
+  return nodeEls.concat(edgeEls);
+}
+
+function stylesheet(el, groups) {
+  let brand = tokenValue(el, Tokens$ReventlessUi.Color.brand, "#3b6ea5");
+  let text = tokenValue(el, Tokens$ReventlessUi.Color.textPrimary, "#1a1a1a");
+  let border = tokenValue(el, Tokens$ReventlessUi.Color.border, "#d4d4d4");
+  let surface = tokenValue(el, Tokens$ReventlessUi.Color.surface, "#ffffff");
+  let colorFor = i => {
+    if (i === 0) {
+      return brand;
+    } else {
+      return literalPalette[Primitive_int.mod_(i - 1 | 0, literalPalette.length)];
+    }
+  };
+  let base = [
+    CytoscapeBindings$Cytoscape.rule("node", [
+      [
+        "background-color",
+        brand
+      ],
+      [
+        "border-width",
+        "2"
+      ],
+      [
+        "border-color",
+        surface
+      ],
+      [
+        "width",
+        "18"
+      ],
+      [
+        "height",
+        "18"
+      ],
+      [
+        "label",
+        "data(label)"
+      ],
+      [
+        "color",
+        text
+      ],
+      [
+        "font-size",
+        "11px"
+      ],
+      [
+        "text-valign",
+        "center"
+      ],
+      [
+        "text-halign",
+        "right"
+      ],
+      [
+        "text-margin-x",
+        "6"
+      ],
+      [
+        "text-wrap",
+        "ellipsis"
+      ],
+      [
+        "text-max-width",
+        "150"
+      ],
+      [
+        "min-zoomed-font-size",
+        "7"
+      ]
+    ]),
+    CytoscapeBindings$Cytoscape.rule("node:parent", [
+      [
+        "background-color",
+        border
+      ],
+      [
+        "background-opacity",
+        "0.12"
+      ],
+      [
+        "border-width",
+        "1"
+      ],
+      [
+        "border-color",
+        border
+      ],
+      [
+        "text-valign",
+        "top"
+      ],
+      [
+        "text-halign",
+        "center"
+      ],
+      [
+        "font-size",
+        "12px"
+      ],
+      [
+        "color",
+        text
+      ],
+      [
+        "padding",
+        "12"
+      ]
+    ]),
+    CytoscapeBindings$Cytoscape.rule("edge", [
+      [
+        "width",
+        "1.5"
+      ],
+      [
+        "line-color",
+        border
+      ],
+      [
+        "target-arrow-color",
+        border
+      ],
+      [
+        "target-arrow-shape",
+        "triangle"
+      ],
+      [
+        "arrow-scale",
+        "0.9"
+      ],
+      [
+        "curve-style",
+        "bezier"
+      ]
+    ])
+  ];
+  let groupRules = groups.map((g, i) => CytoscapeBindings$Cytoscape.rule("." + groupClass(g), [[
+      "background-color",
+      colorFor(i)
+    ]]));
+  return base.concat(groupRules);
+}
+
+function layoutFor(name) {
+  switch (name) {
+    case "breadthfirst" :
+      return {
+        name: "breadthfirst",
+        fit: true,
+        padding: 24,
+        animate: false,
+        spacingFactor: 1.1,
+        nodeDimensionsIncludeLabels: true,
+        directed: true
+      };
+    case "concentric" :
+      return {
+        name: "concentric",
+        fit: true,
+        padding: 24,
+        animate: false,
+        nodeDimensionsIncludeLabels: true,
+        minNodeSpacing: 40
+      };
+    case "cose" :
+      return {
+        name: "cose",
+        fit: true,
+        padding: 24,
+        animate: false,
+        idealEdgeLength: 90,
+        nodeRepulsion: 9000,
+        numIter: 800,
+        randomize: true,
+        componentSpacing: 80
+      };
+    case "dagre" :
+      return {
+        name: "dagre",
+        fit: true,
+        padding: 24,
+        animate: false,
+        nodeDimensionsIncludeLabels: true,
+        rankDir: "BT",
+        nodeSep: 28,
+        rankSep: 56
+      };
+    case "fcose" :
+      return {
+        name: "fcose",
+        fit: true,
+        padding: 24,
+        animate: false,
+        nodeDimensionsIncludeLabels: true,
+        idealEdgeLength: 80,
+        nodeRepulsion: 6000,
+        randomize: true,
+        quality: "proof",
+        nodeSeparation: 90,
+        gravityCompound: 1.5
+      };
+    default:
+      return {
+        name: name,
+        fit: true,
+        padding: 24,
+        animate: false
+      };
+  }
+}
+
+function v(token) {
+  return `var(` + token + `)`;
+}
+
+function wrap(height) {
+  return {
+    background: v(Tokens$ReventlessUi.Color.surface),
+    border: `1px solid ` + v(Tokens$ReventlessUi.Color.border),
+    height: height,
+    overflow: "hidden",
+    width: "100%",
+    borderRadius: v(Tokens$ReventlessUi.Radius.md)
+  };
+}
+
+let empty = {
+  color: v(Tokens$ReventlessUi.Color.textSecondary),
+  fontSize: v(Tokens$ReventlessUi.Typography.sizeSm),
+  padding: v(Tokens$ReventlessUi.Spacing.lg)
+};
+
+let Style = {
+  v: v,
+  wrap: wrap,
+  empty: empty
+};
+
+function signatureOf(nodes, edges) {
+  return nodes.map(n => n.id + `|` + n.label + `|` + Stdlib_Option.getOr(n.group, "")).join(",") + "//" + edges.map(e => e.from + `>` + e.to_).join(",");
+}
+
+function GraphView(props) {
+  let __height = props.height;
+  let __layout = props.layout;
+  let onOpenNode = props.onOpenNode;
+  let edges = props.edges;
+  let nodes = props.nodes;
+  let __layout_value = __layout !== undefined ? __layout : "dagre";
+  let __height_value = __height !== undefined ? __height : "520px";
+  let containerRef = React.useRef(null);
+  let cyRef = React.useRef(undefined);
+  let onOpenRef = React.useRef(onOpenNode);
+  onOpenRef.current = onOpenNode;
+  let dataRef = React.useRef([
+    nodes,
+    edges
+  ]);
+  dataRef.current = [
+    nodes,
+    edges
+  ];
+  let theme = ThemeContext$ReventlessUi.useTheme();
+  let signature = signatureOf(nodes, edges);
+  let pristine = React.useRef(true);
+  React.useEffect(() => {
+    let el = containerRef.current;
+    if (el == null) {
+      return;
+    }
+    ensureExtensions();
+    let cy = Cytoscape({
+      container: el,
+      elements: elementsOf(nodes, edges),
+      style: stylesheet(el, GraphData$ReventlessGraph.groupsOf(nodes)),
+      layout: layoutFor(__layout_value),
+      minZoom: 0.2,
+      maxZoom: 3.0
+    });
+    cy.on("tap", "node", e => Stdlib_Option.forEach(onOpenRef.current, f => f(CytoscapeBindings$Cytoscape.Event.targetId(e))));
+    cyRef.current = Primitive_option.some(cy);
+    let observer = new ResizeObserver(() => {
+      cy.resize();
+      cy.fit(24);
+    });
+    observer.observe(el);
+    return () => {
+      cyRef.current = undefined;
+      observer.disconnect();
+      cy.destroy();
+    };
+  }, []);
+  React.useEffect(() => {
+    if (pristine.current) {
+      pristine.current = false;
+    } else {
+      let match = cyRef.current;
+      let match$1 = containerRef.current;
+      if (match !== undefined && !(match$1 == null)) {
+        let cy = Primitive_option.valFromOption(match);
+        let match$2 = dataRef.current;
+        let nodes = match$2[0];
+        cy.remove(cy.elements());
+        cy.add(elementsOf(nodes, match$2[1]));
+        cy.style(stylesheet(match$1, GraphData$ReventlessGraph.groupsOf(nodes)));
+        cy.layout(layoutFor(__layout_value)).run();
+      }
+    }
+  }, [
+    signature,
+    __layout_value
+  ]);
+  React.useEffect(() => {
+    let match = cyRef.current;
+    let match$1 = containerRef.current;
+    if (match !== undefined && !(match$1 == null)) {
+      let match$2 = dataRef.current;
+      Primitive_option.valFromOption(match).style(stylesheet(match$1, GraphData$ReventlessGraph.groupsOf(match$2[0])));
+    }
+  }, [theme.preset]);
+  if (nodes.length === 0) {
+    return JsxRuntime.jsx("div", {
+      children: "No relationships to graph.",
+      style: empty
+    });
+  } else {
+    return JsxRuntime.jsx("div", {
+      ref: Primitive_option.some(containerRef),
+      style: wrap(__height_value)
+    });
+  }
+}
+
+let Cy;
+
+let make = GraphView;
+
+export {
+  Cy,
+  extensionsRegistered,
+  ensureExtensions,
+  tokenValue,
+  literalPalette,
+  groupClass,
+  elementsOf,
+  stylesheet,
+  layoutFor,
+  Style,
+  signatureOf,
+  make,
+}
+/* empty Not a pure module */