@graphty/graph-io 0.3.43 → 0.3.45

package/dist/src/formats/json/styles.d.ts

@@ -0,0 +1,102 @@
+/**
+ * JSON styles: each dialect read the way the program that draws it draws it, and a graph's styles written back into
+ * each dialect's own style keys.
+ *
+ * - Cytoscape.js: the stylesheet (an array or a CSS-like text) over the raw element JSON, through graph-io's
+ *   Cytoscape.js engine, with Cytoscape.js's defaults beneath it; an element's own `style` is a bypass. Cytoscape
+ *   desktop's export without a stylesheet gets Cytoscape desktop's default style instead.
+ * - graphology: the keys sigma.js draws (`color`, `size`, `label`, `hidden`), with sigma's defaults. Gephi's JSON
+ *   export for sigma.js is read the same way.
+ * - vis.js: the keys vis-network draws, `options.nodes` and `options.edges` as declared defaults and
+ *   `options.groups` as group rules, with vis-network's defaults, its palette for groups the file does not define,
+ *   and an edge without a color of its own in its source node's border color.
+ * - NetworkX node-link: no style keys, NetworkX's drawing defaults.
+ *
+ * Writing: Cytoscape.js gets a stylesheet with the element data its selectors read and a bypass where no rule gives
+ * the value; graphology and vis.js get their per-element keys; node-link, d3 and JGF only the `graphty.styles` block
+ * and the tagged per-element values. The block is a graph attribute where the dialect has graph attributes
+ * (node-link, JGF, graphology) and a top-level key elsewhere (d3, vis.js, Cytoscape.js).
+ */
+import type { GraphSnapshot } from "@graphty/graph-format";
+import { type CytoscapeStylesheetRule } from "../../styles/cyjs/emit.js";
+import type { ExporterStyleInput } from "../../styles/io/writer.js";
+import type { ImporterStyles, StyleReadContext, StyleTarget, StyleWriteCapabilities } from "../../styles/types.js";
+import type { LossNote } from "../../types.js";
+import { type JsonDialect, type JsonImportDialect } from "./dialect.js";
+/**
+ * What a JSON import keeps for its styles (`report.keepForStyles()`): the dialect, a `graphty.styles` block the
+ * document holds as a top-level key, and what each dialect's reader needs beyond the graph.
+ */
+export interface JsonStyleSource {
+    /** The dialect the document was read as. */
+    readonly dialect: JsonImportDialect;
+    /** A `graphty.styles` block held as a top-level key, or null. */
+    readonly block: string | null;
+    /** Cytoscape.js: the elements as the file holds them. */
+    readonly elements?: unknown;
+    /** Cytoscape.js: the stylesheet, as the file holds it. */
+    readonly style?: unknown;
+    /** Cytoscape.js: the `generated_by` of Cytoscape desktop's export, or null. */
+    readonly generatedBy?: string | null;
+    /** Cytoscape.js: the id graph-io gave each node element without a `data.id`. */
+    readonly generatedIds?: ReadonlyMap<object, string>;
+    /** vis.js: the document's `options`. */
+    readonly options?: unknown;
+    /** vis.js: a top-level `groups` object. */
+    readonly groups?: unknown;
+    /** graphology: whether the document is Gephi's JSON export (`id` instead of `key`). */
+    readonly gephi?: boolean;
+    /** node-link: whether the document has NetworkX's `directed`, `multigraph` and `graph` keys. */
+    readonly networkx?: boolean;
+}
+/**
+ * The styles of a JSON document, read by its dialect's reader from what the import kept.
+ * @param snapshot - the graph the import built
+ * @param context - the work budget and what the import kept
+ * @returns the styles, or null when the dialect has none (a block held as a graph attribute is read by graph-io)
+ */
+export declare function jsonStyles(snapshot: GraphSnapshot, context: StyleReadContext): ImporterStyles | null;
+/**
+ * The neutral properties each style-writing dialect holds natively. Not part of the published entry points: the
+ * documentation's per-dialect tables read it, through a dynamic import knip cannot follow (hence public).
+ * @public
+ */
+export declare const NATIVE: Readonly<Record<"cytoscape" | "graphology" | "vis", Readonly<Record<StyleTarget, readonly string[]>>>>;
+/**
+ * What the JSON writer holds natively, over every dialect: Cytoscape.js's stylesheet, vis.js's and graphology's
+ * per-element keys. A dialect that holds less (node-link, d3, JGF hold none) reports the rest from `check()`. The
+ * block goes where each dialect keeps extra data.
+ * @category Built-in formats
+ */
+export declare const JSON_STYLE_CAPABILITIES: StyleWriteCapabilities;
+/** A JSON export with styles worked out. */
+export interface JsonStyledExport {
+    /** The graph to write: the per-element style keys, the tagged values and, where it belongs there, the block. */
+    readonly snapshot: GraphSnapshot;
+    /** The block to write as a top-level key (d3, vis.js, Cytoscape.js), or null. */
+    readonly topLevelBlock: string | null;
+    /** Cytoscape.js: the stylesheet to write as `style`, or null. */
+    readonly stylesheet: readonly CytoscapeStylesheetRule[] | null;
+    /**
+     * vis.js: the `groups` to write, one empty definition per value of the nodes' `group` key, or null. vis-network
+     * colors a node of a group the file does not define from its own palette; a defined group draws nothing of its
+     * own, so the nodes look as graphty draws them.
+     */
+    readonly groups?: Readonly<Record<string, Readonly<Record<string, never>>>> | null;
+    /** What the dialect does not hold, or holds only approximately. */
+    readonly notes: readonly LossNote[];
+}
+/**
+ * Works out a JSON export with styles for one dialect.
+ * @param snapshot - the graph handed to the exporter
+ * @param dialect - the dialect written
+ * @param input - the styles, or undefined when none are written
+ * @returns the styled export, or null without styles
+ */
+export declare function jsonStyledExport(snapshot: GraphSnapshot, dialect: JsonDialect, input: ExporterStyleInput | undefined): JsonStyledExport | null;
+/**
+ * The code of the note that a data value held under a style key is replaced by what graphty draws.
+ * @category Built-in formats
+ */
+export declare const STYLE_KEY_REPLACED_CODE = "W_JSON_STYLE_KEY_REPLACED";
+//# sourceMappingURL=styles.d.ts.map

package/dist/src/formats/json/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../../../src/formats/json/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAS3D,OAAO,EAGH,KAAK,uBAAuB,EAE/B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAIpE,OAAO,KAAK,EAGR,cAAc,EAKd,gBAAgB,EAEhB,WAAW,EAEX,sBAAsB,EACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC/B;AAWD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,GAAG,cAAc,GAAG,IAAI,CAoBpG;AAssCD;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CACzB,MAAM,CAAC,WAAW,GAAG,YAAY,GAAG,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC,CA0C/F,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,sBAQpC,CAAC;AAEH,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC7B,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,SAAS,uBAAuB,EAAE,GAAG,IAAI,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACnF,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC5B,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,kBAAkB,GAAG,SAAS,GACtC,gBAAgB,GAAG,IAAI,CA+CzB;AAmUD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,8BAA8B,CAAC"}