@graphty/graph-io 0.3.46 → 0.3.48

package/src/styles/defaults.ts

@@ -48,6 +48,39 @@ export type ToolDerivedDefault =
           /** Where the default is stated. */
           readonly source: string;
       }
+    | {
+          /**
+           * An edge with no color of its own takes the mean of its two nodes' colors, each channel rounded down
+           * (Gephi Preview's "mixed" edge color).
+           */
+          readonly kind: "colorFromEndNodes";
+          /** Where the default is stated. */
+          readonly source: string;
+      }
+    | {
+          /**
+           * A node with no border of its own gets a border of its fill with each channel times `darken`, `widthFactor`
+           * times its width wide (Gephi Preview's "darker" border, scaled with the node).
+           */
+          readonly kind: "borderFromFill";
+          /** What each color channel of the fill is multiplied by. */
+          readonly darken: number;
+          /** The border's width as a share of the node's width. */
+          readonly widthFactor: number;
+          /** Where the default is stated. */
+          readonly source: string;
+      }
+    | {
+          /**
+           * A node with no label size of its own gets a label size of its width times `factor` (Gephi Preview's
+           * proportional label size).
+           */
+          readonly kind: "labelSizeFromWidth";
+          /** The label size per unit of the node's width. */
+          readonly factor: number;
+          /** Where the default is stated. */
+          readonly source: string;
+      }
     | {
           /** An edge with no width of its own is drawn as thick as its weight (1 for an edge with no weight, or a weight of 0 or below). */
           readonly kind: "widthFromWeight";
@@ -101,10 +134,12 @@ const GV = "graphviz.org/docs/attrs";
 const YED_QA = "yEd Q&A, How can I change the default nodes and/or default edges";
 const YED_CORPUS = "yEd GraphML corpus, most frequent value";
 const YED_EDGE = "yFiles for Java 2.19 EdgeRealizer API docs";
+const YED_BG = "yFiles for Java 2.19 DefaultBackgroundRenderer API docs";
 const Y3 = "yFiles for HTML API docs,";
 const GEPHI = "gephi master 92e503df61a7";
 const VIS = "vis-network 10.1.2 vis-network.esm.js";
 const SIGMA = "sigma 3.0.3 packages/sigma/src";
+const GEXFJS = "github.com/raphv/gexf-js ebfd2a7213d3 js/gexfjs.js";
 const PAJEK = "Pajek 6.02 reference manual";
 const PAJEK_SHAPES =
     "the SHAPES.CFG Pajek writes when none exists (DrawEPS.htm), " +
@@ -259,7 +294,12 @@ export const TOOL_DEFAULTS: ReadonlyMap<StyleTool, ToolDefaults> = new Map<Style
                     labelSize: v(14, `${GV}/fontsize/`),
                     labelFont: v("Times-Roman", `${GV}/fontname/`),
                 },
