@graphty/graph-io 0.3.43 → 0.3.44

package/src/formats/graphml/yfiles.ts

@@ -14,11 +14,16 @@
  * re-importing the tree gives them back. A value edited after import (a layout writing the
  * position) or a tree column removed is therefore not written, and the exporter reports it as a
  * loss (staleGraphicsRows()).
+ *
+ * Deprecated and frozen, not fixed: these columns, the rule that a target arrow makes an edge
+ * directed and the label role of `yfiles.label` stay exactly as they are until the next major
+ * version removes them. The yEd and yFiles 3 style readers read the kept graphics tree instead.
  */
 
-import { type Column, type ColumnDecl, type JsonColumn } from "@graphty/graph-format";
+import { type Column, type ColumnDecl, type GraphSnapshot, type JsonColumn } from "@graphty/graph-format";
 
 import { localName } from "../../common/xml.js";
+import type { ImporterPositions } from "../../positions/types.js";
 
 /** The name prefix of every column mapped from yFiles graphics. */
 const YFILES_COLUMN_PREFIX = "yfiles.";
@@ -27,7 +32,20 @@ type Tree = Record<string, unknown>;
 
 /** The mapped node columns, by the field name graphty-element's records use. */
 const NODE_FIELDS: Readonly<Record<string, Omit<ColumnDecl, "name">>> = {
-    position: { dtype: "f64", components: 3, role: "position", mutable: true },
+    // yEd writes the top-left corner of the node's box, y growing downward, in pixels
+    position: {
+        dtype: "f64",
+        components: 3,
+        role: "position",
+        mutable: true,
+        extra: {
+            units: "px",
+            yAxis: "down",
+            anchor: "top-left",
+            width: `${YFILES_COLUMN_PREFIX}width`,
+            height: `${YFILES_COLUMN_PREFIX}height`,
+        },
+    },
     width: { dtype: "f64" },
     height: { dtype: "f64" },
     color: { dtype: "string" },
@@ -70,6 +88,16 @@ export function graphicsDecl(domain: "node" | "edge", field: string, keyId: stri
     };
 }
 
