@graphty/graph-io 0.3.43 → 0.3.45

package/src/formats/gml/exporter.ts

@@ -43,8 +43,20 @@ import { type ResolvedExportOptions, resolveExportOptions } from "../../common/o
 import { agree, plural } from "../../common/plural.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
+import type { ExporterStyleOptions } from "../../styles/io/writer.js";
 import { type CommonExportOptions, type ExportCapabilities, type GraphExporter, type LossNote } from "../../types.js";
-import { EMPTY_LIST_TEXT, isGmlKey, LIST_START_MARKER, mangleGmlKey, ORIGINAL_ID_KEY } from "./syntax.js";
+import { GML_STYLE_CAPABILITIES, gmlStyledExport } from "./styles.js";
+import {
+    EMPTY_LIST_TEXT,
+    isGmlKey,
+    KEY_MANGLED_CODE,
+    LIST_START_MARKER,
+    mangleGmlKey,
+    ORIGINAL_ID_KEY,
+} from "./syntax.js";
+
+/** What the writer takes: the format's options, the common ones and the styles. */
+type GmlWriteOptions = GmlExportOptions & CommonExportOptions & ExporterStyleOptions;
 
 /**
  * The format-specific options of the GML exporter.
@@ -105,11 +117,7 @@ export const INVALID_KEY_CODE = "E_GML_INVALID_KEY";
  * @category Issue and loss codes
  */
 export const RESERVED_KEY_CODE = "E_GML_RESERVED_KEY";
-/**
- * Keys rewritten under sanitizeKeys "mangle".
- * @category Issue and loss codes
- */
-export const KEY_MANGLED_CODE = "W_GML_KEY_MANGLED";
+export { KEY_MANGLED_CODE } from "./syntax.js";
 /**
  * A position column with more than three components; x, y and z are written.
  * @category Issue and loss codes
@@ -1425,7 +1433,21 @@ export const gmlExporter: GraphExporter<GmlExportOptions> = Object.freeze({
     format: "gml",
     options: Object.freeze(["sanitizeKeys", "weightKey"]),
     capabilities: GML_CAPABILITIES,
-    check,
+    styles: Object.freeze({ capabilities: GML_STYLE_CAPABILITIES }),
+    /**
+     * Pre-flight: the common capability notes, the GML-specific ones and, with styles, the values written as the
+     * nearest ones yEd's GML has.
+     * @param snapshot - the snapshot
+     * @param options - the options
+     * @returns the notes, empty when the export is exact
+     */
+    check(snapshot: GraphSnapshot, options?: GmlWriteOptions): readonly LossNote[] {
+        const styled = gmlStyledExport(snapshot, options?.styles);
+        if (styled === null) {
+            return check(snapshot, options);
+        }
+        return Object.freeze([...check(styled.snapshot, options), ...styled.notes]);
+    },
     /**
      * Write the snapshot as UTF-8 chunks; the context is resolved on the first pull, so the
      * errors check() announced surface from the iteration.
@@ -1433,7 +1455,7 @@ export const gmlExporter: GraphExporter<GmlExportOptions> = Object.freeze({
      * @param options - the options
      * @returns the chunks
      */
-    export(snapshot: GraphSnapshot, options?: GmlExportOptions & CommonExportOptions): AsyncIterable<Uint8Array> {
+    export(snapshot: GraphSnapshot, options?: GmlWriteOptions): AsyncIterable<Uint8Array> {
         return encodeChunks(lazyParts(snapshot, options));
     },
     /**
@@ -1442,7 +1464,7 @@ export const gmlExporter: GraphExporter<GmlExportOptions> = Object.freeze({
      * @param options - the options
      * @returns the document
      */
-    exportToString(snapshot: GraphSnapshot, options?: GmlExportOptions & CommonExportOptions): Promise<string> {
+    exportToString(snapshot: GraphSnapshot, options?: GmlWriteOptions): Promise<string> {
         return joinText(lazyParts(snapshot, options));
     },
 });
