@graphty/graph-io 0.3.48 → 0.3.49

package/src/formats/graphml/yfiles.ts

@@ -171,9 +171,9 @@ function wantedGraphics(trees: JsonColumn[], domain: "node" | "edge", field: str
 
 /**
  * The mapped values of one `<data>` tree of a yFiles key: a ShapeNode's for a node, a
- * PolyLineEdge's for an edge. A GenericNode, ImageNode, SVGNode or ProxyAutoBoundsNode (a group,
- * read through the realizer `Realizers@active` names) gives its geometry only: position, width and
- * height. Nothing for any other graphics (BezierEdge, ...).
+ * PolyLineEdge's for an edge. A GenericNode, ImageNode, SVGNode, UMLClassNode, UMLNoteNode, TableNode
+ * or ProxyAutoBoundsNode (a group, read through the realizer `Realizers@active` names), and yFiles 3's
+ * NodeGeometry `RectD`, give their geometry only: position, width and height. Nothing for any other graphics (BezierEdge, ...).
  * @param domain - node or edge
  * @param tree - the `<data>` content as tree.ts builds it
  * @param unmapped - receives the fields whose text is present but not a number (not mapped)
@@ -184,7 +184,20 @@ export function graphicsValues(domain: "node" | "edge", tree: unknown, unmapped:
     const out: [string, unknown][] = [];
     if (domain === "node") {
         const shape = child(tree, "ShapeNode");
-        if (shape === undefined) {
+        const rect = child(tree, "RectD");
+        if (rect !== undefined) {
+            // yFiles 3's NodeGeometry: the same top-left corner and size as yEd's Geometry, capitalized
+            geometryValues(
+                {
+                    "@_x": attr(rect, "X"),
+                    "@_y": attr(rect, "Y"),
+                    "@_width": attr(rect, "Width"),
+                    "@_height": attr(rect, "Height"),
+                },
+                out,
+                unmapped,
+            );
+        } else if (shape === undefined) {
             geometryValues(child(geometryNode(tree), "Geometry"), out, unmapped);
         } else {
             shapeNodeValues(shape, out, unmapped);
@@ -237,10 +250,10 @@ function geometryValues(geometry: unknown, out: [string, unknown][], unmapped: s
 }
 
 /** The node graphics besides ShapeNode whose Geometry is read. */
-const GEOMETRY_NODES = ["GenericNode", "ImageNode", "SVGNode"] as const;
+const GEOMETRY_NODES = ["GenericNode", "ImageNode", "SVGNode", "UMLClassNode", "UMLNoteNode", "TableNode"] as const;
 
 /**
- * The element holding a non-ShapeNode node's Geometry: a GenericNode, ImageNode or SVGNode, or
+ * The element holding a non-ShapeNode node's Geometry: one of GEOMETRY_NODES, or
  * the active realizer of a ProxyAutoBoundsNode (`Realizers@active`, default 0).
  * @param tree - the `<data>` content
  * @returns the element, or undefined

package/src/formats/json/dialect.ts

@@ -148,11 +148,12 @@ export function isJsonImportDialect(value: unknown): value is JsonImportDialect
 }
 
 /**
- * The dialect of a parsed JSON document, by the shape rules of design section 8.2 (Cytoscape:
+ * The dialect of a parsed JSON document, told by its shape (Cytoscape:
  * `elements` or a top-level array of `{ data }` elements; OBO Graphs: `graphs[]` whose first graph
  * has an edge with `sub` (or `subj`) and `obj` or a `pred`, or a node with `lbl`, `meta` or an OWL
  * `type`; JGF: `graph.nodes` / `graph.edges` or any other `graphs[]`; graphology: `options.type` / `options.multi`, `key` nodes without `id`, edges with
- * `undirected` or an `attributes` record, and vis: edges with `from` / `to`, both only without
+ * `undirected` or an `attributes` record, and vis: edges with `from` / `to`, or no edge record and an `options`
+ * object holding a vis-network option group (`nodes`, `edges`, `groups`, `physics`, ...), both only without
  * NetworkX's `links` / `directed` / `multigraph` / `graph` keys; d3: `links` without
  * `directed` / `multigraph` / `graph`; NetworkX adjacency_data: `nodes` and `adjacency` without
  * `links` / `edges`; NetworkX tree_data: `children` without `nodes` / `links` / `edges`; else
@@ -229,14 +230,46 @@ function sniffEdgeListDialect(root: Record<string, unknown>): JsonImportDialect
     if (record !== undefined) {
         return record;
     }
+    // vis: a `{ nodes, edges, options }` document with no edge record still carries vis-network's options
+    if (!networkx && firstEdge === null && isVisOptions(root.options)) {
+        return "vis";
+    }
     const bare = !hasKey(root, "directed") && !hasKey(root, "multigraph") && !hasKey(root, "graph");
     return bare && hasKey(root, "links") ? "d3" : "node-link";
 }
 
+/** vis-network's top-level option groups (https://visjs.github.io/vis-network/docs/network/#options). */
+const VIS_OPTION_GROUPS = [
+    "nodes",
+    "edges",
+    "groups",
+    "physics",
+    "layout",
+    "interaction",
+    "manipulation",
+    "configure",
+    "autoResize",
+    "clickToUse",
+    "locale",
+    "locales",
+    "height",
+    "width",
+];
+
+/**
+ * Whether a document's `options` is vis-network's: an object holding one of its top-level option groups.
+ * @param options - the document's `options`
+ * @returns true for vis-network options
+ */
+function isVisOptions(options: unknown): boolean {
+    return isJsonObject(options) && VIS_OPTION_GROUPS.some((k) => hasKey(options, k));
+}
+
 /**
  * The graphology or vis dialect, read from the first node and edge records of a document without
- * NetworkX's keys: graphology for a `key` node without `id`, or an edge without `from` that has
- * `undirected` or an `attributes` record; vis for an edge with `from` and `to` but no `source`.
+ * NetworkX's keys: graphology for a `key` node without `id`, an edge without `from` that has
+ * `undirected` or an `attributes` record, or, with no edges, an `id` node with an `attributes` record
+ * (Gephi's JSON export); vis for an edge with `from` and `to` but no `source`.
  * @param firstNode - the first node record, or null
  * @param firstEdge - the first edge record, or null
  * @returns the dialect, or undefined when the records name neither
@@ -249,7 +282,10 @@ function sniffRecordDialect(
         return "graphology";
     }
     if (firstEdge === null) {
-        return undefined;
+        // Gephi's JSON export of a graph with no edges: its nodes still carry the exporter's `attributes` record
+        return firstNode !== null && hasKey(firstNode, "id") && isJsonObject(firstNode.attributes)
+            ? "graphology"
+            : undefined;
     }
     if (!hasKey(firstEdge, "from")) {
         return hasKey(firstEdge, "undirected") || isJsonObject(firstEdge.attributes) ? "graphology" : undefined;

package/src/formats/json/importer.ts

@@ -128,7 +128,7 @@ import {
 } from "./dialect.js";
 import { importObographs } from "./obographs.js";
 import { jsonPositions } from "./positions.js";
-import { jsonStyles, type JsonStyleSource } from "./styles.js";
+import { jsonStyles, type JsonStyleSource, SIGMA_DEFAULT_SETTINGS, type SigmaSettings } from "./styles.js";
 
 /**
  * The format-specific options of the JSON importer. `graphIndex` / `graphName` choose one graph of
@@ -204,6 +204,13 @@ export interface JsonImportOptions extends GraphChoiceOptions, CommonImportOptio
      * @defaultValue next to the nodes
      */
     edgesPath?: string | undefined;
+    /**
+     * graphology and Gephi JSON documents: the sigma.js settings the graph is drawn with, which are the application's
+     * and never in the file. `renderEdgeLabels: true` draws the edges' labels, between two labeled nodes or, with
+     * `edgeLabelAnchors: "allNodes"`, on every edge; other settings are accepted and not read.
+     * @defaultValue sigma.js's own settings (no edge labels)
+     */
+    sigmaSettings?: Readonly<Record<string, unknown>> | undefined;
 }
 
 /**
@@ -408,6 +415,15 @@ const GEPHI_NODE_KEYS: ReadonlySet<string> = new Set(["id", "attributes"]);
 /** The structural keys of an edge in Gephi's JSON export. */
 const GEPHI_EDGE_KEYS: ReadonlySet<string> = new Set([...GRAPHOLOGY_EDGE_KEYS, "id"]);
 
