@graphty/graph-io 0.3.43 → 0.3.44

package/src/formats/gexf/exporter.ts

@@ -29,6 +29,7 @@ import { formatTemporal, formatTimeValue, type TimeFormat } from "../../common/t
 import { explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
 import { xmlIllegalTextNotes } from "../../common/xml.js";
+import type { ExporterStyleOptions } from "../../styles/io/writer.js";
 import { type CommonExportOptions, type ExportCapabilities, type GraphExporter, type LossNote } from "../../types.js";
 import {
     canonicalScalarType,
@@ -47,6 +48,10 @@ import {
     TEMPORAL_COLUMNS,
     VIZ_NAMESPACE,
 } from "./schema.js";
+import { GEXF_STYLE_CAPABILITIES, type GexfStyledExport, gexfStyledExport } from "./styles.js";
+
+/** What the writer takes: the format's options, the common ones and the styles. */
+type GexfWriteOptions = GexfExportOptions & CommonExportOptions & ExporterStyleOptions;
 
 /**
  * The format-specific options of the GEXF exporter.
@@ -1449,6 +1454,10 @@ function listItems(column: Column, row: number): readonly unknown[] {
 
 /**
  * The viz elements of one node or edge.
+ *
+ * Deprecated path, unchanged until the next major version: without `styles`, the color, size,
+ * shape and thickness role columns are written into `viz:*`. With `styles`, gexfStyledExport()
+ * replaces those columns with what the graph draws, so the style writer is the only path.
  * @param roles - the domain's role columns
  * @param row - the element's row
  * @param indent - the indentation
@@ -1562,15 +1571,14 @@ function edgeType(snapshot: GraphSnapshot, e: number, folding: PairFolding): Gex
 
 /**
  * Write the document as text parts.
- * @param snapshot - the snapshot
+ * @param given - the snapshot
  * @param options - the caller's options
  * @yields one part per element or line group
  * @returns nothing
  */
-function* writeGexf(
-    snapshot: GraphSnapshot,
-    options: (GexfExportOptions & CommonExportOptions) | undefined,
-): Generator<string, void, undefined> {
+function* writeGexf(given: GraphSnapshot, options: GexfWriteOptions | undefined): Generator<string, void, undefined> {
+    const styled = gexfStyledExport(given, options?.styles);
+    const snapshot = styled?.snapshot ?? given;
     const plan = planExport(snapshot, options);
     const { version } = plan;
     const ids = sanitizeIds(snapshot, "any", plan.options.sanitizeIds);
@@ -1580,7 +1588,7 @@ function* writeGexf(
 
     yield '<?xml version="1.0" encoding="UTF-8"?>\n';
     yield `<gexf xmlns="${ns.gexf}" xmlns:viz="${ns.viz}" version="${version}">\n`;
-    yield metaElement(meta);
+    yield metaElement(meta, styled);
     yield graphStart(snapshot, plan);
     yield attributesGroups("node", plan.nodeAttrs, "    ");
     yield attributesGroups("edge", plan.edgeAttrs, "    ");
@@ -1611,6 +1619,7 @@ function* writeGexf(
         }
         body += spellsElement(nodeRoles, i, plan, "        ");
         body += vizElements(nodeRoles, i, "        ", writeZ);
+        body += styled?.node(i, "        ") ?? "";
         yield body.length === 0 ? `      <node${attrs}/>\n` : `      <node${attrs}>\n${body}      </node>\n`;
     }
     yield "    </nodes>\n";
@@ -1658,6 +1667,7 @@ function* writeGexf(
         let body = attvaluesElement(plan.edgeAttrs, e, plan, "        ");
         body += spellsElement(edgeRoles, e, plan, "        ");
         body += vizElements(edgeRoles, e, "        ", false);
+        body += styled?.edge(e, "        ") ?? "";
         yield body.length === 0 ? `      <edge${attrs}/>\n` : `      <edge${attrs}>\n${body}      </edge>\n`;
     }
     yield "    </edges>\n";
@@ -1668,9 +1678,10 @@ function* writeGexf(
 /**
  * The `<meta>` element.
  * @param meta - the graph meta
+ * @param styled - the export's styles, whose block goes into `<meta>`, or null
  * @returns the lines, or an empty string when nothing is set
  */
-function metaElement(meta: GraphSnapshot["meta"]): string {
+function metaElement(meta: GraphSnapshot["meta"], styled: GexfStyledExport | null): string {
     let body = "";
     if (meta.creator !== null) {
         body += `    <creator>${escapeXmlText(meta.creator)}</creator>\n`;
@@ -1681,6 +1692,9 @@ function metaElement(meta: GraphSnapshot["meta"]): string {
     if (meta.keywords.length > 0) {
         body += `    <keywords>${escapeXmlText(meta.keywords.join(", "))}</keywords>\n`;
     }
+    if (styled !== null) {
+        body += `    ${styled.blockElement}\n`;
+    }
     const modified = meta.modified === null ? "" : ` lastmodifieddate="${escapeXmlAttribute(meta.modified)}"`;
     if (body.length === 0 && modified.length === 0) {
         return "";
@@ -1802,14 +1816,16 @@ export const gexfExporter: GraphExporter<GexfExportOptions> = Object.freeze({
     format: GEXF_FORMAT,
     options: Object.freeze(["version"]),
     capabilities: CAPABILITIES_1_3,
+    styles: Object.freeze({ capabilities: GEXF_STYLE_CAPABILITIES }),
     /**
      * Pre-flight: what export() would lose.
      * @param snapshot - the snapshot
      * @param options - format-specific and common options
      * @returns the loss notes, empty when the export is exact
      */
-    check(snapshot: GraphSnapshot, options?: GexfExportOptions & CommonExportOptions): readonly LossNote[] {
-        return Object.freeze(planExport(snapshot, options).notes);
+    check(snapshot: GraphSnapshot, options?: GexfWriteOptions): readonly LossNote[] {
+        const styled = gexfStyledExport(snapshot, options?.styles);
+        return Object.freeze([...planExport(styled?.snapshot ?? snapshot, options).notes, ...(styled?.notes ?? [])]);
     },
     /**
      * Write the snapshot as UTF-8 chunks.
@@ -1817,7 +1833,7 @@ export const gexfExporter: GraphExporter<GexfExportOptions> = Object.freeze({
      * @param options - format-specific and common options
      * @returns the chunks
      */
-    export(snapshot: GraphSnapshot, options?: GexfExportOptions & CommonExportOptions): AsyncIterable<Uint8Array> {
+    export(snapshot: GraphSnapshot, options?: GexfWriteOptions): AsyncIterable<Uint8Array> {
         return encodeChunks(writeGexf(snapshot, options));
     },
     /**
@@ -1826,7 +1842,7 @@ export const gexfExporter: GraphExporter<GexfExportOptions> = Object.freeze({
      * @param options - format-specific and common options
      * @returns the document
      */
-    async exportToString(snapshot: GraphSnapshot, options?: GexfExportOptions & CommonExportOptions): Promise<string> {
+    async exportToString(snapshot: GraphSnapshot, options?: GexfWriteOptions): Promise<string> {
         return joinText(writeGexf(snapshot, options));
     },
 });