@@ -1454,9 +1476,6 @@ export const gmlExporter: GraphExporter<GmlExportOptions> = Object.freeze({
  * @yields the parts
  * @returns nothing
  */
-function* lazyParts(
-    snapshot: GraphSnapshot,
-    options: (GmlExportOptions & CommonExportOptions) | undefined,
-): Generator<string, void, undefined> {
-    yield* gmlParts(contextOf(snapshot, options));
+function* lazyParts(snapshot: GraphSnapshot, options: GmlWriteOptions | undefined): Generator<string, void, undefined> {
+    yield* gmlParts(contextOf(gmlStyledExport(snapshot, options?.styles)?.snapshot ?? snapshot, options));
 }

package/src/formats/gml/importer.ts

@@ -68,6 +68,8 @@ import {
     type ImportInput,
     type ImportReport,
 } from "../../types.js";
+import { gmlPositions } from "./positions.js";
+import { gmlStyles } from "./styles.js";
 import {
     EMPTY_LIST_TEXT,
     EMPTY_TUPLE_TEXT,
@@ -1990,6 +1992,8 @@ export const gmlImporter: GraphImporter<GmlImportOptions> = Object.freeze({
     extensions: Object.freeze([".gml"]),
     mimeTypes: Object.freeze(["text/x-gml", "text/plain"]),
     sniff: sniffGml,
+    styles: gmlStyles,
+    positions: gmlPositions,
     /**
      * Read a GML text into a sink.
      * @param input - the text, bytes or stream

package/src/formats/gml/index.ts

@@ -60,6 +60,7 @@ import {
 
 export { gmlExporter, type GmlExportOptions } from "./exporter.js";
 export { gmlImporter, type GmlImportOptions } from "./importer.js";
+export { GML_STYLE_BLOCK_KEY, GML_STYLE_CAPABILITIES } from "./styles.js";
 
 /**
  * The issue codes the GML importer records, by name: the codes shared with
@@ -193,7 +194,7 @@ export const GML_LOSS = Object.freeze({
     INVALID_KEY: INVALID_KEY_CODE,
     /** A column named like a structural key. */
     RESERVED_KEY: RESERVED_KEY_CODE,
-    /** A key rewritten under sanitizeKeys "mangle". */
+    /** A key rewritten under sanitizeKeys "mangle", or a column renamed because its key would read back as a style value. */
     KEY_MANGLED: KEY_MANGLED_CODE,
     /** A position column with more than three components. */
     POSITION_COMPONENTS: POSITION_COMPONENTS_CODE,

package/src/formats/gml/positions.ts

@@ -0,0 +1,52 @@
+/**
+ * How a GML file's `graphics [ x y z ]` positions are spelled, for `extractPositions()`: the node's
+ * center in pixels, y growing downward (the GML specification, yFiles and Cytoscape) unless the
+ * `Creator` names a y-up tool (Gephi, Tulip).
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { toolOf } from "../../common/units.js";
+import { median } from "../../positions/convert.js";
+import type { ImporterPositions } from "../../positions/types.js";
+
+/** The json column the importer keeps the rest of each node's graphics record in. */
+const GRAPHICS_COLUMN = "graphics";
+
+/**
+ * The spelling of a GML file's positions.
+ * @param snapshot - the graph the GML importer read
+ * @returns the spelling, or null when no node has a position
+ */
+export function gmlPositions(snapshot: GraphSnapshot): ImporterPositions | null {
+    if (snapshot.nodes.byRole("position") === null) {
+        return null;
+    }
+    const tool = toolOf(snapshot.meta.creator);
+    return {
+        units: "px",
+        // a z that is the same on every node collapses to 2D
+        sourceDims: 3,
+        yAxis: tool === "gephi" || tool === "tulip" ? "up" : "down",
+        tool,
+        medianNodeSize: graphicsMedian(snapshot),
+    };
+}
+
+/**
+ * The median node diameter from the graphics records' `w` and `h`.
+ * @param snapshot - the graph
+ * @returns the median of each node's mean of w and h, or null when no node has both
+ */
+function graphicsMedian(snapshot: GraphSnapshot): number | null {
+    const graphics = snapshot.nodes.get(GRAPHICS_COLUMN);
+    const sizes: number[] = [];
+    for (let row = 0; graphics !== null && row < graphics.length; row++) {
+        const g = graphics.isSet(row) ? graphics.value(row) : undefined;
+        const { w, h } = typeof g === "object" && g !== null ? (g as Record<string, unknown>) : {};
+        if (typeof w === "number" && typeof h === "number") {
+            sizes.push((w + h) / 2);
+        }
+    }
+    return median(sizes);
+}