@graphty/graph-io 0.3.43 → 0.3.44

package/src/formats/cx2/exporter.ts

@@ -6,6 +6,11 @@
  * `z` from the `z` column), `edges`, the `cx2.bypass` columns as `nodeBypasses` / `edgeBypasses`,
  * the opaque aspects a CX2 import kept (which returns its own style rules) and `status`.
  *
+ * Given styles (`exportGraph(..., { styles })`), `visualProperties` and `visualEditorProperties` are the
+ * Cytoscape style of the rules (defaults and mappings), the bypasses are every element whose value the style
+ * cannot give, and the style values the rules read are attributes; the `graphty.styles` block, which graph-io
+ * hands over as a graph attribute, is written as an aspect of its own (a kept one is written back the same way).
+ *
  * What CX2 cannot hold is announced by check() before anything is written: every edge is
  * directed (W_CX2_UNDIRECTED_AS_DIRECTED, W_MUTUAL_EXPANDED), node ids are integers (E_ID_CHARSET
  * unless `sanitizeIds: "mangle"`, which keeps the original in the `graphty:originalId` attribute
@@ -32,8 +37,13 @@ import { type ResolvedExportOptions, resolveExportOptions } from "../../common/o
 import { plural } from "../../common/plural.js";
 import { type ExplicitWeights, explicitWeights } from "../../common/weights.js";
 import { encodeChunks, joinText } from "../../common/writer.js";
+import { cytoscapeCx2Aspects, type CytoscapeEmitted } from "../../styles/cytoscape/emit.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 { blockAspect, cytoscapeStyledExport, snapshotBlock } from "../cx/styles.js";
 import { BYPASS_NAMESPACE, CX2_FORMAT, cx2Type, ORIGINAL_ID_ATTRIBUTE } from "./importer.js";
+import { CX2_STYLE_CAPABILITIES } from "./styles.js";
 
 /**
  * The options of the CX2 exporter: the common export options; it has none of its own.
@@ -142,8 +152,12 @@ const SKIPPED_ROLES: ReadonlySet<string> = new Set([
     "thickness",
 ]);
 
+/** The style aspects; written from the styles when styles are given, else the kept ones. */
+const STYLE_ASPECTS: ReadonlySet<string> = new Set(["visualProperties", "visualEditorProperties"]);
+
 /** The aspects the exporter writes itself; an opaque aspect of the same name is not written again. */
 const CORE_ASPECTS: ReadonlySet<string> = new Set([
+    STYLE_BLOCK_NAME,
     "nodes",
     "edges",
     "attributeDeclarations",
@@ -444,7 +458,8 @@ function plan(snapshot: GraphSnapshot, common: ResolvedExportOptions): Plan {
     const edgeAttrs = planEdgeAttributes(snapshot, weights, note);
     const graphAttrs = planAttributes(
         snapshot.graph,
-        () => false,
+        // the graphty.styles block is an aspect of its own
+        (c) => c.meta.name === STYLE_BLOCK_NAME,
         (c) => c.meta.name,
     ).map((p) => ({ ...p, key: p.name }));
 
@@ -569,36 +584,16 @@ function attributesOf(plans: readonly AttributePlan[], row: number): Record<stri
 }
 
 /**
- * Write the document as text parts.
+ * The networkAttributes element and its declarations: the graph attributes, then the snapshot's name and
+ * description where no attribute of that name is written.
  * @param snapshot - the snapshot
  * @param p - the plan
- * @yields the document's text
- * @returns nothing
+ * @returns the element and the declarations
  */
-function* write(snapshot: GraphSnapshot, p: Plan): Generator<string, void, undefined> {
-    if (p.fatal !== null) {
-        throw p.fatal;
-    }
-    const { ids } = p;
-    if (ids === null) {
-        throw new GraphFormatError("E_INVALID_ID", "node ids cannot be written as CX2 integers", { reason: "charset" });
-    }
-    const { src, dst } = snapshot.edgeList();
-    const edges: number[] = [];
-    for (let e = 0; e < snapshot.edgeCount; e++) {
-        if (!p.folding.folded(e)) {
-            edges.push(e);
-        }
-    }
-
-    const nodeDecls = declarations(p.nodeAttrs, true);
-    if (p.originalIds) {
-        nodeDecls[ORIGINAL_ID_ATTRIBUTE] = { d: "string" };
-    }
-    const edgeDecls = declarations(p.edgeAttrs, true);
-    if (p.weights.weighted) {
-        edgeDecls[WEIGHT_ATTRIBUTE] = { d: "double" };
-    }
+function networkOf(
+    snapshot: GraphSnapshot,
+    p: Plan,
+): { network: Record<string, unknown>; networkDecls: Record<string, unknown> } {
     const networkDecls = declarations(p.graphAttrs, false);
     const network: Record<string, unknown> = {};
     for (const a of p.graphAttrs) {
@@ -617,81 +612,155 @@ function* write(snapshot: GraphSnapshot, p: Plan): Generator<string, void, undef
             networkDecls[key] = { d: "string" };
         }
     }
-    const kept = isRecord(meta.extra.cx2) ? meta.extra.cx2 : {};
+    return { network, networkDecls };
+}
+
+/**
+ * The attributeDeclarations element: the kept declarations of other tables, then the network's, the nodes' and the
+ * edges' where there are any.
+ * @param p - the plan
+ * @param kept - what an import kept in meta.extra.cx2
+ * @param networkDecls - the network's declarations
+ * @returns the element
+ */
+function declarationsElementOf(
+    p: Plan,
+    kept: Record<string, unknown>,
+    networkDecls: Record<string, unknown>,
+): Record<string, unknown> {
+    const nodeDecls = declarations(p.nodeAttrs, true);
+    if (p.originalIds) {
+        nodeDecls[ORIGINAL_ID_ATTRIBUTE] = { d: "string" };
+    }
+    const edgeDecls = declarations(p.edgeAttrs, true);
+    if (p.weights.weighted) {
+        edgeDecls[WEIGHT_ATTRIBUTE] = { d: "double" };
+    }
     const otherDecls = isRecord(kept.declarations) ? kept.declarations : {};
-    const opaque = meta.sourceFormat === CX2_FORMAT && isRecord(kept.opaque) ? kept.opaque : {};
-    const declarationsElement: Record<string, unknown> = { ...otherDecls };
+    const element: Record<string, unknown> = { ...otherDecls };
     for (const [key, table] of [
         ["networkAttributes", networkDecls],
         ["nodes", nodeDecls],
         ["edges", edgeDecls],
     ] as const) {
         if (Object.keys(table).length > 0) {
-            declarationsElement[key] = table;
+            element[key] = table;
         }
     }
-    const nodeBypassRows = bypassRows(p.nodeBypasses, snapshot.nodeCount);
-    const edgeBypassRows = bypassRows(p.edgeBypasses, snapshot.edgeCount).filter((e) => !p.folding.folded(e));
-    const opaqueAspects = Object.entries(opaque).filter(
-        (entry): entry is [string, unknown[]] => !CORE_ASPECTS.has(entry[0]) && Array.isArray(entry[1]),
-    );
+    return element;
+}
 
-    const counts: [string, number][] = [];
-    const hasDeclarations = Object.keys(declarationsElement).length > 0;
-    if (hasDeclarations) {
-        counts.push(["attributeDeclarations", 1]);
+/**
+ * One edge element.
+ * @param p - the plan
+ * @param ids - the written node ids
+ * @param src - the source of each edge
+ * @param dst - the target of each edge
+ * @param e - the edge
+ * @returns the element
+ */
+function edgeElement(
+    p: Plan,
+    ids: WrittenIds,
+    src: ArrayLike<number>,
+    dst: ArrayLike<number>,
+    e: number,
+): Record<string, unknown> {
+    const element: Record<string, unknown> = {
+        id: p.edgeIds[e],
+        s: ids.idAt(src[e]),
+        t: ids.idAt(dst[e]),
+    };
+    let v = attributesOf(p.edgeAttrs, e);
+    if (p.weights.isExplicit(e)) {
+        const w = p.weights.value(e);
+        v ??= {};
+        v[WEIGHT_ATTRIBUTE] = Number.isFinite(w) ? w : null;
     }
-    if (Object.keys(network).length > 0) {
-        counts.push(["networkAttributes", 1]);
+    if (v !== null) {
+        element.v = v;
     }
-    counts.push(["nodes", snapshot.nodeCount], ["edges", edges.length]);
-    if (nodeBypassRows.length > 0) {
-        counts.push(["nodeBypasses", nodeBypassRows.length]);
+    return element;
+}
+
+/**
+ * The optional aspects of a document that are written: those with elements.
+ * @param aspects - each aspect's name and element count
+ * @returns the metaData counts
+ */
+function presentAspects(aspects: readonly (readonly [string, number])[]): [string, number][] {
+    return aspects.filter(([, n]) => n > 0).map(([name, n]) => [name, n]);
+}
+
+/**
+ * Write the document as text parts.
+ * @param snapshot - the snapshot
+ * @param p - the plan
+ * @param styled - the styles as a Cytoscape style, or null without styles
+ * @yields the document's text
+ * @returns nothing
+ */
+function* write(
+    snapshot: GraphSnapshot,
+    p: Plan,
+    styled: CytoscapeEmitted | null = null,
+): Generator<string, void, undefined> {
+    if (p.fatal !== null) {
+        throw p.fatal;
     }
-    if (edgeBypassRows.length > 0) {
-        counts.push(["edgeBypasses", edgeBypassRows.length]);
+    const { ids } = p;
+    if (ids === null) {
+        throw new GraphFormatError("E_INVALID_ID", "node ids cannot be written as CX2 integers", { reason: "charset" });
     }
-    for (const [name, elements] of opaqueAspects) {
-        counts.push([name, elements.length]);
+    const edges: number[] = [];
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (!p.folding.folded(e)) {
+            edges.push(e);
+        }
     }
+    const { network, networkDecls } = networkOf(snapshot, p);
+    const { meta } = snapshot;
+    const kept = isRecord(meta.extra.cx2) ? meta.extra.cx2 : {};
+    const opaque = meta.sourceFormat === CX2_FORMAT && isRecord(kept.opaque) ? kept.opaque : {};
+    const declarationsElement = declarationsElementOf(p, kept, networkDecls);
+    const { bypassOf, nodeBypassRows, edgeBypassRows, opaqueAspects } = styleParts(snapshot, p, styled, opaque);
+    const hasDeclarations = Object.keys(declarationsElement).length > 0;
+    const hasNetwork = Object.keys(network).length > 0;
+    const counts: [string, number][] = [
+        ...presentAspects([
+            ["attributeDeclarations", hasDeclarations ? 1 : 0],
+            ["networkAttributes", hasNetwork ? 1 : 0],
+        ]),
+        ["nodes", snapshot.nodeCount],
+        ["edges", edges.length],
+        ...presentAspects([
+            ["nodeBypasses", nodeBypassRows.length],
+            ["edgeBypasses", edgeBypassRows.length],
+        ]),
+        ...opaqueAspects.map(([name, elements]): [string, number] => [name, elements.length]),
+    ];
 
     yield '[{"CXVersion":"2.0","hasFragments":false},\n';
     yield `{"metaData":${stringify(counts.map(([name, elementCount]) => ({ name, elementCount })))}},\n`;
     if (hasDeclarations) {
         yield `{"attributeDeclarations":[${stringify(declarationsElement)}]},\n`;
     }
-    if (Object.keys(network).length > 0) {
+    if (hasNetwork) {
         yield `{"networkAttributes":[${stringify(network)}]},\n`;
     }
     yield* block("nodes", snapshot.nodeCount, (i) => stringify(nodeElement(p, ids, i)));
-    yield* block("edges", edges.length, (k) => {
-        const e = edges[k];
-        const element: Record<string, unknown> = {
-            id: p.edgeIds[e],
-            s: ids.idAt(src[e]),
-            t: ids.idAt(dst[e]),
-        };
-        let v = attributesOf(p.edgeAttrs, e);
-        if (p.weights.isExplicit(e)) {
-            const w = p.weights.value(e);
-            v ??= {};
-            v[WEIGHT_ATTRIBUTE] = Number.isFinite(w) ? w : null;
-        }
-        if (v !== null) {
-            element.v = v;
-        }
-        return stringify(element);
-    });
+    const { src, dst } = snapshot.edgeList();
+    yield* block("edges", edges.length, (k) => stringify(edgeElement(p, ids, src, dst, edges[k])));
     if (nodeBypassRows.length > 0) {
         yield* block("nodeBypasses", nodeBypassRows.length, (k) => {
             const i = nodeBypassRows[k];
-            return stringify({ id: ids.idAt(i), v: bypassValues(p.nodeBypasses, i) });
+            return stringify({ id: ids.idAt(i), v: bypassOf("node", i) });
         });
     }
     if (edgeBypassRows.length > 0) {
         yield* block("edgeBypasses", edgeBypassRows.length, (k) => {
             const e = edgeBypassRows[k];
-            return stringify({ id: p.edgeIds[e], v: bypassValues(p.edgeBypasses, e) });
+            return stringify({ id: p.edgeIds[e], v: bypassOf("edge", e) });
         });
     }
     for (const [name, elements] of opaqueAspects) {
@@ -700,6 +769,74 @@ function* write(snapshot: GraphSnapshot, p: Plan): Generator<string, void, undef
     yield '{"status":[{"error":"","success":true}]}]\n';
 }
 
+/** The bypasses and the extra aspects of a document. */
+interface StyleParts {
+    /** An element's bypasses, or null. */
+    readonly bypassOf: (target: "node" | "edge", row: number) => Record<string, unknown> | null;
+    /** The nodes with bypasses. */
+    readonly nodeBypassRows: number[];
+    /** The written edges with bypasses. */
+    readonly edgeBypassRows: number[];
+    /** The aspects written after the bypasses: the kept opaque ones, the style, the `graphty.styles` block. */
+    readonly opaqueAspects: [string, unknown[]][];
+}
+
+/**
+ * The bypasses and the extra aspects of a document. With styles, the bypasses and the style aspects are the
+ * styles' own (the bypass columns and style aspects of an import are what the styles were read from); without, the
+ * bypass columns and the kept aspects are written back.
+ * @param snapshot - the snapshot
+ * @param p - the plan
+ * @param styled - the styles as a Cytoscape style, or null without styles
+ * @param opaque - the opaque aspects a CX2 import kept
+ * @returns the parts
+ */
+function styleParts(
+    snapshot: GraphSnapshot,
+    p: Plan,
+    styled: CytoscapeEmitted | null,
+    opaque: Record<string, unknown>,
+): StyleParts {
+    const bypassOf = (target: "node" | "edge", row: number): Record<string, unknown> | null => {
+        if (styled === null) {
+            return bypassValues(target === "node" ? p.nodeBypasses : p.edgeBypasses, row);
+        }
+        const m = styled.bypasses[target][row];
+        return m === null || m.size === 0 ? null : Object.fromEntries(m);
+    };
+    const rowsWith = (target: "node" | "edge", n: number): number[] => {
+        if (styled === null) {
+            return bypassRows(target === "node" ? p.nodeBypasses : p.edgeBypasses, n);
+        }
+        const out: number[] = [];
+        for (let i = 0; i < n; i++) {
+            if (bypassOf(target, i) !== null) {
+                out.push(i);
+            }
+        }
+        return out;
+    };
+    const nodeBypassRows = rowsWith("node", snapshot.nodeCount);
+    const edgeBypassRows = rowsWith("edge", snapshot.edgeCount).filter((e) => !p.folding.folded(e));
+    const opaqueAspects = Object.entries(opaque).filter(
+        (entry): entry is [string, unknown[]] =>
+            !CORE_ASPECTS.has(entry[0]) && !(styled !== null && STYLE_ASPECTS.has(entry[0])) && Array.isArray(entry[1]),
+    );
+    if (styled !== null) {
+        const aspects = cytoscapeCx2Aspects(styled.style);
+        opaqueAspects.push(
+            ["visualProperties", aspects.visualProperties],
+            ["visualEditorProperties", aspects.visualEditorProperties],
+        );
+    }
+    const styleBlock = snapshotBlock(snapshot);
+    if (styleBlock !== null) {
+        opaqueAspects.push([STYLE_BLOCK_NAME, blockAspect(styleBlock)]);
+    }
+
+    return { bypassOf, nodeBypassRows, edgeBypassRows, opaqueAspects };
+}
+
 /**
  * The text of one aspect block, element by element.
  * @param aspect - the aspect name
@@ -799,6 +936,7 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
     format: CX2_FORMAT,
     options: Object.freeze([]),
     capabilities: CX2_CAPABILITIES,
+    styles: Object.freeze({ capabilities: CX2_STYLE_CAPABILITIES }),
 
     /**
      * Pre-flight: what export() would lose, without writing anything.
@@ -806,8 +944,12 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the notes, empty when the export is exact
      */
-    check(snapshot: GraphSnapshot, options?: Cx2ExportOptions): readonly LossNote[] {
-        return Object.freeze([...plan(snapshot, resolveExportOptions(options)).notes]);
+    check(snapshot: GraphSnapshot, options?: Cx2ExportOptions & ExporterStyleOptions): readonly LossNote[] {
+        const styled = cytoscapeStyledExport(snapshot, options?.styles, "cx2");
+        return Object.freeze([
+            ...plan(styled?.snapshot ?? snapshot, resolveExportOptions(options)).notes,
+            ...(styled?.notes ?? []),
+        ]);
     },
 
     /**
@@ -816,8 +958,8 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the chunks
      */
-    export(snapshot: GraphSnapshot, options?: Cx2ExportOptions): AsyncIterable<Uint8Array> {
-        return encodeChunks(write(snapshot, plan(snapshot, resolveExportOptions(options))));
+    export(snapshot: GraphSnapshot, options?: Cx2ExportOptions & ExporterStyleOptions): AsyncIterable<Uint8Array> {
+        return encodeChunks(written(snapshot, options));
     },
 
     /**
@@ -826,7 +968,22 @@ export const cx2Exporter: GraphExporter<Cx2ExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the document
      */
-    exportToString(snapshot: GraphSnapshot, options?: Cx2ExportOptions): Promise<string> {
-        return joinText(write(snapshot, plan(snapshot, resolveExportOptions(options))));
+    exportToString(snapshot: GraphSnapshot, options?: Cx2ExportOptions & ExporterStyleOptions): Promise<string> {
+        return joinText(written(snapshot, options));
     },
 });
+
+/**
+ * The document's text, with the styles when they are given.
+ * @param snapshot - the snapshot
+ * @param options - the options
+ * @returns the text parts
+ */
+function written(
+    snapshot: GraphSnapshot,
+    options: (Cx2ExportOptions & ExporterStyleOptions) | undefined,
+): Generator<string, void, undefined> {
+    const styled = cytoscapeStyledExport(snapshot, options?.styles, "cx2");
+    const target = styled?.snapshot ?? snapshot;
+    return write(target, plan(target, resolveExportOptions(options)), styled?.styled ?? null);
+}

package/src/formats/cx2/importer.ts

@@ -16,7 +16,10 @@
  * `x` / `y` become the position column with y flipped to y-up, `z` the `z` column; per-element
  * bypasses become one column per visual property (origin namespace "cx2.bypass"); style rules
  * (`visualProperties`, `visualEditorProperties`) and every opaque aspect are kept verbatim in
- * `meta.extra.cx2.opaque` and are not applied (W_STYLES_NOT_IMPORTED, issue #706).
+ * `meta.extra.cx2.opaque`. Asked for styles (`importGraph(..., { styles: true })`), the importer reads
+ * the style rules and the bypasses (styles.ts), kept for it through the report; otherwise
+ * W_STYLES_NOT_IMPORTED. The `graphty.styles` aspect of a file graphty wrote becomes the graph
+ * attribute of that name, as in every other format.
  */
 
 import {
@@ -103,7 +106,10 @@ import {
 import { agree, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { weightFromValue } from "../../common/weights.js";
+import { STYLE_BLOCK_NAME } from "../../styles/io/block.js";
 import { type CommonImportOptions, type GraphImporter, type ImportInput, type ImportReport } from "../../types.js";
+import { blockOfAspect, type Cx2StyleSource } from "../cx/styles.js";
+import { readCx2Styles } from "./styles.js";
 
 /**
  * The format name.
@@ -2402,6 +2408,7 @@ export const cx2Importer: GraphImporter<Cx2ImportOptions> = Object.freeze({
     options: Object.freeze(["zAs"]),
     extensions: Object.freeze([".cx2"]),
     mimeTypes: Object.freeze(["application/json"]),
+    styles: readCx2Styles,
 
     /**
      * Confidence that the head is CX2: 0.97 when the first member of a top-level array is an
@@ -2434,7 +2441,18 @@ export const cx2Importer: GraphImporter<Cx2ImportOptions> = Object.freeze({
         reportSinkOptions(sink, options, report, true);
         reportUnusedOptions(options, report, USED_OPTIONS);
         const doc = await readDocument(input, report, resolved);
+        // the graphty.styles block of a file graphty wrote: a graph attribute, as in every other format
+        const block = blockOfAspect(doc.opaque.get(STYLE_BLOCK_NAME));
+        doc.opaque.delete(STYLE_BLOCK_NAME);
         new Cx2Reader(sink, report, resolved, zAs, doc).build();
+        if (block !== null) {
+            sink.setGraphValue(STYLE_BLOCK_NAME, block, { dtype: "string", origin: { format: CX2_FORMAT, id: null } });
+        }
+        const kept: Cx2StyleSource = {
+            visualProperties: doc.opaque.get("visualProperties"),
+            visualEditorProperties: doc.opaque.get("visualEditorProperties"),
+        };
+        report.keepForStyles(kept);
         throwIfAborted(resolved.signal);
         return report.finish();
     },

package/src/formats/cx2/styles.ts

@@ -0,0 +1,29 @@
+/**
+ * The styles of CX2 files: the `visualProperties` aspect (defaults, `nodeMapping`, `edgeMapping`), the dependencies
+ * in `visualEditorProperties`, and the `nodeBypasses` / `edgeBypasses` columns, resolved the way Cytoscape draws
+ * them with Cytoscape desktop's default style beneath. The reading and writing CX version 1 shares are in
+ * `../cx/styles.ts`.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { cytoscapeStyleFromCx2 } from "../../styles/cytoscape/mappings.js";
+import { StyleNotes } from "../../styles/notes.js";
+import type { ImporterStyles, StyleReadContext, StyleWriteCapabilities } from "../../styles/types.js";
+import { type Cx2StyleSource, cytoscapeWriteCapabilities, readDeclaredStyles } from "../cx/styles.js";
+
+/** What the CX2 writer holds of a graph's styles. */
+export const CX2_STYLE_CAPABILITIES: StyleWriteCapabilities = cytoscapeWriteCapabilities("cx2");
+
+/**
+ * The styles of an imported CX2 network.
+ * @param snapshot - the network
+ * @param context - what the import kept, the budget and the cancel signal
+ * @returns the styles
+ */
+export function readCx2Styles(snapshot: GraphSnapshot, context: StyleReadContext): ImporterStyles {
+    const notes = new StyleNotes();
+    const kept = context.kept as Cx2StyleSource | undefined;
+    const style = cytoscapeStyleFromCx2(kept?.visualProperties, kept?.visualEditorProperties, notes);
+    return readDeclaredStyles(snapshot, context, style, "cx2.bypass", notes, "cx2");
+}

package/src/formats/cys/constants.ts

@@ -142,3 +142,6 @@ export const CYS_ISSUE = Object.freeze({
     /** `graphName` matches several networks in the session. The import stops. */
     AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
 });
+
+/** The name prefix of the per-element style value columns graphty writes into a session's tables. */
+export const STYLE_COLUMN_PREFIX = "graphty.style.";