@reventlessdev/rescript-cytoscape 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,57 @@
+# @reventlessdev/rescript-cytoscape
+
+ReScript bindings for [Cytoscape.js](https://js.cytoscape.org/) — a narrow
+surface covering what a node-link view needs:
+
+- `Cytoscape.CytoscapeBindings.make({container, elements, style, layout, …})`
+  — an instance rendering into a container element.
+- Element descriptors: `nodeElement({data: {id, label, parent}})`,
+  `edgeElement({data: {id, source, target, label}})` (`parent` is cytoscape's
+  compound-node mechanism — clustering for free).
+- Stylesheets: `rule(~selector, [("background-color", "#333"), …])`, applied at
+  init or swapped wholesale with `style(cy, sheet)` (how a theme change lands).
+- Layouts: `layout(cy, {name: "dagre", rankDir: "BT"})->run`. Built-in names
+  are `grid` / `circle` / `concentric` / `breadthfirst` / `cose` / `preset`;
+  layered `dagre` and compound-aware `fcose` are extensions and need
+  `use(dagre)` / `use(fcose)` once, first.
+- Camera: `fit(cy, padding)`, `center`, `resize`, `zoom`/`setZoom`,
+  `pan`/`setPan` — cytoscape ships pan/zoom, nothing to build.
+- Events: `onSelector(cy, "tap", "node", e => Event.targetId(e))`.
+- Algorithms: `dijkstra`, `aStar`, `neighborhood`, `components`, `degree`.
+- `png(cy, {full: true})` → base64 data URI; `destroy(cy)` on unmount.
+
+The package carries **no Reventless and no React dependency** — the AutoUI
+graph view mode built on it lives in
+[`@reventlessdev/reventless-graph`](../../reventless/graph).
+
+## Setup
+
+```bash
+pnpm add @reventlessdev/rescript-cytoscape cytoscape cytoscape-dagre cytoscape-fcose
+```
+
+`rescript.json`:
+
+```json
+"dependencies": ["@reventlessdev/rescript-cytoscape"]
+```
+
+```rescript
+open Cytoscape.CytoscapeBindings
+
+use(dagre) // once, before the first instance that asks for these layouts
+use(fcose)
+```
+
+Cytoscape draws to a canvas and needs no stylesheet import; the container
+element must have a non-zero height.
+
+## 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. This package has no
+dependencies, so build it **first**, then reventless-graph, then
+reventless-ui **last** — building the downstream package walks into ui and
+deletes its dev-source `.res.mjs`, which only a ui `clean && build` restores.
+Never use `-with-deps` from a downstream package.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@reventlessdev/rescript-cytoscape",
+  "version": "0.1.0-alpha.1",
+  "description": "Cytoscape.js bindings for ReScript. The minimal surface (graph init, element builders, stylesheets, layouts, camera, events, graph algorithms, PNG export). Framework-agnostic — the Reventless AutoUI graph view mode lives in @reventlessdev/reventless-graph.",
+  "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": "echo \"no test specified\""
+  },
+  "devDependencies": {
+    "cytoscape": "^3.34.0",
+    "cytoscape-dagre": "^4.0.0",
+    "cytoscape-fcose": "^2.2.0",
+    "rescript": "^12.3.0"
+  },
+  "peerDependencies": {
+    "cytoscape": ">=3.30.0",
+    "cytoscape-dagre": ">=2.5.0",
+    "cytoscape-fcose": ">=2.2.0",
+    "rescript": "^12.3.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "gitHead": "ee9a72b1a1f76e7fdeab58922e4fb653a1b20cec"
+}

package/rescript.json

@@ -0,0 +1,9 @@
+{
+  "name": "@reventlessdev/rescript-cytoscape",
+  "namespace": "Cytoscape",
+  "sources": [{ "dir": "src", "subdirs": true }],
+  "package-specs": { "module": "esmodule", "in-source": true },
+  "suffix": ".res.mjs",
+  "warnings": { "number": "-3" },
+  "dependencies": []
+}

package/src/CytoscapeBindings.res