-                graph: {},
+                graph: {
+                    background: v(
+                        "#ffffff",
+                        `${GV}/bgcolor/ (default none); lib/common/emit.c emit_background: no bgcolor paints white`,
+                    ),
+                },
                 derived: [
                     { kind: "labelFromId", source: String.raw`${GV}/label/ (default \N, the node name)` },
                     {
@@ -295,7 +335,12 @@ export const TOOL_DEFAULTS: ReadonlyMap<StyleTool, ToolDefaults> = new Map<Style
                     labelFont: v("Dialog", `${YED_CORPUS} of y:EdgeLabel`),
                     labelSize: v(12, `${YED_CORPUS} of y:EdgeLabel`),
                 },
-                graph: {},
+                graph: {
+                    background: v(
+                        "#ffffff",
+                        `${YED_BG} (setColor: "By default the background color is white"); yEd manual, Preferences, Background tab`,
+                    ),
+                },
                 derived: [],
             },
             {
@@ -332,20 +377,64 @@ export const TOOL_DEFAULTS: ReadonlyMap<StyleTool, ToolDefaults> = new Map<Style
                     width: v(10, `${GEPHI} AbstractProcessor.java lines 195-198`),
                     height: v(10, `${GEPHI} AbstractProcessor.java lines 195-198`),
                     shape: v("ellipse", "GEXF 1.3 viz shape default disc; Preview NodeRenderer"),
+                    opacity: v(1, `${GEPHI} DefaultPreset.java line 87 (NODE_OPACITY 100)`),
+                    // Preview hides labels (DefaultPreset.java line 106) and so does the Overview (VizConfig.java
+                    // line 113); graph-io shows them as sigma.js and gexf-js do (see formats/gexf/styles.ts), in
+                    // the color and font Gephi gives a label it shows
+                    labelColor: v("#000000", `${GEPHI} DefaultPreset.java line 91 (DependantOriginalColor(BLACK))`),
+                    labelFont: v("Arial", `${GEPHI} DefaultPreset.java line 93 (Arial plain 12)`),
+                    // the size of a size-10 node's label; Preview scales it with the node (labelSizeFromWidth below)
+                    labelSize: v(12, `${GEPHI} DefaultPreset.java line 93 (Arial plain 12)`),
                     labelPosition: v(
                         "center",
                         `${GEPHI} NodeLabelRenderer.java (a label is drawn centered on its node)`,
                     ),
                 },
                 edge: {
+                    curved: v(
+                        true,
+                        `${GEPHI} DefaultPreset.java line 66 (EDGE_CURVED true); EdgeRenderer.java line 117`,
+                    ),
                     sourceArrow: v("none", `${GEPHI} DefaultPreset.java line 62`),
                     targetArrow: v("none", `${GEPHI} DefaultPreset.java line 62`),
+                    // the vocabulary's 1 is the tool's normal arrow: Preview's ARROW_SIZE 3, drawn 3 times the edge's
+                    // weight long, as Cytoscape.js's arrow-scale 1 scales with the edge's width
+                    arrowSize: v(
+                        1,
+                        `${GEPHI} DefaultPreset.java line 62 (ARROW_SIZE 3); EdgeRenderer.java lines 255-256 (times the weight)`,
+                    ),
+                    opacity: v(1, `${GEPHI} DefaultPreset.java line 71 (EDGE_OPACITY 100)`),
                 },
                 graph: { background: v("#ffffff", `${GEPHI} VizConfig.java line 111`) },
                 derived: [
                     {
-                        kind: "colorFromSourceNode",
-                        source: `${GEPHI} VizConfig.java line 119 (EdgeColorMode.SOURCE)`,
+                        kind: "labelFromColumn",
+                        column: "label",
+                        source: `${SIGMA}/settings.ts lines 119-126 (renderLabels); ${GEXFJS} lines 1019-1040`,
+                    },
+                    {
+                        kind: "colorFromEndNodes",
+                        source:
+                            `${GEPHI} DefaultPreset.java line 65 (EdgeColor.Mode.MIXED); ` +
+                            "PreviewAPI types/EdgeColor.java lines 89-93",
+                    },
+                    {
+                        kind: "borderFromFill",
+                        darken: 0.498,
+                        widthFactor: 0.08,
+                        source:
+                            `${GEPHI} DefaultPreset.java lines 84, 86 (DependantColor DARKER, NODE_BORDER_FIXED false); ` +
+                            "PreviewAPI types/DependantColor.java lines 55, 85-86; Utils ColorUtils.java lines 22-34; " +
+                            "PreviewPlugin renderers/SizeUtils.java lines 11, 33-38 (0.16 x size / 2 of a node drawn " +
+                            "size x 2 wide, builders/NodeBuilder.java line 65)",
+                    },
+                    {
+                        kind: "labelSizeFromWidth",
+                        factor: 1.2,
+                        source:
+                            `${GEPHI} DefaultPreset.java lines 93, 98 (Arial 12, NODE_LABEL_PROPORTIONAL_SIZE true); ` +
+                            "PreviewPlugin renderers/NodeLabelRenderer.java lines 165-173 (12 x the node drawn size x 2 " +
+                            "wide x 0.05, builders/NodeBuilder.java line 65)",
                     },
                     {
                         kind: "widthFromWeight",

package/src/styles/io/block.ts

@@ -727,6 +727,15 @@ function predicate(v: unknown): Predicate {
     return o as Predicate;
 }
 
+/**
+ * A positive finite number.
+ * @param v - the parsed value
+ * @returns the number
+ */
+function positive(v: unknown): number {
+    return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : invalid();
+}
+
 /**
  * A mapping. A mapping of a kind this version does not know is kept and gives no value.
  * @param v - the parsed mapping
@@ -760,6 +769,7 @@ function mapping(v: unknown): Mapping {
                         above: scalar(q.above),
                     };
                 }),
+                ...(o.step === undefined ? {} : { step: positive(o.step) }),
             };
         default:
             return { ...o, kind: name(o.kind), by } as unknown as Mapping;

package/src/styles/io/writer.ts

@@ -9,6 +9,7 @@ import type { GraphSnapshot } from "@graphty/graph-format";
 import { agree, plural } from "../../common/plural.js";
 import type { GraphExporter, LossNote } from "../../types.js";
 import { STYLE_ISSUE } from "../codes.js";
+import { toolDefaults } from "../defaults.js";
 import { styleFingerprint } from "../plan/features.js";
 import { canonicalFor, dataCell, degreeValues, plainCell, resolveStyles } from "../plan/resolve.js";
 import type {
@@ -516,7 +517,8 @@ function lossNotes(
 }
 
 /**
- * W_STYLE_NOT_WRITTEN for every graph property the format does not write.
+ * W_STYLE_NOT_WRITTEN for every graph property the format does not write, except one whose value is what the program
+ * the format is written for draws anyway (a white background for yEd): nothing is lost there.
  * @param extracted - the styles
  * @param exporter - the exporter
  * @param caps - its style capabilities, or null
@@ -528,8 +530,11 @@ function graphLossNotes(
     caps: StyleWriteCapabilities | null,
 ): LossNote[] {
     const graphWritten = new Set<string>(caps?.graph ?? []);
-    return Object.keys(extracted.styles.graph)
-        .filter((property) => !graphWritten.has(property))
+    const drawn: Readonly<Record<string, { readonly value: unknown } | undefined>> =
+        (caps?.tool === undefined ? null : toolDefaults(caps.tool))?.graph ?? {};
+    return Object.entries(extracted.styles.graph)
+        .filter(([property, value]) => !graphWritten.has(property) && drawn[property]?.value !== value)
+        .map(([property]) => property)
         .map((property) =>
             Object.freeze({
                 code: STYLE_ISSUE.NOT_WRITTEN,

package/src/styles/plan/resolve.ts

@@ -481,9 +481,21 @@ export function interpolate(a: StyleValue, b: StyleValue, t: number): StyleValue
  * Evaluates a continuous mapping at x.
  * @param points - the points, in increasing `at`
  * @param x - the input
+ * @param step - when given, a number is rounded to the nearest multiple of it (a whole-number property)
  * @returns the value, or null for a missing or non-finite input
  */
-export function evalContinuous(points: readonly ContinuousPoint[], x: number | null): StyleValue | null {
+export function evalContinuous(points: readonly ContinuousPoint[], x: number | null, step?: number): StyleValue | null {
+    const v = evalPoints(points, x);
+    return typeof v === "number" && step !== undefined && step > 0 ? num6(Math.round(v / step) * step) : v;
+}
+
+/**
+ * A continuous mapping's value at x, unrounded.
+ * @param points - the points, in increasing `at`
+ * @param x - the input
+ * @returns the value, or null for a missing or non-finite input
+ */
+function evalPoints(points: readonly ContinuousPoint[], x: number | null): StyleValue | null {
     if (x === null || !Number.isFinite(x) || points.length === 0) {
         return null;
     }
@@ -539,7 +551,7 @@ function evalMapping(
             return j < 0 ? null : m.table[j][1];
         }
         case "continuous":
-            return Array.isArray(v) ? null : evalContinuous(m.points, numberOf(v));
+            return Array.isArray(v) ? null : evalContinuous(m.points, numberOf(v), m.step);
         default:
             return null;
     }

package/src/styles/types.ts

@@ -83,11 +83,21 @@ export type StyleArrowShape =
 export type StyleLabelWeight = "normal" | "bold";
 
 /**
- * Where a node's label sits relative to the node.
+ * Where a node's label sits relative to the node. The sides and corners are outside the node (`top` is above it);
+ * `inside-top` is inside the node, along its top edge (a group box's title).
  * @category Styles
  */
 export type StyleLabelPosition =
-    "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    | "center"
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right"
+    | "inside-top";
 
 /**
  * The neutral node properties and the type of each value. Lengths are in the unit `FileStyles.units.length`
@@ -421,6 +431,11 @@ export type Mapping =
           readonly by: ColumnRef;
           /** The points, in increasing `at`. */
           readonly points: readonly ContinuousPoint[];
+          /**
+           * When set, a number the mapping gives is rounded to the nearest multiple of `step`, as the writing tool
+           * draws a property that holds whole numbers (Cytoscape's font size: 1; its 0..255 transparency: 1/255).
+           */
+          readonly step?: number;
       };
 
 /**
@@ -448,6 +463,12 @@ export type StyleRuleReason =
     | "LAYER_CAP"
     /** Edges with no color of their own take their source node's color, as the writing tool draws them. */
     | "SOURCE_NODE_COLOR"
+    /** Edges with no color of their own take the mean of their two nodes' colors, as the writing tool draws them. */
+    | "END_NODES_COLOR"
+    /** Nodes with no border of their own get a border darker than their fill and scaled with their size, as the writing tool draws them. */
+    | "FILL_BORDER"
+    /** Nodes with no label size of their own get a label size scaled with their size, as the writing tool draws them. */
+    | "NODE_SIZE_LABEL"
     /** Edges with no width of their own are as thick as their weight, as the writing tool draws them. */
     | "EDGE_WEIGHT"
     /** Nodes with no label of their own show their name, as the writing tool draws them (Graphviz's `\N`). */
@@ -792,6 +813,11 @@ export interface StyleWriteCapabilities {
     readonly edge: readonly EdgeStyleProperty[];
     /** Graph properties written natively. */
     readonly graph?: readonly GraphStyleProperty[];
+    /**
+     * The program that draws the files this writer writes, when there is one. A graph property the format has no
+     * place for is not reported lost when its value is what that program draws anyway (its tool default).
+     */
+    readonly tool?: StyleTool;
     /** Where the block and the tagged values go. */
     readonly block: "native" | "attributes" | "none";
 }

package/src/styles/vocabulary.ts

@@ -129,7 +129,21 @@ export const STYLE_ENUMS: ReadonlyMap<StyleValueKind, readonly string[]> = new M
         ],
     ],
     ["weight", ["normal", "bold"]],