+/**
+ * The tool behind a GraphML file's positions, for `extractPositions()`: yEd when they come from
+ * yFiles graphics. The column's `meta.extra` already says how they are spelled.
+ * @param snapshot - the graph the GraphML importer read
+ * @returns the tool, or null to read the position column as declared
+ */
+export function yfilesPositions(snapshot: GraphSnapshot): ImporterPositions | null {
+    return snapshot.nodes.byRole("position")?.meta.origin?.namespace === "yfiles" ? { tool: "yed" } : null;
+}
+
 /**
  * Whether a column is one graphicsDecl() declared (a view of a yFiles tree, never exported).
  * @param meta - the column's name, dtype and origin
@@ -143,7 +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; nothing for any other graphics (GenericNode, BezierEdge, ...).
+ * 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, ...).
  * @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)
@@ -154,7 +184,9 @@ export function graphicsValues(domain: "node" | "edge", tree: unknown, unmapped:
     const out: [string, unknown][] = [];
     if (domain === "node") {
         const shape = child(tree, "ShapeNode");
-        if (shape !== undefined) {
+        if (shape === undefined) {
+            geometryValues(child(geometryNode(tree), "Geometry"), out, unmapped);
+        } else {
             shapeNodeValues(shape, out, unmapped);
         }
     } else {
@@ -173,15 +205,7 @@ export function graphicsValues(domain: "node" | "edge", tree: unknown, unmapped:
  * @param unmapped - receives the fields whose text is not a number
  */
 function shapeNodeValues(shape: unknown, out: [string, unknown][], unmapped: string[]): void {
-    const geometry = child(shape, "Geometry");
-    // yFiles requires x, y, width and height on Geometry; a position needs both coordinates
-    const x = checked(attr(geometry, "x"), "x", unmapped);
-    const y = checked(attr(geometry, "y"), "y", unmapped);
-    if (x !== undefined && y !== undefined) {
-        out.push(["position", [x, y, 0]]);
-    }
-    push(out, "width", checked(attr(geometry, "width"), "width", unmapped));
-    push(out, "height", checked(attr(geometry, "height"), "height", unmapped));
+    geometryValues(child(shape, "Geometry"), out, unmapped);
     push(out, "color", color(attr(child(shape, "Fill"), "color")));
     const border = child(shape, "BorderStyle");
     push(out, "borderColor", color(attr(border, "color")));
@@ -195,6 +219,58 @@ function shapeNodeValues(shape: unknown, out: [string, unknown][], unmapped: str
     push(out, "shape", nonEmpty(attr(child(shape, "Shape"), "type")));
 }
 
+/**
+ * Read a Geometry: the position of the box's top-left corner, its width and height.
+ * @param geometry - the Geometry element, or undefined
+ * @param out - receives the values
+ * @param unmapped - receives the fields whose text is not a number
+ */
+function geometryValues(geometry: unknown, out: [string, unknown][], unmapped: string[]): void {
+    // yFiles requires x, y, width and height on Geometry; a position needs both coordinates
+    const x = checked(attr(geometry, "x"), "x", unmapped);
+    const y = checked(attr(geometry, "y"), "y", unmapped);
+    if (x !== undefined && y !== undefined) {
+        out.push(["position", [x, y, 0]]);
+    }
+    push(out, "width", checked(attr(geometry, "width"), "width", unmapped));
+    push(out, "height", checked(attr(geometry, "height"), "height", unmapped));
+}
+
+/** The node graphics besides ShapeNode whose Geometry is read. */
+const GEOMETRY_NODES = ["GenericNode", "ImageNode", "SVGNode"] as const;
+
+/**
+ * The element holding a non-ShapeNode node's Geometry: a GenericNode, ImageNode or SVGNode, or
+ * the active realizer of a ProxyAutoBoundsNode (`Realizers@active`, default 0).
+ * @param tree - the `<data>` content
+ * @returns the element, or undefined
+ */
+function geometryNode(tree: unknown): unknown {
+    for (const local of GEOMETRY_NODES) {
+        const node = child(tree, local);
+        if (node !== undefined) {
+            return node;
+        }
+    }
+    const realizers = child(child(tree, "ProxyAutoBoundsNode"), "Realizers");
+    const active = Number.parseInt(attr(realizers, "active") ?? "0", 10);
+    return elements(realizers)[Number.isNaN(active) ? 0 : active];
+}
+
+/**
+ * Every child element of a tree node, in document order per name.
+ * @param node - the tree node
+ * @returns the children
+ */
+function elements(node: unknown): unknown[] {
+    if (typeof node !== "object" || node === null) {
+        return [];
+    }
+    return Object.entries(node as Tree)
+        .filter(([key]) => !key.startsWith("@_") && key !== "#text")
+        .flatMap(([, value]) => (Array.isArray(value) ? (value as unknown[]) : [value]));
+}
+
 /**
  * Read a PolyLineEdge.
  * @param edge - the PolyLineEdge element

package/src/formats/json/exporter.ts

@@ -29,6 +29,8 @@ import { otherFormatDialect, type ResolvedExportOptions, resolveExportOptions }
 import { agree, plural } from "../../common/plural.js";
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, indentUnit, joinText } from "../../common/writer.js";
+import { STYLE_BLOCK_NAME } from "../../styles/io/block.js";
+import type { ExporterStyleOptions } from "../../styles/io/writer.js";
 import { type CommonExportOptions, type ExportCapabilities, type GraphExporter, type LossNote } from "../../types.js";
 import {
     CYTOSCAPE_ELEMENT_KEYS,
@@ -43,6 +45,10 @@ import {
     SUFFIX,
 } from "./dialect.js";
 import { OBOGRAPHS_LOSS, OBOGRAPHS_SHARED_LOSS, planObographs } from "./obographs-export.js";
+import { JSON_STYLE_CAPABILITIES, type JsonStyledExport, jsonStyledExport, STYLE_KEY_REPLACED_CODE } from "./styles.js";
+
+/** What the writer takes: the format's options, the common ones and the styles. */
+type JsonWriteOptions = JsonExportOptions & CommonExportOptions & ExporterStyleOptions;
 
 /**
  * The format-specific options of the JSON exporter.
@@ -212,6 +218,11 @@ export const JSON_LOSS = Object.freeze({
      * back with graph-io's usual type. The values are the same.
      */
     DTYPE_UNSUPPORTED: LOSS.DTYPE,
+    /**
+     * Saving with styles: a column named like one of the dialect's style keys (graphology's `color`, `size`, `label`,
+     * vis.js's `color`, `shape`, `font`, ...) is written with what graphty draws, so the values it held differ.
+     */
+    STYLE_KEY_REPLACED: STYLE_KEY_REPLACED_CODE,
 });
 
 /** The roles each dialect has a slot for (every other role column is a plain attribute, reported by checkCapabilities()). */
@@ -284,6 +295,8 @@ interface Resolved {
     readonly weightKey: string;
     readonly shape: JsonShapeMeta;
     readonly ontologyIri: string | null;
+    /** The styles being written, worked out for the dialect; absent without styles. */
+    readonly styled?: JsonStyledExport;
 }
 
 /** Everything write() needs, computed once by plan(). */