@@ -0,0 +1,227 @@
+// Minimal cytoscape bindings — only what the AutoUI graph view mode
+// (@reventlessdev/reventless-graph) and its stories need: instance init,
+// element descriptors, stylesheets, layouts, the built-in camera, tap events,
+// the handful of graph algorithms we surface, and PNG export.
+//
+// Cytoscape is imperative and framework-agnostic (it owns a canvas inside a
+// container element), so this binds like the maplibre package: no React, no
+// Reventless. Style values travel as strings — cytoscape parses numeric
+// properties out of strings, and every property we set is expressible that
+// way, which keeps the stylesheet a plain (selector, declarations) pair
+// instead of a typed pyramid.
+
+type t // a cytoscape instance
+type collection // one or more elements (nodes and/or edges)
+type element // an element descriptor handed to cytoscape
+type extension // a registrable extension (cytoscape-dagre, …)
+
+// ─── Elements ────────────────────────────────────────────────────────────
+
+type nodeData = {
+  id: string,
+  label?: string,
+  parent?: string, // compound parent node id — the clustering mechanism
+}
+
+type edgeData = {
+  id: string,
+  source: string,
+  target: string,
+  label?: string,
+}
+
+type nodeSpec = {data: nodeData, classes?: string}
+type edgeSpec = {data: edgeData, classes?: string}
+
+// Descriptors are plain objects; the casts exist so `elements` can hold both.
+external nodeElement: nodeSpec => element = "%identity"
+external edgeElement: edgeSpec => element = "%identity"
+
+// ─── Stylesheet ──────────────────────────────────────────────────────────
+
+type styleRule = {
+  selector: string,
+  style: Js.Dict.t<string>,
+}
+
+let rule = (~selector: string, declarations: array<(string, string)>): styleRule => {
+  selector,
+  style: Js.Dict.fromArray(declarations),
+}
+
+// ─── Layout ──────────────────────────────────────────────────────────────
+
+// One record for every layout: cytoscape ignores options a layout doesn't
+// know, so `{name: "dagre", rankDir: "TB"}` and `{name: "concentric"}` share
+// a type. Built-in names: grid, circle, concentric, breadthfirst, cose,
+// random, preset. `dagre` needs `use(dagre)` first.
+type layoutOptions = {
+  name: string,
+  fit?: bool,
+  padding?: int,
+  animate?: bool,
+  animationDuration?: int,
+  spacingFactor?: float,
+  nodeDimensionsIncludeLabels?: bool,
+  // dagre
+  rankDir?: string, // "TB" | "BT" | "LR" | "RL"
+  nodeSep?: int,
+  rankSep?: int,
+  edgeSep?: int,
+  // breadthfirst
+  directed?: bool,
+  roots?: string,
+  circle?: bool,
+  // concentric
+  minNodeSpacing?: int,
+  // cose (the built-in force layout) / fcose
+  idealEdgeLength?: int,
+  nodeRepulsion?: int,
+  gravity?: float,
+  // Multiplies the ideal edge length for edges that cross a compound
+  // boundary — how far apart cluster boxes are pushed.
+  nestingFactor?: float,
+  numIter?: int,
+  randomize?: bool,
+  componentSpacing?: int,
+  // fcose only
+  quality?: string, // "draft" | "default" | "proof"
+  nodeSeparation?: int,
+  gravityCompound?: float,
+  packComponents?: bool,
+}
+
+type layout
+
+// ─── Instance ────────────────────────────────────────────────────────────
+
+type options = {
+  container: Dom.element,
+  elements: array<element>,
+  style?: array<styleRule>,
+  layout?: layoutOptions,
+  minZoom?: float,
+  maxZoom?: float,
+  wheelSensitivity?: float,
+  autoungrabify?: bool,
+}
+
+@module("cytoscape") external make: options => t = "default"
+
+// `cytoscape.use(ext)` registers an extension globally — call once, before
+// the first `make` that names its layout.
+type lib
+@module("cytoscape") external lib: lib = "default"
+@send external useExtension: (lib, extension) => unit = "use"
+let use = (ext: extension): unit => lib->useExtension(ext)
+
+@module("cytoscape-dagre") external dagre: extension = "default"
+// fcose is the compound-aware force layout — the built-in `cose` piles
+// cluster boxes on top of each other.
+@module("cytoscape-fcose") external fcose: extension = "default"
+
+@send external destroy: t => unit = "destroy"
+
+// ─── Collections ─────────────────────────────────────────────────────────
+
+@send external elements: t => collection = "elements"
+@send external nodes: t => collection = "nodes"
+@send external edges: t => collection = "edges"
+@send external getElementById: (t, string) => collection = "getElementById"
+// Selector query, e.g. cy->query("node[kind = 'Order']").
+@send external query: (t, string) => collection = "$"
+
+@send external id: collection => string = "id"
+@send external size: collection => int = "size"
+@send external map: (collection, collection => 'a) => array<'a> = "map"
+@send external forEach: (collection, collection => unit) => unit = "forEach"
+@send external addClass: (collection, string) => collection = "addClass"
+@send external removeClass: (collection, string) => collection = "removeClass"
+@send external dataAt: (collection, string) => Js.Json.t = "data"
+// Writing a computed value back into element data is how a derived metric
+// (degree centrality, a score) becomes available to `mapData(…)` in a style.
+@send external setDataAt: (collection, string, Js.Json.t) => collection = "data"
+// Neighbours reached in either direction; `closed` includes the node itself.
+@send external neighborhood: collection => collection = "neighborhood"
+@send external closedNeighborhood: collection => collection = "closedNeighborhood"
+@send external union: (collection, collection) => collection = "union"
+@send external difference: (collection, collection) => collection = "difference"
+// Degree centrality of the collection's first element.
+@send external degree: (collection, bool) => int = "degree"
+// Connected components, one collection each.
+@send external components: collection => array<collection> = "components"
+
+@send external add: (t, array<element>) => collection = "add"
+@send external remove: (t, collection) => collection = "remove"
+@send external removeSelector: (t, string) => collection = "remove"
+
+// Replaces the whole stylesheet — how a theme change is applied.
+@send external style: (t, array<styleRule>) => unit = "style"
+
+@send external layout: (t, layoutOptions) => layout = "layout"
+@send external run: layout => unit = "run"
+@send external stop: layout => unit = "stop"
+
+// ─── Camera ──────────────────────────────────────────────────────────────
+
+type position = {x: float, y: float}
+
+// cy.fit(padding) — the number arity fits every element with that padding.
+@send external fit: (t, int) => unit = "fit"
+@send external fitTo: (t, collection, int) => unit = "fit"
+@send external center: t => unit = "center"
+// Re-reads the container size; call after the container box changes.
+@send external resize: t => unit = "resize"
+@send external zoom: t => float = "zoom"
+@send external setZoom: (t, float) => unit = "zoom"
+@send external pan: t => position = "pan"
+@send external setPan: (t, position) => unit = "pan"
+
+// ─── Events ──────────────────────────────────────────────────────────────
+
+type event
+
+// Graph-wide ("tap" on the background included).
+@send external on: (t, string, event => unit) => unit = "on"
+// Delegated to elements matching a selector, e.g. on(cy, "tap", "node", …).
+@send external onSelector: (t, string, string, event => unit) => unit = "on"
+
+module Event = {
+  @get external target: event => collection = "target"
+  // The tapped element's id — the row key the graph mode drills through.
+  let targetId = (e: event): string => e->target->id
+}
+
+// ─── Algorithms ──────────────────────────────────────────────────────────
+
+type dijkstraOptions = {
+  root: string, // selector, e.g. "#e1"
+  directed?: bool,
+}
+type dijkstraResult
+@send external dijkstra: (collection, dijkstraOptions) => dijkstraResult = "dijkstra"
+@send external distanceTo: (dijkstraResult, collection) => float = "distanceTo"
+// The nodes and edges of the shortest path, in order.
+@send external pathTo: (dijkstraResult, collection) => collection = "pathTo"
+
+type aStarOptions = {
+  root: string,
+  goal: string,
+  directed?: bool,
+}
+type aStarResult = {
+  found: bool,
+  distance: float,
+  path: collection,
+}
+@send external aStar: (collection, aStarOptions) => aStarResult = "aStar"
+
+// ─── Export ──────────────────────────────────────────────────────────────
+
+type pngOptions = {
+  full?: bool, // whole graph rather than the current viewport
+  scale?: float,
+  bg?: string,
+}
+// Returns a base64 data URI.
+@send external png: (t, pngOptions) => string = "png"

package/src/CytoscapeBindings.res.mjs

@@ -0,0 +1,30 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Js_dict from "@rescript/runtime/lib/es6/Js_dict.js";
+import Cytoscape from "cytoscape";
+
+function rule(selector, declarations) {
+  return {
+    selector: selector,
+    style: Js_dict.fromArray(declarations)
+  };
+}
+
+function use(ext) {
+  Cytoscape.use(ext);
+}
+
+function targetId(e) {
+  return e.target.id();
+}
+
+let Event = {
+  targetId: targetId
+};
+
+export {
+  rule,
+  use,
+  Event,
+}
+/* cytoscape Not a pure module */