-    ["position", ["center", "top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"]],
+    [
+        "position",
+        [
+            "center",
+            "top",
+            "bottom",
+            "left",
+            "right",
+            "top-left",
+            "top-right",
+            "bottom-left",
+            "bottom-right",
+            "inside-top",
+        ],
+    ],
 ]);
 
 /** The enumerations that keep unknown spellings as `other:<raw>`. */

package/src/types.ts

@@ -18,6 +18,8 @@ import {
 } from "@graphty/graph-format";
 
 import type { ImporterPositions, PositionReadContext } from "./positions/types.js";
+import { type SourceIssueCode } from "./sources/codes.js";
+import { type SourceReportInfo } from "./sources/types.js";
 import type {
     EdgeStyleProperty,
     GraphStyleProperty,
@@ -170,9 +172,10 @@ export interface CommonImportOptions {
      * Called as the input is read, with the bytes read so far and the total. For a string or a
      * Uint8Array the total is known from the first call. For a stream (which includes loadFromUrl()
      * and loadFromFile()) it is undefined until the last call, which always has
-     * `bytesDone === bytesTotal`. Text counts its UTF-8 length.
+     * `bytesDone === bytesTotal`. Text counts its UTF-8 length. A load from a network source passes a
+     * third argument, "bytes" or "items", saying what is counted.
      */
-    onProgress?: ((bytesDone: number, bytesTotal?: number) => void) | undefined;
+    onProgress?: ((bytesDone: number, bytesTotal?: number, unit?: "items" | "bytes") => void) | undefined;
     /**
      * The character encoding of byte input, as a label such as "utf-8", "windows-1252" or
      * "utf-16le". Without it graph-io uses a byte order mark, then the encoding the file declares
@@ -553,9 +556,18 @@ export interface ImportIssue {
      * kept, possibly changed.
      */
     readonly severity: "error" | "warning";
-    /** A stable code; E_ for errors, W_ for warnings ("E_UNKNOWN_NODE", "W_WIDENED"). */
-    readonly code: string;
-    /** A plain-English message. */
+    /**
+     * A stable code; E_ for errors, W_ for warnings ("E_UNKNOWN_NODE", "W_WIDENED"). The network
+     * source codes (`SOURCE_ISSUE`) autocomplete; every other code is a string.
+     */
+    readonly code: SourceIssueCode | (string & {}); // NOSONAR(S4335): open string union, keeps the known names autocompleting
+    /**
+     * The issue's machine-readable values (`{ status: 401 }`), when it has any. Every network source
+     * issue has them (`SourceIssueParams` maps each code to its shape); an application writes its
+     * own words from the code and these values.
+     */
+    readonly params?: Readonly<Record<string, unknown>> | undefined;
+    /** A plain-English message, for logs. */
     readonly message: string;
     /** The 1-based line in the input, or null when the format has no lines or it is unknown. */
     readonly line: number | null;
@@ -598,6 +610,8 @@ export interface ImportReport {
     readonly lossy: readonly LossNote[];
     /** How long reading the file took, in milliseconds. */
     readonly durationMs: number;
+    /** What a load from a network source did: requests, bytes, where to resume. Experimental. */
+    readonly source?: SourceReportInfo | undefined;
 }
 
 /**