+/**
+ * The keys Gephi's JSON export writes beside a node's `attributes`, the ones sigma.js draws: a Gephi column named
+ * like one of them is data under `attributes`, read as `<key>#data` so it never stands in for the element's own key.
+ */
+const GEPHI_NODE_DISPLAY_KEYS: ReadonlySet<string> = new Set(["label", "x", "y", "size", "color"]);
+
+/** The keys Gephi's JSON export writes beside an edge's `attributes` (see GEPHI_NODE_DISPLAY_KEYS). */
+const GEPHI_EDGE_DISPLAY_KEYS: ReadonlySet<string> = new Set(["label", "size", "color"]);
+
 /** The vis.js endpoint keys. */
 const VIS_SOURCE_KEYS: readonly string[] = Object.freeze(["from"]);
 const VIS_TARGET_KEYS: readonly string[] = Object.freeze(["to"]);
@@ -452,6 +468,8 @@ interface ResolvedJsonOptions {
     readonly edgesPath: readonly string[] | null;
     /** Set by importAll(): every graph of a `graphs` array is read, so none is reported as skipped. */
     readonly all?: boolean;
+    /** graphology: the sigma.js settings of the drawing. */
+    readonly sigma: SigmaSettings;
 }
 
 /**
@@ -499,9 +517,32 @@ function resolveJsonOptions(options: (JsonImportOptions & CommonImportOptions) |
         typedefs,
         nodesPath,
         edgesPath,
+        sigma: sigmaSettingsOption(o.sigmaSettings),
     };
 }
 
+/**
+ * Check the `sigmaSettings` option: an object, whose `renderEdgeLabels` and `edgeLabelAnchors` are sigma's values.
+ * @param value - the caller's value
+ * @returns the settings graph-io reads, sigma's own where not given
+ */
+function sigmaSettingsOption(value: unknown): SigmaSettings {
+    if (value === undefined) {
+        return SIGMA_DEFAULT_SETTINGS;
+    }
+    if (!isJsonObject(value)) {
+        throw unsupportedOption("sigmaSettings", value, ["an object of sigma.js settings"]);
+    }
+    const { renderEdgeLabels = false, edgeLabelAnchors = "nodeLabels" } = value;
+    if (typeof renderEdgeLabels !== "boolean") {
+        throw unsupportedOption("sigmaSettings.renderEdgeLabels", renderEdgeLabels, ["true", "false"]);
+    }
+    if (edgeLabelAnchors !== "nodeLabels" && edgeLabelAnchors !== "allNodes") {
+        throw unsupportedOption("sigmaSettings.edgeLabelAnchors", edgeLabelAnchors, ["nodeLabels", "allNodes"]);
+    }
+    return { renderEdgeLabels, edgeLabelAnchors };
+}
+
 /**
  * Check a dotted path option: object keys joined by dots, none of them empty.
  * @param name - the option name
@@ -1326,9 +1367,10 @@ export class ImportContext {
      * @param structural - the element keys that are not attributes
      * @param element - the element name for issues
      * @param how - `weightFrom`: the weight key to skip in the dict; `plain`: write the element-level keys under their
-     * own names, not with the `#element` suffix
+     * own names, not with the `#element` suffix; `dataKeys`: the dict keys written with the `#data` suffix
      * @param how.weightFrom - the weight key to skip in the dict, or null (the default)
      * @param how.plain - write the element-level keys under their own names (default false)
+     * @param how.dataKeys - the dict keys that name an element-level key, written as `<key>#data` (default none)
      */
     writeNested(
         writer: AttributeWriter,
@@ -1337,12 +1379,17 @@ export class ImportContext {
         dict: JsonRecord,
         structural: ReadonlySet<string>,
         element: string,
-        how: { readonly weightFrom?: string | null; readonly plain?: boolean } = {},
+        how: {
+            readonly weightFrom?: string | null;
+            readonly plain?: boolean;
+            readonly dataKeys?: ReadonlySet<string>;
+        } = {},
     ): void {
-        const { weightFrom = null, plain = false } = how;
+        const { weightFrom = null, plain = false, dataKeys } = how;
         for (const key of Object.keys(dict)) {
             if (key !== weightFrom) {
-                writer.write(row, key, dict[key], SUFFIX.data, element);
+                const name = dataKeys?.has(key) === true ? `${key}${SUFFIX.data}` : key;
+                writer.write(row, name, dict[key], SUFFIX.data, element);
             }
         }
         for (const key of Object.keys(record)) {
@@ -2797,7 +2844,7 @@ function importGraphology(ctx: ImportContext, root: JsonRecord): void {
     // `y`, `color`, `size`) beside `attributes`; they are read as attributes, not as unknown element keys
     const firstNode = nodes.find((n) => isJsonObject(n));
     const gephi = isJsonObject(firstNode) && !hasKey(firstNode, "key") && hasKey(firstNode, "id");
-    ctx.styleSource = { dialect: "graphology", block: blockOf(root), gephi };
+    ctx.styleSource = { dialect: "graphology", block: blockOf(root), gephi, sigma: ctx.json.sigma };
     ctx.reportNodeIdFrom("graphology", "the node key");
     ctx.sink.reserve(nodes.length, edges.length);
 
@@ -2989,6 +3036,7 @@ function pushGraphologyEdge(
     ctx.writeNested(ctx.edges, edge, record, attributes, gephi ? GEPHI_EDGE_KEYS : GRAPHOLOGY_EDGE_KEYS, element, {
         weightFrom: ctx.options.weightFrom,
         plain: gephi,
+        dataKeys: gephi ? GEPHI_EDGE_DISPLAY_KEYS : undefined,
     });
     if (declared.allowSelfLoops === false && u === v) {
         violations.selfLoops++;
@@ -3069,7 +3117,10 @@ function pushNestedNode(
                 { element },
             );
         }
-        ctx.writeNested(ctx.nodes, index, record, isJsonObject(dict) ? dict : {}, structural, element, { plain });
+        ctx.writeNested(ctx.nodes, index, record, isJsonObject(dict) ? dict : {}, structural, element, {
+            plain,
+            dataKeys: plain ? GEPHI_NODE_DISPLAY_KEYS : undefined,
+        });
     } catch (err) {
         ctx.report.recordError(err, { element: String(id) });
     }
@@ -4267,6 +4318,7 @@ export const jsonImporter: GraphImporter<JsonImportOptions> = Object.freeze({
         "nodeIdKey",
         "nodesPath",
         "oboIds",
+        "sigmaSettings",
         "sourceKey",
         "targetKey",
         "typedefs",

package/src/formats/json/index.ts

@@ -11,6 +11,7 @@ export {
     type JsonImportDialect,
     type JsonShapeMeta,
     jsonShapeOf,
+    sniffJsonDialect,
 } from "./dialect.js";
 export { JSON_LOSS, jsonCapabilities, jsonExporter, type JsonExportOptions } from "./exporter.js";
 export { JSON_ISSUE, jsonImporter, type JsonImportOptions } from "./importer.js";

package/src/formats/json/positions.ts

@@ -3,12 +3,23 @@
  * document has a role-`position` column the importer already flipped to y up. A plain
  * `{ nodes: [{ x, y }] }` file is read as graphty-element's own convention (center, y up, file
  * units) and never flipped, unless it carries a positive marker of a y-down tool: d3-force's
- * simulation keys (`vx`, `vy`, `fx`, `fy`, `index`) or vis's `physics`.
+ * simulation keys (`vx`, `vy`, `fx`, `fy`, `index`) or vis's `physics`. A vis-network document
+ * (edges with `from` / `to`) is always y down in canvas px: vis-network draws `x` / `y` straight onto
+ * its canvas. A Cytoscape compound node's saved position is not read: Cytoscape.js draws a compound
+ * around its children.
  */
 
 import type { Column, GraphSnapshot } from "@graphty/graph-format";
 
-import type { ImporterPositions } from "../../positions/types.js";
+import type { ImporterPositions, ViewerFit } from "../../positions/types.js";
+import { jsonShapeOf } from "./dialect.js";
+
+/**
+ * How sigma.js fits a graphology graph into its canvas: the bounding box of the positions, 30 px in
+ * from each side, with node sizes in the positions' unit and label sizes in the canvas's px
+ * (sigma 4.0.1 settings: `stagePadding: 30`, `itemSizesReference: "positions"`, `autoRescale: true`).
+ */
+const SIGMA_FIT: ViewerFit = { padding: 30 };
 
 /** Node keys that mark a y-down drawing. */
 const Y_DOWN_MARKERS = ["vx", "vy", "fx", "fy", "index", "physics"] as const;
@@ -16,11 +27,12 @@ const Y_DOWN_MARKERS = ["vx", "vy", "fx", "fy", "index", "physics"] as const;
 /**
  * The spelling of a JSON file's positions.
  * @param snapshot - the graph the JSON importer read
- * @returns the plain x / y columns, or null to read the role-`position` column as declared
+ * @returns the plain x / y columns, the role-`position` column's spelling, or null to read that column as declared
  */
 export function jsonPositions(snapshot: GraphSnapshot): ImporterPositions | null {
     if (snapshot.nodes.byRole("position") !== null) {
-        return null;
+        // cy.json() saves a compound node's position too, but Cytoscape.js draws the compound around its children
+        return jsonShapeOf(snapshot)?.dialect === "cytoscape" ? { containersFollowChildren: true } : null;
     }
     const x = numeric(snapshot.nodes.get("x"));
     const y = numeric(snapshot.nodes.get("y"));
@@ -29,13 +41,18 @@ export function jsonPositions(snapshot: GraphSnapshot): ImporterPositions | null
     }
     const z = numeric(snapshot.nodes.get("z"));
     // a z means a 3D drawing (3d-force-graph), drawn y up even with the d3 keys
-    const down = z === null && Y_DOWN_MARKERS.some((name) => snapshot.nodes.get(name) !== null);
+    const dialect = jsonShapeOf(snapshot)?.dialect;
+    // sigma.js draws every graphology file y up: d3-force's keys in one do not make it a d3 drawing
+    // (graphology-specimen-node-sizes-opacity-p3)
+    const markers = dialect !== "graphology" && Y_DOWN_MARKERS.some((name) => snapshot.nodes.get(name) !== null);
+    const down = z === null && (dialect === "vis" || markers);
     return {
         x: x.meta.name,
         y: y.meta.name,
         ...(z === null ? {} : { z: z.meta.name }),
         yAxis: down ? "down" : "up",
         units: down ? "px" : "file",
+        ...(dialect === "graphology" ? { viewerFit: SIGMA_FIT } : {}),
     };
 }