@@ -651,6 +664,8 @@ function plan(snapshot: GraphSnapshot, resolved: Resolved): Plan {
     const notes = checkCapabilities(snapshot, caps, resolved.common, {
         roles: SLOT_ROLES[dialect],
         positionDtype: "f64",
+        // Deprecated (next major): role columns are written as plain attributes; styles go through the style writer.
+        vizAsAttributes: true,
     }).filter((n) => n.code !== LOSS.POSITIONS && n.code !== LOSS.EDGE_IDS_DROPPED);
     const note: NoteFn = (code, message, column = null, count = null): void => {
         notes.push(Object.freeze({ code, message, column, count }));
@@ -735,7 +750,8 @@ function reservedKeys(snapshot: GraphSnapshot, resolved: Resolved): Readonly<Rec
             break;
         case "vis":
             node.add(resolved.nodeIdKey ?? "id");
-            edge.add(resolved.sourceKey).add(resolved.targetKey);
+            // an edge key named source or target reads the document as node-link JSON, whose endpoints those are
+            edge.add(resolved.sourceKey).add(resolved.targetKey).add("source").add("target");
             break;
         case "cytoscape":
             node.add("id").add("parent");
@@ -1363,10 +1379,27 @@ function* writeNodeLink(snapshot: GraphSnapshot, p: Plan): Generator<string, voi
         yield w.take();
     }
     w.close("]");
+    writeTopLevelBlock(c, p);
     w.close("}");
     yield w.take();
 }
 
+/**
+ * The `graphty.styles` block as a top-level key, for a dialect that holds it there.
+ * @param c - the cursor
+ * @param p - the plan
+ */
+function writeTopLevelBlock(c: Cursor, p: Plan): void {
+    const groups = p.resolved.styled?.groups ?? null;
+    if (groups !== null) {
+        c.w.member("groups", JSON.stringify(groups));
+    }
+    const block = p.resolved.styled?.topLevelBlock ?? null;
+    if (block !== null) {
+        c.w.member(STYLE_BLOCK_NAME, JSON.stringify(block));
+    }
+}
+
 /**
  * Write a vis.js document.
  * @param snapshot - the snapshot
@@ -1416,6 +1449,7 @@ function* writeVis(snapshot: GraphSnapshot, p: Plan): Generator<string, void, un
         yield w.take();
     }
     w.close("]");
+    writeTopLevelBlock(c, p);
     w.close("}");
     yield w.take();
 }
@@ -1624,7 +1658,7 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
         writeSlots(c, p.nodes, i, parentSlots);
         writeSlots(c, p.nodes, i, ATTRIBUTE_SLOTS);
         w.close("}");
-        writeCytoscapePosition(c, p.nodes, i);
+        writeCytoscapePosition(c, p, i);
         writeSlots(c, p.nodes, i, ELEMENT_SLOTS);
         w.close("}");
         yield w.take();
@@ -1661,27 +1695,27 @@ function* writeCytoscape(snapshot: GraphSnapshot, p: Plan): Generator<string, vo
         w.key("data");
         writeGraphObject(c, p);
     }
-    writeCytoscapeExtra(c, resolved.shape.cytoscape);
+    writeCytoscapeTopLevel(c, p);
+    writeTopLevelBlock(c, p);
     w.close("}");
     yield w.take();
 }
 
 /**
- * Write a node's `position` member (Cytoscape.js), when its position is set.
+ * Write a Cytoscape.js node's position: stored y-up, written with Cytoscape's y growing downward.
  * @param c - the cursor
- * @param items - the node plan items
- * @param i - the node index
+ * @param p - the plan
+ * @param i - the node
  */
