@graphty/graph-io 0.3.42 → 0.3.44

package/src/formats/cx/exporter.ts

@@ -12,6 +12,12 @@
  * `cx.bypass` columns, the provenance aspects a CX import created, the style rules and unknown
  * aspects a CX import kept, and `status`.
  *
+ * Given styles (`exportGraph(..., { styles })`), `cyVisualProperties` holds the Cytoscape style of the rules
+ * (`network`, `nodes:default` and `edges:default` with their mappings and dependencies) and a bypass for 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 CX cannot hold is announced by check() before anything is written: every edge is directed
  * (W_CX_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 the
@@ -42,8 +48,12 @@ 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 { cytoscapeCxAspect, 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 { ORIGINAL_ID_ATTRIBUTE } from "../cx2/importer.js";
+import { blockAspect, CX_STYLE_CAPABILITIES, cytoscapeStyledExport, snapshotBlock } from "./styles.js";
 
 /** The format name. */
 const CX_FORMAT = "cx";
@@ -216,6 +226,7 @@ const NEVER_WRITTEN: ReadonlySet<string> = new Set([
     "status",
     "groups",
     "subnetwork",
+    STYLE_BLOCK_NAME,
 ]);
 
 /** The weight attribute name (the CX importer's weightFrom default). */
@@ -559,7 +570,12 @@ function plan(snapshot: GraphSnapshot, common: ResolvedExportOptions): Plan {
     nonfinite += weight.nonfinite;
 
     graphColumnNotes(snapshot, note);
-    const graphAttrs = attributePlans(snapshot.graph, isBypass, (c) => c.meta.name);
+    // the graphty.styles block is an aspect of its own
+    const graphAttrs = attributePlans(
+        snapshot.graph,
+        (c) => isBypass(c) || c.meta.name === STYLE_BLOCK_NAME,
+        (c) => c.meta.name,
+    );
 
     if (children.column !== null && children.column.meta.role === "parents" && !several) {
         note(
@@ -900,9 +916,10 @@ function writtenEdges(snapshot: GraphSnapshot, folding: PairFolding): number[] {
  * @param snapshot - the snapshot
  * @param p - the plan
  * @param ids - the written node ids
+ * @param styled - the styles as a Cytoscape style, or null without styles
  * @returns the aspects (those without elements included; the writer skips them)
  */
-function aspects(snapshot: GraphSnapshot, p: Plan, ids: WrittenIds): Aspect[] {
+function aspects(snapshot: GraphSnapshot, p: Plan, ids: WrittenIds, styled: CytoscapeEmitted | null): Aspect[] {
     const { src, dst } = snapshot.edgeList();
     const edges = writtenEdges(snapshot, p.folding);
     const nodeRange = (): number[] => Array.from({ length: snapshot.nodeCount }, (_, i) => i);
@@ -1017,8 +1034,18 @@ function aspects(snapshot: GraphSnapshot, p: Plan, ids: WrittenIds): Aspect[] {
         { name: "cyTableColumn", elements: () => tableColumns(p, ids) },
         { name: "cartesianLayout", elements: () => layoutElements(p, ids, nodeRange()) },
         { name: "cyGroups", elements: () => groupElements(snapshot, p, ids, edges) },
-        { name: "cyVisualProperties", elements: () => visualProperties(p, ids, nodeRange(), edges, kept) },
+        {
+            name: "cyVisualProperties",
+            elements: () =>
+                styled === null
+                    ? visualProperties(p, ids, nodeRange(), edges, kept)
+                    : styledVisualProperties(styled, ids, p.edgeIds, edges),
+        },
     ];
+    const block = snapshotBlock(snapshot);
+    if (block !== null) {
+        out.push({ name: STYLE_BLOCK_NAME, elements: () => blockAspect(block) });
+    }
     out.push(...provenanceAspects(snapshot, p, ids, edges));
     for (const [name, value] of Object.entries(kept)) {
         if (!NEVER_WRITTEN.has(name) && Array.isArray(value)) {
@@ -1281,6 +1308,38 @@ function* visualProperties(
     }
 }
 
+/**
+ * The cyVisualProperties entries of a styled export: the style's defaults, mappings and dependencies, then every
+ * element's bypasses (as text, Cytoscape's form).
+ * @param styled - the styles as a Cytoscape style
+ * @param ids - the written ids
+ * @param edgeIds - the written edge ids
+ * @param edges - the written edges
+ * @yields the entries
+ */
+function* styledVisualProperties(
+    styled: CytoscapeEmitted,
+    ids: WrittenIds,
+    edgeIds: readonly number[],
+    edges: readonly number[],
+): Generator<unknown, void, undefined> {
+    yield* cytoscapeCxAspect(styled.style);
+    const text = (m: ReadonlyMap<string, unknown>): Record<string, string> =>
+        Object.fromEntries([...m].map(([k, v]) => [k, String(v)]));
+    for (let row = 0; row < styled.bypasses.node.length; row++) {
+        const m = styled.bypasses.node[row];
+        if (m !== null && m.size > 0) {
+            yield { properties_of: "nodes", applies_to: ids.idAt(row), properties: text(m) };
+        }
+    }
+    for (const e of edges) {
+        const m = styled.bypasses.edge[e];
+        if (m !== null && m.size > 0) {
+            yield { properties_of: "edges", applies_to: edgeIds[e], properties: text(m) };
+        }
+    }
+}
+
 /**
  * The view of the subnetwork a CX import read (the one its style rules belong to).
  * @param kept - meta.extra.cx
@@ -1393,10 +1452,15 @@ function provenanceAspects(snapshot: GraphSnapshot, p: Plan, ids: WrittenIds, ed
  * 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): Generator<string, void, undefined> {
+function* write(
+    snapshot: GraphSnapshot,
+    p: Plan,
+    styled: CytoscapeEmitted | null = null,
+): Generator<string, void, undefined> {
     if (p.fatal !== null) {
         throw p.fatal;
     }
@@ -1404,7 +1468,7 @@ function* write(snapshot: GraphSnapshot, p: Plan): Generator<string, void, undef
     if (ids === null) {
         throw new GraphFormatError("E_INVALID_ID", "node ids cannot be written as CX integers", { reason: "charset" });
     }
-    const all = aspects(snapshot, p, ids);
+    const all = aspects(snapshot, p, ids, styled);
     const written: { aspect: Aspect; count: number }[] = [];
     for (const aspect of all) {
         let count = 0;
@@ -1450,6 +1514,7 @@ export const cxExporter: GraphExporter<CxExportOptions> = Object.freeze({
     format: CX_FORMAT,
     options: Object.freeze([]),
     capabilities: CX_CAPABILITIES,
+    styles: Object.freeze({ capabilities: CX_STYLE_CAPABILITIES }),
 
     /**
      * Pre-flight: what export() would lose, without writing anything.
@@ -1457,8 +1522,12 @@ export const cxExporter: GraphExporter<CxExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the notes, empty when the export is exact
      */
-    check(snapshot: GraphSnapshot, options?: CxExportOptions): readonly LossNote[] {
-        return Object.freeze([...plan(snapshot, resolveExportOptions(options)).notes]);
+    check(snapshot: GraphSnapshot, options?: CxExportOptions & ExporterStyleOptions): readonly LossNote[] {
+        const styled = cytoscapeStyledExport(snapshot, options?.styles, "desktop");
+        return Object.freeze([
+            ...plan(styled?.snapshot ?? snapshot, resolveExportOptions(options)).notes,
+            ...(styled?.notes ?? []),
+        ]);
     },
 
     /**
@@ -1467,8 +1536,8 @@ export const cxExporter: GraphExporter<CxExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the chunks
      */
-    export(snapshot: GraphSnapshot, options?: CxExportOptions): AsyncIterable<Uint8Array> {
-        return encodeChunks(write(snapshot, plan(snapshot, resolveExportOptions(options))));
+    export(snapshot: GraphSnapshot, options?: CxExportOptions & ExporterStyleOptions): AsyncIterable<Uint8Array> {
+        return encodeChunks(written(snapshot, options));
     },
 
     /**
@@ -1477,7 +1546,22 @@ export const cxExporter: GraphExporter<CxExportOptions> = Object.freeze({
      * @param options - the common options
      * @returns the document
      */
-    exportToString(snapshot: GraphSnapshot, options?: CxExportOptions): Promise<string> {
-        return joinText(write(snapshot, plan(snapshot, resolveExportOptions(options))));
+    exportToString(snapshot: GraphSnapshot, options?: CxExportOptions & 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: (CxExportOptions & ExporterStyleOptions) | undefined,
+): Generator<string, void, undefined> {
+    const styled = cytoscapeStyledExport(snapshot, options?.styles, "desktop");
+    const target = styled?.snapshot ?? snapshot;
+    return write(target, plan(target, resolveExportOptions(options)), styled?.styled ?? null);
+}

package/src/formats/cx/importer.ts

@@ -17,8 +17,11 @@
  * one `graphIndex` / `graphName` picks, `listGraphs()` lists them. Positions come from the
  * subnetwork's view, y flipped to y-up, `z` into the `z` column; `cyGroups` give `parent` (or
  * `parents`); per-element visual properties are one column per property (origin namespace
- * "cx.bypass") and style rules are kept verbatim in `meta.extra.cx` and not applied
- * (W_STYLES_NOT_IMPORTED, issue #706); provenance aspects become extension tables and list columns.
+ * "cx.bypass") and style rules are kept verbatim in `meta.extra.cx`; asked for styles
+ * (`importGraph(..., { styles: true })`), the importer reads the view's style rules and 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; provenance aspects become
+ * extension tables and list columns.
  */
 
 import {
@@ -111,6 +114,7 @@ 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 GraphChoiceOptions,
@@ -120,6 +124,7 @@ import {
     type ImportReport,
 } from "../../types.js";
 import { ORIGINAL_ID_ATTRIBUTE, zAsOption } from "../cx2/importer.js";
+import { blockOfAspect, type CxStyleSource, readCxStyles } from "./styles.js";
 
 /** The format name. */
 const CX_FORMAT = "cx";
@@ -1083,6 +1088,41 @@ function refId(raw: unknown): NodeId | null {
     }
 }
 
+/**
+ * The view a cyVisualProperties entry names.
+ * @param entry - the entry
+ * @returns the view's id, or null when it names none
+ */
+function entryView(entry: Record<string, unknown>): NodeId | null {
+    return entry.view === undefined || entry.view === null ? null : refId(entry.view);
+}
+
+/**
+ * A visual property value as the text of a bypass cell.
+ * @param raw - the value
+ * @returns the string itself, else its JSON
+ */
+function cellText(raw: unknown): string {
+    return typeof raw === "string" ? raw : JSON.stringify(raw);
+}
+
+/** What readVisualProperties() collects from the entries of this graph's view. */
+interface VisualPropertiesRead {
+    /** The per-element values, by property: [row, text] pairs. */
+    readonly columns: {
+        readonly node: Map<string, [number, string][]>;
+        readonly edge: Map<string, [number, string][]>;
+    };
+    /** The network values, by property. */
+    readonly network: Map<string, string>;
+    /** How many default values the entries hold. */
+    defaults: number;
+    /** How many mappings. */
+    mappings: number;
+    /** How many dependencies. */
+    dependencies: number;
+}
+
 /**
  * A member list: the ids of an array, or null for "all" (an absent list is empty).
  * @param raw - the list
@@ -1364,26 +1404,6 @@ function memberCount(members: ReadonlySet<NodeId> | null, total: number): number
 
 // ============================================================ the build
 
-/** The cyVisualProperties of a graph's view, gathered before they are written. */
-interface VisualCollection {
-    /** per domain, per property: the [row, text] cells */
-    columns: Record<"node" | "edge", Map<string, [number, string][]>>;
-    /** the network values by property */
-    network: Map<string, string>;
-    defaults: number;
-    mappings: number;
-    dependencies: number;
-}
-
-/**
- * A visual property value as text: a string as it is, anything else as JSON.
- * @param raw - the value
- * @returns its text
- */
-function visualText(raw: unknown): string {
-    return typeof raw === "string" ? raw : JSON.stringify(raw);
-}
-
 /** One attribute column of the graph being built. */
 interface AttributeColumn {
     readonly name: string;
@@ -1509,6 +1529,7 @@ class CxReader {
         this.writeAttributes("edge", edgeColumns);
         this.readNetworkAttributes();
         this.readVisualProperties();
+        this.readStyleBlock();
         this.readProvenance();
         for (const [kind, count] of this.dangling) {
             report.warning(
@@ -2872,79 +2893,86 @@ class CxReader {
      * applied.
      */
     private readVisualProperties(): void {
+        const entries = aspect(this.doc, "cyVisualProperties");
         // Cytoscape's table-cell styles: a visual property aspect graph-io keeps but does not read
         const tableStyles = TABLE_STYLE_ASPECTS.reduce((n, name) => n + (this.doc.kept.get(name)?.length ?? 0), 0);
         // the graph's own view (its first): the one its positions come from; the others stay in meta.extra.cx
         const views = new Set(this.plan.views.slice(0, 1));
-        const visual: VisualCollection = {
+        const ofThisView = (view: NodeId | null): boolean => view === null || views.size === 0 || views.has(view);
+        this.keepVisualPropertiesForStyles(entries, ofThisView);
+        const read: VisualPropertiesRead = {
             columns: { node: new Map(), edge: new Map() },
             network: new Map(),
             defaults: 0,
             mappings: 0,
             dependencies: 0,
         };
-        for (const { value } of aspect(this.doc, "cyVisualProperties")) {
-            if (isRecord(value)) {
-                this.collectVisualEntry(value, views, visual);
+        for (const { value } of entries) {
+            if (isRecord(value) && ofThisView(entryView(value))) {
+                this.collectVisualProperties(value, read);
             }
         }
-        this.writeBypassColumns(visual.columns);
-        this.writeBypassNetwork(visual.network);
-        this.reportStyleRules(visual, tableStyles);
+        this.writeBypassColumns(read);
+        this.warnStylesNotImported(read, tableStyles);
     }
 
     /**
-     * File one cyVisualProperties element of this graph's view into the collection: per-element and
-     * network values by property, defaults, mappings and dependencies counted.
-     * @param value - the element
-     * @param views - the views read (empty: every view)
-     * @param visual - the collection to add to
+     * Hand the style reader the entries of this graph's view (and those naming no view).
+     * @param entries - every cyVisualProperties entry
+     * @param ofThisView - whether a view is this graph's
      */
-    private collectVisualEntry(
-        value: Record<string, unknown>,
-        views: ReadonlySet<NodeId>,
-        visual: VisualCollection,
+    private keepVisualPropertiesForStyles(
+        entries: readonly { value: unknown }[],
+        ofThisView: (view: NodeId | null) => boolean,
     ): void {
-        const view = value.view === undefined || value.view === null ? null : refId(value.view);
-        if (view !== null && views.size > 0 && !views.has(view)) {
-            return;
-        }
-        const properties = isRecord(value.properties) ? value.properties : {};
-        visual.mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
-        visual.dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
-        switch (value.properties_of) {
-            case "nodes":
-                this.collectElementProperties("node", value.applies_to, properties, visual.columns);
-                break;
-            case "edges":
-                this.collectElementProperties("edge", value.applies_to, properties, visual.columns);
-                break;
-            case "network":
-                for (const [property, raw] of Object.entries(properties)) {
-                    visual.network.set(property, visualText(raw));
+        const others = new Set<unknown>();
+        const kept = entries
+            .map((h) => h.value)
+            .filter((v) => {
+                const view = isRecord(v) ? entryView(v) : null;
+                if (!ofThisView(view)) {
+                    others.add(view);
+                    return false;
                 }
-                break;
-            default:
-                visual.defaults += Object.keys(properties).length;
-                break;
+                return true;
+            });
+        const source: CxStyleSource = others.size > 0 ? { entries: kept, otherViews: others.size } : { entries: kept };
+        this.report.keepForStyles(source);
+    }
+
+    /**
+     * Collect one cyVisualProperties entry of this graph's view.
+     * @param value - the entry
+     * @param read - what is collected so far
+     */
+    private collectVisualProperties(value: Record<string, unknown>, read: VisualPropertiesRead): void {
+        const properties = isRecord(value.properties) ? value.properties : {};
+        read.mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
+        read.dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
+        if (value.properties_of === "nodes" || value.properties_of === "edges") {
+            this.collectElementProperties(value, properties, read);
+        } else if (value.properties_of === "network") {
+            for (const [property, raw] of Object.entries(properties)) {
+                read.network.set(property, cellText(raw));
+            }
+        } else {
+            read.defaults += Object.keys(properties).length;
         }
     }
 
     /**
-     * File the visual values of one node or edge under its row; an element not in this graph is
-     * skipped, and reported dangling when it is in no graph of the file.
-     * @param domain - node or edge
-     * @param appliesTo - the element's applies_to
-     * @param properties - its visual properties
-     * @param columns - the per-property cells to add to
+     * Collect the per-element values of a nodes or edges entry.
+     * @param value - the entry
+     * @param properties - its properties
+     * @param read - what is collected so far
      */
     private collectElementProperties(
-        domain: "node" | "edge",
-        appliesTo: unknown,
+        value: Record<string, unknown>,
         properties: Record<string, unknown>,
-        columns: VisualCollection["columns"],
+        read: VisualPropertiesRead,
     ): void {
-        const target = refId(appliesTo);
+        const domain = value.properties_of === "nodes" ? "node" : "edge";
+        const target = refId(value.applies_to);
         const rows = domain === "node" ? this.nodeRows : this.edgeRows;
         const row = target === null ? undefined : rows.get(target);
         if (row === undefined) {
@@ -2954,19 +2982,19 @@ class CxReader {
             return;
         }
         for (const [property, raw] of Object.entries(properties)) {
-            const list = columns[domain].get(property) ?? [];
-            list.push([row, visualText(raw)]);
-            columns[domain].set(property, list);
+            const list = read.columns[domain].get(property) ?? [];
+            list.push([row, cellText(raw)]);
+            read.columns[domain].set(property, list);
         }
     }
 
     /**
-     * Write the collected per-element visual values as string columns in the cx.bypass namespace.
-     * @param columns - the per-property cells of each domain
+     * Write the per-element and network values as string columns in the cx.bypass namespace.
+     * @param read - what was collected
      */
-    private writeBypassColumns(columns: VisualCollection["columns"]): void {
+    private writeBypassColumns(read: VisualPropertiesRead): void {
         for (const domain of ["node", "edge"] as const) {
-            for (const [property, cells] of columns[domain]) {
+            for (const [property, cells] of read.columns[domain]) {
                 const handle = declareFresh(
                     this.sink,
                     domain,
@@ -2987,14 +3015,7 @@ class CxReader {
                 }
             }
         }
-    }
-
-    /**
-     * Write the network visual values as graph values in the cx.bypass namespace.
-     * @param network - the value of each property
-     */
-    private writeBypassNetwork(network: ReadonlyMap<string, string>): void {
-        for (const [property, text] of network) {
+        for (const [property, text] of read.network) {
             try {
                 this.sink.setGraphValue(property, text, {
                     dtype: "string",
@@ -3007,12 +3028,12 @@ class CxReader {
     }
 
     /**
-     * Warn that the style rules (defaults, mappings, dependencies, table styles) are kept, not applied.
-     * @param visual - the counted rules
-     * @param tableStyles - the number of table style elements
+     * The warning that the file's style rules are kept and not applied, when it has any.
+     * @param read - what was collected
+     * @param tableStyles - how many table style elements the file holds
      */
-    private reportStyleRules(visual: VisualCollection, tableStyles: number): void {
-        const { defaults, mappings, dependencies } = visual;
+    private warnStylesNotImported(read: VisualPropertiesRead, tableStyles: number): void {
+        const { defaults, mappings, dependencies } = read;
         if (defaults + mappings + dependencies + tableStyles === 0) {
             return;
         }
@@ -3030,6 +3051,17 @@ class CxReader {
         );
     }
 
+    /** The `graphty.styles` aspect of a file graphty wrote, as the graph attribute of that name. */
+    private readStyleBlock(): void {
+        const block = blockOfAspect(this.doc.kept.get(STYLE_BLOCK_NAME));
+        if (block !== null) {
+            this.sink.setGraphValue(STYLE_BLOCK_NAME, block, {
+                dtype: "string",
+                origin: { format: CX_FORMAT, id: null },
+            });
+        }
+    }
+
     /**
      * Read the provenance aspects: citations and supports as extension tables cx:citations and
      * cx:supports, the node / edge links to them as list columns, functionTerms as a json column,
@@ -3230,7 +3262,10 @@ class CxReader {
             }
             return found;
         };
-        const extra: Record<string, unknown> = Object.fromEntries(this.doc.kept);
+        // the graphty.styles aspect is read as a graph attribute (readStyleBlock), not kept
+        const extra: Record<string, unknown> = Object.fromEntries(
+            [...this.doc.kept].filter(([name]) => name !== STYLE_BLOCK_NAME),
+        );
         const groups = aspect(this.doc, "cyGroups").map((h) => plainJson(h.value));
         const own: Record<string, unknown> = {};
         if (groups.length > 0) {
@@ -3312,6 +3347,7 @@ export const cxImporter: GraphImporter<CxImportOptions> = Object.freeze({
     options: Object.freeze(["zAs"]),
     extensions: Object.freeze([".cx"]),
     mimeTypes: Object.freeze(["application/json"]),
+    styles: readCxStyles,
 
     /**
      * Confidence that the head is CX version 1: 0.95 when a top-level array starts with an object