@graphty/graph-io 0.3.49 → 0.3.50

package/src/styles/cyjs/cascade.ts

@@ -1354,6 +1354,7 @@ function evaluateTarget(
     if (kind === "node") {
         const read: DrawnRead = { kind, els, cells, order, rendered: input.rendered, notes };
         nodeSizes(graph, read, drawn);
+        groupBoxes(graph, read, drawn);
         mixedLabelPlaces(graph, read, drawn);
     }
     if (kind === "edge") {
@@ -1787,6 +1788,8 @@ const CYJS_EDGE_ONLY: ReadonlySet<string> = new Set([
     "target-text-margin-y",
     "source-text-rotation",
     "target-text-rotation",
+    "source-distance-from-node",
+    "target-distance-from-node",
 ]);
 
 /**
@@ -2839,6 +2842,146 @@ function nodeSizes(graph: CyjsGraph, read: DrawnRead, values: Record<string, (St
     }
 }
 
+/** The words of a compound parent's sizing properties. */
+const PADDING_OF_PART: CyjsPropertySpec = {
+    property: "_paddingOf",
+    type: "enum",
+    enums: ["width", "height", "average", "min", "max"],
+};
+const LABELS_PART: CyjsPropertySpec = { property: "_compoundLabels", type: "enum", enums: ["include", "exclude"] };
+
+/**
+ * A length or a percentage as Cytoscape.js spells it.
+ * @param text - the value, or null
+ * @returns the number and whether it is a percentage, or null for none or a non-number
+ */
+function measureOf(text: StyleValue | null | undefined): { value: number; percent: boolean } | null {
+    if (typeof text !== "string" && typeof text !== "number") {
+        return null;
+    }
+    const value = Number.parseFloat(String(text));
+    return Number.isFinite(value) ? { value, percent: String(text).trim().endsWith("%") } : null;
+}
+
+/**
+ * The share of a minimum's growth on the near side (left, top), as Cytoscape.js 3.34.3 `updateCompoundBounds`
+ * splits it: each bias a percentage, a length read as its percentage of the minimum, the near side's share of
+ * their sum; no bias on either side grows both sides alike.
+ * @param near - the near side's bias
+ * @param far - the far side's bias
+ * @param min - the minimum
+ * @returns the near side's share, or null for half
+ */
+function biasShare(
+    near: StyleValue | null | undefined,
+    far: StyleValue | null | undefined,
+    min: number,
+): number | null {
+    const percent = (text: StyleValue | null | undefined): number => {
+        const m = measureOf(text);
+        if (m === null || m.value <= 0) {
+            return 0;
+        }
+        return m.percent ? m.value : (m.value * 100) / min;
+    };
+    const a = percent(near);
+    const total = a + percent(far);
+    return total > 0 ? a / total : null;
+}
+
+/**
+ * How Cytoscape.js sizes a compound parent round its children (cytoscape.js 3.34.3 `updateCompoundBounds`): its
+ * `padding` past their box (a percentage is of the box, `padding-relative-to`), at least `min-width` by `min-height`
+ * before the padding, grown by the biases' shares, its children's labels counted unless `compound-sizing-wrt-labels`
+ * is `exclude`. Written for every compound parent, so the group is drawn as Cytoscape.js draws it.
+ * @param graph - the core's elements
+ * @param read - the nodes' cells
+ * @param values - the nodes' values; changed in place
+ */
+function groupBoxes(graph: CyjsGraph, read: DrawnRead, values: Record<string, (StyleValue | null)[]>): void {
+    const word = (name: string, spec: CyjsPropertySpec = TEXT_PART): (StyleValue | null | undefined)[] =>
+        drawnColumn(read, name, spec);
+    const padding = word("padding");
+    const paddingOf = word("padding-relative-to", PADDING_OF_PART);
+    const labels = word("compound-sizing-wrt-labels", LABELS_PART);
+    const axes = [
+        { min: word("min-width"), near: word("min-width-bias-left"), far: word("min-width-bias-right") },
+        { min: word("min-height"), near: word("min-height-bias-top"), far: word("min-height-bias-bottom") },
+    ];
+    const names = [
+        ["groupMinWidth", "groupMinWidthBiasLeft"],
+        ["groupMinHeight", "groupMinHeightBiasTop"],
+    ];
+    const n = read.order.length;
+    const put = (p: string, k: number, v: StyleValue): void => {
+        const column = values[p] ?? new Array<StyleValue | null>(n).fill(null);
+        values[p] = column;
+        column[k] = v;
+    };
+    for (let k = 0; k < n; k++) {
+        const core = read.order[k];
+        if (core < 0 || graph.children[core].length === 0) {
+            continue;
+        }
+        for (const [p, v] of groupPaddingValues(padding[k], paddingOf[k])) {
+            put(p, k, v);
+        }
+        put("groupIncludeLabels", k, labels[k] !== "exclude");
+        axes.forEach((axis, a) => {
+            for (const [p, v] of groupMinValues(axis.min[k], axis.near[k], axis.far[k], names[a])) {
+                put(p, k, v);
+            }
+        });
+    }
+}
+
+/**
+ * A compound parent's padding as neutral values: a length, or a fraction of the side `padding-relative-to` names.
+ * @param padding - the padding as Cytoscape.js spells it
+ * @param of - its `padding-relative-to`
+ * @returns the properties and their values
+ */
+function groupPaddingValues(
+    padding: StyleValue | null | undefined,
+    of: StyleValue | null | undefined,
+): [string, StyleValue][] {
+    const pad = measureOf(padding);
+    if (pad?.percent !== true) {
+        return [["groupPadding", Math.max(0, pad?.value ?? 0)]];
+    }
+    return [
+        ["groupPaddingRatio", Math.max(0, pad.value / 100)],
+        ["groupPaddingOf", typeof of === "string" ? of : "width"],
+    ];
+}
+
+/**
+ * A compound parent's minimum size on one axis and the share of its growth on the near side, as neutral values.
+ * @param min - the minimum as Cytoscape.js spells it
+ * @param near - the near side's bias (left, top)
+ * @param far - the far side's bias
+ * @param names - the neutral names of the minimum and of the near side's share
+ * @returns the properties and their values; none without a minimum
+ */
+function groupMinValues(
+    min: StyleValue | null | undefined,
+    near: StyleValue | null | undefined,
+    far: StyleValue | null | undefined,
+    names: readonly string[],
+): [string, StyleValue][] {
+    const m = measureOf(min);
+    if (m === null || m.percent || m.value <= 0) {
+        return [];
+    }
+    const share = biasShare(near, far, m.value);
+    return share === null
+        ? [[names[0], m.value]]
+        : [
+              [names[0], m.value],
+              [names[1], share],
+          ];
+}
+
 /** The label alignments read as Cytoscape.js's words. */
 const VALIGN_PART: CyjsPropertySpec = {
     property: "_valign",

package/src/styles/cyjs/defaults-table.ts

@@ -63,6 +63,7 @@ export const CYJS_DEFAULT_STYLESHEET: readonly {
         selector: ":parent",
         style: {
             shape: "rectangle",
+            padding: "10px",
             "background-color": "rgb(238,238,238)",
             "border-color": "rgb(204,204,204)",
             "border-width": "1px",

package/src/styles/cyjs/emit.ts

@@ -224,7 +224,41 @@ function toCyjs(target: StyleTarget, property: string, value: StyleValue): Writt
         case "labelBorderWidth":
             return ifNumber(value, (v) => exact({ "text-border-width": v, "text-border-opacity": 1 }));
         default:
-            return propertyToCyjs(property, value, specs);
+            return groupToCyjs(property, value) ?? propertyToCyjs(property, value, specs);
+    }
+}
+
+/**
+ * A compound parent's sizing as Cytoscape.js properties: a bias share as the two sides' percentages.
+ * @param property - the neutral property
+ * @param value - the value
+ * @returns the properties, or null when the property is no group sizing
+ */
+function groupToCyjs(property: string, value: StyleValue): Written | null {
+    const percent = (v: number): string => `${num6(v * 100)}%`;
+    switch (property) {
+        case "groupPadding":
+            return ifNumber(value, (v) => exact({ padding: `${num6(v)}px` }));
+        case "groupPaddingRatio":
+            return ifNumber(value, (v) => exact({ padding: percent(v) }));
+        case "groupPaddingOf":
+            return exact({ "padding-relative-to": String(value) });
+        case "groupMinWidth":
+            return ifNumber(value, (v) => exact({ "min-width": `${num6(v)}px` }));
+        case "groupMinHeight":
+            return ifNumber(value, (v) => exact({ "min-height": `${num6(v)}px` }));
+        case "groupMinWidthBiasLeft":
+            return ifNumber(value, (v) =>
+                exact({ "min-width-bias-left": percent(v), "min-width-bias-right": percent(1 - v) }),
+            );
+        case "groupMinHeightBiasTop":
+            return ifNumber(value, (v) =>
+                exact({ "min-height-bias-top": percent(v), "min-height-bias-bottom": percent(1 - v) }),
+            );
+        case "groupIncludeLabels":
+            return exact({ "compound-sizing-wrt-labels": value === false ? "exclude" : "include" });
+        default:
+            return null;
     }
 }
 

package/src/styles/cyjs/mappers.ts

@@ -465,6 +465,18 @@ export const CYJS_NODE_PROPERTIES: ReadonlyMap<string, CyjsPropertySpec> = new M
     ["height", { property: "height", type: "nodeSize" }],
     // a node is drawn this much larger on every side (`nodeSizes`)
     ["padding", { property: "_padding", type: "text" }],
+    // how a compound parent is sized round its children (`groupBoxes`)
+    [
+        "padding-relative-to",
+        { property: "_paddingOf", type: "enum", enums: ["width", "height", "average", "min", "max"] },
+    ],
+    ["min-width", { property: "_minWidth", type: "text" }],
+    ["min-height", { property: "_minHeight", type: "text" }],
+    ["min-width-bias-left", { property: "_biasLeft", type: "text" }],
+    ["min-width-bias-right", { property: "_biasRight", type: "text" }],
+    ["min-height-bias-top", { property: "_biasTop", type: "text" }],
+    ["min-height-bias-bottom", { property: "_biasBottom", type: "text" }],
+    ["compound-sizing-wrt-labels", { property: "_compoundLabels", type: "enum", enums: ["include", "exclude"] }],
     [
         "text-valign",
         { property: "_valign", type: "enum", enums: ["top", "top-inside", "center", "bottom", "bottom-inside"] },
@@ -538,6 +550,8 @@ export const CYJS_EDGE_PROPERTIES: ReadonlyMap<string, CyjsPropertySpec> = new M
     // where the ends meet the nodes, read with the routes (`edgePorts`)
     ["source-endpoint", { property: "_sourceEndpoint", type: "text" }],
     ["target-endpoint", { property: "_targetEndpoint", type: "text" }],
+    ["source-distance-from-node", { property: "sourceNodeGap", type: "size" }],
+    ["target-distance-from-node", { property: "targetNodeGap", type: "size" }],
     // a bundle's control points are this far apart, so the curves' middles half of it (see cyjsNeutral)
     ["control-point-step-size", { property: "fanSpacing", type: "size" }],
     ["arrow-scale", { property: "arrowSize", type: "positive" }],

package/src/styles/types.ts

@@ -518,6 +518,37 @@ export interface NodeStyleValues {
     readonly chartBorderColor: StyleColor;
     /** How wide a bar's and a box's outline is (a length); unset, none. */
     readonly chartBorderWidth: number;
+    /**
+     * How far a group drawn round its members (a node other nodes name as their parent, with no box of its own) reaches
+     * past their box on every side (a length; Cytoscape.js `padding` on a compound parent). Unset, the reader's own.
+     */
+    readonly groupPadding: number;
+    /**
+     * That padding as a fraction of the members' box instead, measured as `groupPaddingOf` says (Cytoscape.js
+     * `padding: 20%`); it wins over `groupPadding`.
+     */
+    readonly groupPaddingRatio: number;
+    /**
+     * What `groupPaddingRatio` is a fraction of: the members' box's `width`, `height`, `average` of the two, `min` or
+     * `max` (Cytoscape.js `padding-relative-to`); unset, `width`.
+     */
+    readonly groupPaddingOf: string;
+    /** The narrowest the members' box is drawn, before the padding (a length; Cytoscape.js `min-width`). */
+    readonly groupMinWidth: number;
+    /** The shortest the members' box is drawn, before the padding (a length; Cytoscape.js `min-height`). */
+    readonly groupMinHeight: number;
+    /**
+     * The share, 0..1, of the width `groupMinWidth` adds that goes on the left (Cytoscape.js `min-width-bias-left`
+     * against `min-width-bias-right`); unset, half.
+     */
+    readonly groupMinWidthBiasLeft: number;
+    /**
+     * The share, 0..1, of the height `groupMinHeight` adds that goes on top, as the reader sees it (Cytoscape.js
+     * `min-height-bias-top` against `min-height-bias-bottom`); unset, half.
+     */
+    readonly groupMinHeightBiasTop: number;
+    /** Whether the members' labels count in the members' box (Cytoscape.js `compound-sizing-wrt-labels`). */
+    readonly groupIncludeLabels: boolean;
     /** Whether the node is drawn at all. */
     readonly visible: boolean;
 }
@@ -701,11 +732,33 @@ export interface EdgeStyleValues {
      * distance between them (Gephi: the distance over its arc curveness 1.2).
      */
     readonly arcRadius: number;
+    /**
+     * A curved edge drawn as one quadratic curve through a support point a force simulation places among the nodes,
+     * wherever they are: `"barnesHut"` or `"forceAtlas2"`, the force law it settles under (vis-network's dynamic smooth
+     * edges, under its solvers of those names). Tied to the edge's two nodes by two springs, pushed away by every node
+     * and every other support point, pulled toward the middle of the nodes; the numbers below are in the file's units.
+     */
+    readonly supportModel: string;
+    /** The rest length of a support point's two springs together (a length). */
+    readonly supportSpringLength: number;
+    /** How hard a support point's springs pull per unit they are stretched. */
+    readonly supportSpringConstant: number;
+    /**
+     * How hard every node and every other support point push a support point away: over the distance squared under
+     * barnesHut, over the distance under forceAtlas2.
+     */
+    readonly supportRepulsion: number;
+    /** How hard a support point is pulled toward the middle of the nodes: a constant pull under barnesHut, in proportion to the distance under forceAtlas2. */
+    readonly supportCentralGravity: number;
     /**
      * How far from each of its nodes' outlines the edge's line (and its arrowhead) stops, leaving that much empty
      * (a length; Gephi's `edge.radius`).
      */
     readonly nodeGap: number;
+    /** How far from its source node's outline the edge's line stops, over `nodeGap` at that end (a length). */
+    readonly sourceNodeGap: number;
+    /** How far from its target node's outline the line (and its arrowhead) stops; see `sourceNodeGap`. */
+    readonly targetNodeGap: number;
     /**
      * Where the edge leaves its source node, when not at its center: `x,y` relative to the node's center as fractions
      * of its half width and half height, y up (`"1,0"` is the middle of its right side, `"0,1"` of its top), so the
@@ -813,6 +866,18 @@ export interface EdgeStyleValues {
     readonly sourceLabelRotation: number;
     /** How far the target end's label is turned, in degrees clockwise about its middle; unset, level. */
     readonly targetLabelRotation: number;
+    /** The source end's label's font size, in the units of `labelSize`; unset, the label's (`labelSize`). */
+    readonly sourceLabelSize: number;
+    /** The target end's label's font size; see `sourceLabelSize`. */
+    readonly targetLabelSize: number;
+    /** The color of the source end's label's words; unset, the label's (`labelColor`). */
+    readonly sourceLabelColor: StyleColor;
+    /** The color of the target end's label's words; see `sourceLabelColor`. */
+    readonly targetLabelColor: StyleColor;
+    /** The source end's label's font family, as the file names it; unset, the label's (`labelFont`). */
+    readonly sourceLabelFont: string;
+    /** The target end's label's font family; see `sourceLabelFont`. */
+    readonly targetLabelFont: string;
     /** The label is not drawn while its letters are drawn smaller than this many screen pixels; see the node's. */
     readonly labelMinScreenSize: number;
     /** Whether the label is drawn over every node and edge; see the node's. */

package/src/styles/vocabulary.ts

@@ -170,6 +170,14 @@ export const STYLE_PROPERTIES: {
         ["chartLineWidth", "number"],
         ["chartBorderColor", "color"],
         ["chartBorderWidth", "number"],
+        ["groupPadding", "number"],
+        ["groupPaddingRatio", "number"],
+        ["groupPaddingOf", "text"],
+        ["groupMinWidth", "number"],
+        ["groupMinHeight", "number"],
+        ["groupMinWidthBiasLeft", "number"],
+        ["groupMinHeightBiasTop", "number"],
+        ["groupIncludeLabels", "boolean"],
         ["visible", "boolean"],
     ]),
     edge: new Map<string, StyleValueKind>([
@@ -229,7 +237,14 @@ export const STYLE_PROPERTIES: {
         ["fanned", "boolean"],
         ["bendCurve", "text"],
         ["arcRadius", "number"],
+        ["supportModel", "text"],
+        ["supportSpringLength", "number"],
+        ["supportSpringConstant", "number"],
+        ["supportRepulsion", "number"],
+        ["supportCentralGravity", "number"],
         ["nodeGap", "number"],
+        ["sourceNodeGap", "number"],
+        ["targetNodeGap", "number"],
         ["sourcePort", "text"],
         ["targetPort", "text"],
         ["label", "text"],
@@ -272,6 +287,12 @@ export const STYLE_PROPERTIES: {
         ["targetLabelOffsetY", "signed"],
         ["sourceLabelRotation", "number"],
         ["targetLabelRotation", "number"],
+        ["sourceLabelSize", "number"],
+        ["targetLabelSize", "number"],
+        ["sourceLabelColor", "color"],
+        ["targetLabelColor", "color"],
+        ["sourceLabelFont", "text"],
+        ["targetLabelFont", "text"],
         ["labelMinScreenSize", "number"],
         ["labelOnTop", "boolean"],
         ["visible", "boolean"],