-function writeCytoscapePosition(c: Cursor, items: readonly ColumnPlan[], i: number): void {
+function writeCytoscapePosition(c: Cursor, p: Plan, i: number): void {
     const { w } = c;
-    for (const item of items) {
+    for (const item of p.nodes) {
         if (item.slot === "cytoscapePosition" && item.column.isSet(i)) {
             const value = item.column.value(i) as ArrayLike<number>;
             const f32 = item.column.dtype === "f32";
             w.key("position");
             w.open("{");
             w.member("x", numberText(value[0], f32, c.nonfinite));
-            // stored y-up; Cytoscape's y grows downward
             w.member("y", numberText(flipY(value[1]), f32, c.nonfinite));
             w.close("}");
         }
@@ -1689,19 +1723,23 @@ function writeCytoscapePosition(c: Cursor, items: readonly ColumnPlan[], i: numb
 }
 
 /**
- * Write the extra top-level members of a Cytoscape.js document, beyond `elements` and `data`.
+ * Write the top-level keys of a Cytoscape.js document an import kept, and the stylesheet: the styles written replace
+ * the stylesheet the file was read with.
  * @param c - the cursor
- * @param extra - the extra members, when any
+ * @param p - the plan
  */
-function writeCytoscapeExtra(c: Cursor, extra: Readonly<Record<string, unknown>> | undefined): void {
-    if (extra === undefined) {
-        return;
-    }
+function writeCytoscapeTopLevel(c: Cursor, p: Plan): void {
+    const { w } = c;
+    const extra = p.resolved.shape.cytoscape ?? {};
+    const stylesheet = p.resolved.styled?.stylesheet ?? null;
     for (const key of Object.keys(extra)) {
-        if (key !== "elements" && key !== "data") {
-            c.w.member(key, valueText(extra[key], false, c.nonfinite));
+        if (key !== "elements" && key !== "data" && !(key === "style" && stylesheet !== null)) {
+            w.member(key, valueText(extra[key], false, c.nonfinite));
         }
     }
+    if (stylesheet !== null) {
+        w.member("style", valueText(stylesheet, false, c.nonfinite));
+    }
 }
 
 /**
@@ -1744,9 +1782,20 @@ function edgeIdGenerator(snapshot: GraphSnapshot, p: Plan): (e: number) => strin
  * @returns the parts
  */
 function parts(snapshot: GraphSnapshot, resolved: Resolved): Generator<string, void, undefined> {
-    return resolved.dialect === "obographs"
-        ? planObographs(snapshot, resolved).write()
-        : write(snapshot, plan(snapshot, resolved));
+    const s = resolved.styled?.snapshot ?? snapshot;
+    return resolved.dialect === "obographs" ? planObographs(s, resolved).write() : write(s, plan(s, resolved));
+}
+
+/**
+ * Resolve the options and, when styles are written, work them out for the dialect.
+ * @param snapshot - the snapshot
+ * @param options - the caller's options, with the styles graph-io hands an exporter
+ * @returns the resolved options
+ */
+function resolveStyled(snapshot: GraphSnapshot, options: JsonWriteOptions | undefined): Resolved {
+    const resolved = resolve(snapshot, options);
+    const styled = jsonStyledExport(snapshot, resolved.dialect, options?.styles);
+    return styled === null ? resolved : { ...resolved, styled };
 }
 
 /**
@@ -1768,6 +1817,7 @@ export const jsonExporter: GraphExporter<JsonExportOptions> = Object.freeze({
         "weightKey",
     ]),
     capabilities: dialectCapabilities("node-link"),
+    styles: Object.freeze({ capabilities: JSON_STYLE_CAPABILITIES }),
 
     /**
      * Pre-flight: every loss of the selected dialect, without writing anything.
@@ -1776,10 +1826,10 @@ export const jsonExporter: GraphExporter<JsonExportOptions> = Object.freeze({
      * @returns the notes, empty when the export is exact
      */
     check(snapshot: GraphSnapshot, options?: JsonExportOptions & CommonExportOptions): readonly LossNote[] {
-        const resolved = resolve(snapshot, options);
-        const notes =
-            resolved.dialect === "obographs" ? planObographs(snapshot, resolved).notes : plan(snapshot, resolved).notes;
-        return Object.freeze([...notes]);
+        const resolved = resolveStyled(snapshot, options);
+        const s = resolved.styled?.snapshot ?? snapshot;
+        const notes = resolved.dialect === "obographs" ? planObographs(s, resolved).notes : plan(s, resolved).notes;
+        return Object.freeze([...notes, ...(resolved.styled?.notes ?? [])]);
     },
 
     /**
@@ -1789,7 +1839,7 @@ export const jsonExporter: GraphExporter<JsonExportOptions> = Object.freeze({
      * @returns the chunks
      */
     export(snapshot: GraphSnapshot, options?: JsonExportOptions & CommonExportOptions): AsyncIterable<Uint8Array> {
-        return encodeChunks(parts(snapshot, resolve(snapshot, options)));
+        return encodeChunks(parts(snapshot, resolveStyled(snapshot, options)));
     },
 
     /**
@@ -1799,7 +1849,7 @@ export const jsonExporter: GraphExporter<JsonExportOptions> = Object.freeze({
      * @returns the document
      */
     exportToString(snapshot: GraphSnapshot, options?: JsonExportOptions & CommonExportOptions): Promise<string> {
-        return joinText(parts(snapshot, resolve(snapshot, options)));
+        return joinText(parts(snapshot, resolveStyled(snapshot, options)));
     },
 });