@graphty/graph-io 0.3.42 → 0.3.44

package/src/formats/cys/importer.ts

@@ -13,14 +13,15 @@
  * shows), in a label column named `name`, and ids an exporter mangled are restored from the node
  * table's `graphty:originalId` (restoreMangledIds). 2.x: one full XGMML file per network, with
  * selection and hidden state from `cysession.xml`. Everything is resolved by the XGMML emitter, so
- * both readers share every column rule. Styles are not read (issue #706): W_STYLES_NOT_IMPORTED.
+ * both readers share every column rule. Asked for styles, the importer reads the style the imported view names
+ * from `session_vizmap.xml` (styles.ts), kept for it through the report; otherwise W_STYLES_NOT_IMPORTED.
  */
 
 import { GraphFormatError, type GraphSink, INVALID_INDEX } from "@graphty/graph-format";
 
 import { declareResolved } from "../../common/attributes.js";
 import { IdCoercer } from "../../common/ids.js";
-import { decodeEntryName, throwIfAborted } from "../../common/input.js";
+import { decodeEntryName, readText, throwIfAborted } from "../../common/input.js";
 import {
     chooseGraph,
     graphChosen,
@@ -33,6 +34,7 @@ import {
 import { agree, elementCount, plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { startsLikeZip } from "../../common/zip.js";
+import { STYLE_BLOCK_NAME } from "../../styles/io/block.js";
 import {
     type CommonImportOptions,
     type GraphChoiceOptions,
@@ -88,6 +90,7 @@ import {
     urlDecode,
     type XmlNode,
 } from "./session.js";
+import { readSessionStyles, type SessionStyleSource } from "./styles.js";
 import { cellAtt, type CyTable, readCyTable, type VirtualColumn, virtualColumnsOf } from "./tables.js";
 
 /**
@@ -469,8 +472,9 @@ function registeredGraphs(parsed: Parsed): GraphRec[] {
  * @param choice - the subnetwork
  * @param sink - the sink
  * @param parsed - its network file, parsed for this import (its records are filled in)
+ * @returns the style its view names, or null
  */
-async function import3(prepared: Prepared, choice: Choice3, sink: GraphSink, parsed: Parsed): Promise<void> {
+async function import3(prepared: Prepared, choice: Choice3, sink: GraphSink, parsed: Parsed): Promise<string | null> {
     const { graph } = choice;
     const members = membersOf(parsed.doc, graph);
     const nodes = byId(members.nodes);
@@ -478,7 +482,7 @@ async function import3(prepared: Prepared, choice: Choice3, sink: GraphSink, par
     // the records are shared by every network of the file: what this import adds is undone after
     const restore = saveRecords(graph, nodes, edges);
     try {
-        await fill3(prepared, choice, sink, parsed, nodes, edges);
+        return await fill3(prepared, choice, sink, parsed, nodes, edges);
     } finally {
         restore();
     }
@@ -530,6 +534,7 @@ function saveRecords(
  * @param parsed - its network file
  * @param nodes - its node records by id
  * @param edges - its edge records by id
+ * @returns the style its view names, or null
  */
 async function fill3(
     prepared: Prepared,
@@ -538,7 +543,7 @@ async function fill3(
     parsed: Parsed,
     nodes: ReadonlyMap<string, NodeRec>,
     edges: ReadonlyMap<string, EdgeRec>,
-): Promise<void> {
+): Promise<string | null> {
     const { report, inner } = prepared;
     const { doc, dialect } = parsed;
     const { graph } = choice;
@@ -553,6 +558,12 @@ async function fill3(
     }
     const restoredIds = inner.restoreMangledIds ? restoreIds(members.nodes) : new Map<string, string>();
     const { visualStyle, extraViews, extraIds } = await readViews(prepared, choice, nodes, edges);
+    const block =
+        prepared.session.layout.block === null ? null : await entryText(prepared, prepared.session.layout.block);
+    if (block !== null) {
+        // the graphty.styles block of a session graphty wrote: a graph attribute, as in every other format
+        graph.atts.push(textAtt(STYLE_BLOCK_NAME, block));
+    }
     const cyMeta = sessionMeta(prepared, {
         collection: doc.root.label ?? choice.network.title,
         network: choice.graphId,
@@ -586,6 +597,7 @@ async function fill3(
     }
     reportRootOnly(parsed, report, choice.network.name);
     writeViewPositions(sink, extraViews, extraIds, report, prepared.inner, restoredIds);
+    return visualStyle;
 }
 
 /**
@@ -749,7 +761,8 @@ function rowAtts(
     const line = table.lines.get(key) ?? 0;
     const out: AttRec[] = [];
     for (let i = 1; i < table.columns.length && i < cells.length; i++) {
-        pushAtt(out, cellAtt(table.columns[i], cells[i], line, namespace, hidden));
+        const quoted = table.quotedEmpty?.get(key)?.has(i) === true;
+        pushAtt(out, cellAtt(table.columns[i], cells[i], line, namespace, hidden, quoted));
     }
     return out;
 }
@@ -1305,8 +1318,9 @@ function sessionRecord(report: ImportReportBuilder, entry: string, message: stri
  * @param prepared - the prepared import
  * @param choice - the network
  * @param sink - the sink
+ * @returns the style the network uses, or null
  */
-async function import2(prepared: Prepared, choice: Choice2, sink: GraphSink): Promise<void> {
+async function import2(prepared: Prepared, choice: Choice2, sink: GraphSink): Promise<string | null> {
     const { report, inner, session } = prepared;
     const { doc, dialect } = await parseEntry(session, choice.file, report, inner);
     let unmatched = 0;
@@ -1343,6 +1357,7 @@ async function import2(prepared: Prepared, choice: Choice2, sink: GraphSink): Pr
     };
     const settings: XgmmlSettings = { labelAliases: true, cytoscapeEscapes: true, zAs: prepared.zAs };
     new XgmmlEmitter(doc, dialect, sink, report, inner, settings, extras).emit(null);
+    return cyMeta.visualStyle;
 }
 
 /**
@@ -1466,16 +1481,116 @@ function sessionMeta(
  */
 async function importChoice(prepared: Prepared, index: number, sink: GraphSink): Promise<ImportReport> {
     const choice = prepared.choices[index];
+    let visualStyle: string | null;
     if (choice.era === "3") {
         const parsed = prepared.docs.get(choice.network.name) as Parsed;
-        await import3(prepared, choice, sink, parsed);
+        visualStyle = await import3(prepared, choice, sink, parsed);
     } else {
-        await import2(prepared, choice, sink);
+        visualStyle = await import2(prepared, choice, sink);
     }
+    await keepStyleSource(prepared, index, visualStyle);
     throwIfAborted(prepared.common.signal);
     return prepared.report.finish();
 }
 
+/**
+ * Keep what the session's style reader needs (`styles()` gets it back as `context.kept`): the parsed
+ * `session_vizmap.xml` of a 3.x session, the style the imported view names, and which network was imported.
+ * Reading the styles never fails the import: a damaged entry is kept as the reason it cannot be read.
+ * @param prepared - the prepared import
+ * @param index - the network imported
+ * @param visualStyle - the style its view names, or null
+ */
+async function keepStyleSource(prepared: Prepared, index: number, visualStyle: string | null): Promise<void> {
+    const { layout } = prepared.session;
+    const entry = layout.styles.find((e) => e.path.endsWith("session_vizmap.xml"));
+    let vizmap: XmlNode | null = null;
+    let problem: string | null = null;
+    if (layout.era === "3" && entry !== undefined) {
+        const bytes = await entryBytes(prepared, entry);
+        const tree =
+            typeof bytes === "string"
+                ? bytes
+                : await parseXmlTree(bytes, entry.name, new ImportReportBuilder(FORMAT, 0), prepared.inner);
+        if (typeof tree === "string") {
+            problem = tree;
+        } else {
+            vizmap = tree;
+        }
+    }
+    const source: SessionStyleSource = {
+        era: layout.era,
+        vizmap,
+        problem,
+        visualStyle,
+        network: { index, name: prepared.choices[index].name },
+    };
+    prepared.report.keepForStyles(source);
+}
+
+/**
+ * An entry's bytes for the styles, read outside the import's report: a damaged entry is the reason, never a failure.
+ * @param prepared - the prepared import
+ * @param entry - the entry
+ * @returns the bytes, or why they cannot be read
+ */
+async function entryBytes(prepared: Prepared, entry: SessionEntry): Promise<Uint8Array | string> {
+    try {
+        return await prepared.session.read(entry, new ImportReportBuilder(FORMAT, 0));
+    } catch (err) {
+        if (err instanceof ImportError) {
+            return err.message;
+        }
+        throw err;
+    }
+}
+
+/**
+ * An entry's text for the styles, or null when it cannot be read.
+ * @param prepared - the prepared import
+ * @param entry - the entry
+ * @returns the text, or null
+ */
+async function entryText(prepared: Prepared, entry: SessionEntry): Promise<string | null> {
+    const bytes = await entryBytes(prepared, entry);
+    if (typeof bytes === "string") {
+        return null;
+    }
+    try {
+        return await readText(bytes, new ImportReportBuilder(FORMAT, 0), { signal: prepared.common.signal });
+    } catch (err) {
+        if (err instanceof ImportError) {
+            return null;
+        }
+        throw err;
+    }
+}
+
+/**
+ * A text att of the network.
+ * @param name - its name
+ * @param value - its text
+ * @returns the att
+ */
+function textAtt(name: string, value: string): AttRec {
+    return {
+        name,
+        type: "string",
+        cyType: "String",
+        elementType: null,
+        value,
+        hidden: false,
+        equation: false,
+        children: [],
+        extra: {},
+        xml: null,
+        hasGraph: false,
+        text: "",
+        line: 0,
+        namespace: null,
+    };
+}
+
 /**
  * Import one network of a session.
  * @param input - the session bytes
@@ -1599,4 +1714,5 @@ export const cysImporter: GraphImporter<CysImportOptions> = Object.freeze({
     import: importCys,
     importAll: importAllCys,
     listGraphs: listCysGraphs,
+    styles: readSessionStyles,
 });

package/src/formats/cys/session.ts

@@ -12,6 +12,7 @@ import { plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
 import { tokenizeXml, xmlDeclaredEncoding, XmlSyntaxError } from "../../common/xml.js";
 import { readZipDirectory, readZipEntry, type ZipEntry, ZipError } from "../../common/zip.js";
+import { STYLE_BLOCK_NAME } from "../../styles/io/block.js";
 import { ImportError, type ImportInput } from "../../types.js";
 import { CYS_ISSUE, FORMAT, MAX_RATIO } from "./constants.js";
 
@@ -83,6 +84,8 @@ interface SessionLayout {
     readonly files: ReadonlyMap<string, SessionEntry>;
     /** The style entries (`session_vizmap.xml`, `session_vizmap.props`). */
     readonly styles: readonly SessionEntry[];
+    /** 3.x: the `graphty.styles` entry a session graphty wrote holds, if present. */
+    readonly block: SessionEntry | null;
     /** Every entry the importer does not read. */
     readonly skipped: readonly string[];
 }
@@ -321,6 +324,7 @@ function layoutOf(zipEntries: readonly ZipEntry[], report: ImportReportBuilder):
         cysession: null as SessionEntry | null,
         files: new Map<string, SessionEntry>(),
         styles: [] as SessionEntry[],
+        block: null as SessionEntry | null,
         skipped: [] as string[],
     };
     for (const [name, zip] of byName) {
@@ -379,6 +383,8 @@ function classify3(entry: SessionEntry, layout: Mutable): void {
         layout.networkList = entry;
     } else if (/(^|\/)session_vizmap\.(xml|props)$/.test(path)) {
         layout.styles.push(entry);
+    } else if (path === STYLE_BLOCK_NAME) {
+        layout.block = entry;
     } else {
         layout.skipped.push(entry.name);
     }

package/src/formats/cys/styles.ts

@@ -0,0 +1,254 @@
+/**
+ * The styles of a Cytoscape session. A 3.x session keeps its named visual styles in `session_vizmap.xml` and each
+ * view names the one it uses (`cy:visualStyle`); the view's elements carry only their bypasses
+ * (`lockedVisualProperties`). The import reads the style the imported network's view names, resolved the way
+ * Cytoscape draws it (bypass over mapping over default), with Cytoscape's renderer fallbacks for what the style
+ * leaves unset. A 2.x session's network files carry every element's resolved values, read like XGMML, and its
+ * hidden elements come back invisible. The writer emits the graph's styles as a named style, bypasses and columns.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import { STYLE_ISSUE } from "../../styles/codes.js";
+import {
+    type CytoscapeMapping,
+    type CytoscapeStyle,
+    emptyCytoscapeStyle,
+    typedKey,
+} from "../../styles/cytoscape/mappings.js";
+import { cytoscapeBackground, type CytoscapeElements, resolveCytoscape } from "../../styles/cytoscape/resolve.js";
+import { cytoscapeRules } from "../../styles/cytoscape/translate.js";
+import { StyleNotes } from "../../styles/notes.js";
+import { dataCell } from "../../styles/plan/resolve.js";
+import type { ImporterStyles, ReaderOutput, StyleReadContext, StyleTarget } from "../../styles/types.js";
+import { exactFromBlock, graphicsBypasses, hiddenToVisible, nonEmpty, readXgmmlStyles } from "../xgmml/styles.js";
+import { HIDDEN_COLUMN } from "./constants.js";
+import type { XmlNode } from "./session.js";
+
+/**
+ * What a session import keeps for its styles (through `report.keepForStyles()`): the era, the parsed
+ * `session_vizmap.xml`, the style the imported network's view names, and which network was imported.
+ */
+export interface SessionStyleSource {
+    /** "3" for a 3.x session, "2" for a 2.x one. */
+    readonly era: "2" | "3";
+    /** The root element of `session_vizmap.xml`, or null when the session has none or it cannot be read. */
+    readonly vizmap: XmlNode | null;
+    /** Why `session_vizmap.xml` could not be read, or null. */
+    readonly problem: string | null;
+    /** The style the imported view names, or null. */
+    readonly visualStyle: string | null;
+    /** The network the import read: its index among the session's networks, and its name. */
+    readonly network: { readonly index: number; readonly name: string | null };
+}
+
+/**
+ * The styles of an imported session network.
+ * @param snapshot - the network
+ * @param context - what the import kept, the budget and the cancel signal
+ * @returns the styles
+ */
+export function readSessionStyles(snapshot: GraphSnapshot, context: StyleReadContext): ImporterStyles {
+    const kept = context.kept as SessionStyleSource | undefined;
+    if (kept?.era === "2") {
+        return readXgmmlStyles(snapshot, context, { tool: "cytoscape-fallbacks", hiddenColumn: HIDDEN_COLUMN });
+    }
+    const notes = new StyleNotes();
+    const style = sessionStyle(kept, notes);
+    const out: Record<StyleTarget, ReaderOutput> = { node: { values: {} }, edge: { values: {} } };
+    for (const target of ["node", "edge"] as const) {
+        context.signal?.throwIfAborted();
+        out[target] = sessionTargetStyles(snapshot, target, style, { notes, budget: context.budget });
+    }
+    const background = cytoscapeBackground(style, notes);
+    return {
+        canonical: true,
+        dialect: "cytoscape",
+        tool: "cytoscape-fallbacks",
+        units: "px",
+        node: out.node,
+        edge: out.edge,
+        graph: background === null ? {} : { background },
+        notes: notes.list(),
+    };
+}
+
+/**
+ * The Cytoscape style of a session: its vizmap's, or an empty one with a note saying why there is none.
+ * @param kept - what the import kept
+ * @param notes - where problems are noted
+ * @returns the style
+ */
+function sessionStyle(kept: SessionStyleSource | undefined, notes: StyleNotes): CytoscapeStyle {
+    if (kept?.vizmap === null || kept?.vizmap === undefined) {
+        const problem = kept?.problem ?? null;
+        notes.add(problem === null ? STYLE_ISSUE.NO_VIZMAP : STYLE_ISSUE.UNREADABLE, null, "session_vizmap.xml", {
+            sample: problem ?? "absent",
+        });
+        return emptyCytoscapeStyle();
+    }
+    return cytoscapeStyleFromVizmap(kept.vizmap, kept.visualStyle, notes);
+}
+
+/**
+ * The styles of a session's nodes or edges.
+ * @param snapshot - the network
+ * @param target - nodes or edges
+ * @param style - the session's style
+ * @param work - where problems are noted, and the work budget
+ * @param work.notes - where problems are noted
+ * @param work.budget - the work budget
+ * @returns the reader output for the target
+ */
+function sessionTargetStyles(
+    snapshot: GraphSnapshot,
+    target: StyleTarget,
+    style: CytoscapeStyle,
+    work: { readonly notes: StyleNotes; readonly budget: StyleReadContext["budget"] },
+): ReaderOutput {
+    const { notes } = work;
+    const table = target === "node" ? snapshot.nodes : snapshot.edges;
+    const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+    for (const m of style[target].mappings.values()) {
+        if (!table.has(m.column)) {
+            notes.add(STYLE_ISSUE.MAPPING_COLUMN_MISSING, target, m.column, { sample: m.kind });
+        }
+    }
+    const elements: CytoscapeElements = {
+        count: n,
+        value: (column, i) => (table.has(column) ? dataCell(table, column, i) : null),
+        bypasses: graphicsBypasses(table, target, n, notes),
+    };
+    const values = resolveCytoscape(target, style, elements, work);
+    hiddenToVisible(table, HIDDEN_COLUMN, n, values);
+    // a session graphty wrote: a value its style writes as the nearest Cytoscape value is the block's
+    exactFromBlock(snapshot, target, values);
+    const { rules, columns } = cytoscapeRules(target, style, elements, work);
+    return { values: nonEmpty(values), rules, columns };
+}
+
+/**
+ * One named style of a `session_vizmap.xml` as a Cytoscape style: the one named `name`, else the first with a
+ * `W_STYLE_VIEW_STYLE_MISSING` note; the other styles are noted as `W_STYLE_OTHER_STYLES`.
+ * @param root - the `<vizmap>` element
+ * @param name - the style the view names, or null
+ * @param notes - where problems are noted
+ * @returns the style
+ */
+function cytoscapeStyleFromVizmap(root: XmlNode, name: string | null, notes: StyleNotes): CytoscapeStyle {
+    const style = emptyCytoscapeStyle();
+    const styles = root.children.filter((c) => c.name === "visualStyle");
+    let chosen = styles.find((s) => s.attrs.get("name") === name);
+    if (chosen === undefined) {
+        chosen = styles.at(0);
+        if (chosen === undefined) {
+            notes.add(STYLE_ISSUE.NO_VIZMAP, null, "visualStyle", { sample: "no visualStyle" });
+            return style;
+        }
+        notes.add(STYLE_ISSUE.VIEW_STYLE_MISSING, null, "visualStyle", { sample: String(name) });
+    }
+    if (styles.length > 1) {
+        notes.add(STYLE_ISSUE.OTHER_STYLES, null, "visualStyle", {
+            sample: `${styles.length - 1} unused`,
+            count: styles.length - 1,
+        });
+    }
+    for (const kind of ["network", "node", "edge"] as const) {
+        const section = chosen.children.find((c) => c.name === kind);
+        for (const child of section?.children ?? []) {
+            readVizmapEntry(style, kind, child);
+        }
+    }
+    return style;
+}
+
+/**
+ * One dependency or visual property of a vizmap style section, into the style.
+ * @param style - the style being read
+ * @param kind - the section
+ * @param child - the entry
+ */
+function readVizmapEntry(style: CytoscapeStyle, kind: "network" | "node" | "edge", child: XmlNode): void {
+    const childName = child.attrs.get("name");
+    if (childName === undefined) {
+        return;
+    }
+    if (child.name === "dependency" && kind !== "network") {
+        style[kind].dependencies.set(childName, child.attrs.get("value")?.trim().toLowerCase() === "true");
+        return;
+    }
+    if (child.name !== "visualProperty") {
+        return;
+    }
+    const d = child.attrs.get("default");
+    if (d !== undefined) {
+        style[kind].defaults.set(childName, d);
+    }
+    if (kind !== "network") {
+        const mapping = vizmapMapping(child);
+        if (mapping !== null) {
+            style[kind].mappings.set(childName, mapping);
+        }
+    }
+}
+
+/**
+ * The mapping of one `<visualProperty>`: a passthrough, discrete or continuous mapping element.
+ * @param vp - the element
+ * @returns the mapping, or null
+ */
+function vizmapMapping(vp: XmlNode): CytoscapeMapping | null {
+    for (const m of vp.children) {
+        const column = m.attrs.get("attributeName");
+        if (column === undefined) {
+            continue;
+        }
+        const type = m.attrs.get("attributeType") ?? null;
+        if (m.name === "passthroughMapping") {
+            return { kind: "passthrough", column, type };
+        }
+        if (m.name === "discreteMapping") {
+            return { kind: "discrete", column, type, table: discreteTable(m, type) };
+        }
+        if (m.name === "continuousMapping") {
+            return { kind: "continuous", column, type, points: continuousPoints(m) };
+        }
+    }
+    return null;
+}
+
+/**
+ * The entries of a `<discreteMapping>`.
+ * @param m - the element
+ * @param type - the attribute type its keys are read as
+ * @returns the key and value of each entry
+ */
+function discreteTable(m: XmlNode, type: string | null): [string | number | boolean, unknown][] {
+    const table: [string | number | boolean, unknown][] = [];
+    for (const e of m.children) {
+        const key = typedKey(e.attrs.get("attributeValue"), type);
+        const value = e.attrs.get("value");
+        if (e.name === "discreteMappingEntry" && key !== null && value !== undefined) {
+            table.push([key, value]);
+        }
+    }
+    return table;
+}
+
+/**
+ * The points of a `<continuousMapping>`.
+ * @param m - the element
+ * @returns the points with a finite position
+ */
+function continuousPoints(
+    m: XmlNode,
+): { at: number; below: string | undefined; value: string | undefined; above: string | undefined }[] {
+    return m.children
+        .filter((p) => p.name === "continuousMappingPoint" && Number.isFinite(Number(p.attrs.get("attrValue"))))
+        .map((p) => ({
+            at: Number(p.attrs.get("attrValue")),
+            below: p.attrs.get("lesserValue"),
+            value: p.attrs.get("equalValue"),
+            above: p.attrs.get("greaterValue"),
+        }));
+}