@graphty/graphty-element 2.2.0 → 2.2.1

package/dist/graphty.js

@@ -1,4 +1,4 @@
-import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-2VIpMJZP.js";
+import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-Cz47b_vU.js";
 import { a as p, S as G, b as f } from "./chunks/paletteRegistry-NrWOKT-A.js";
 import { D as y, E as D } from "./chunks/DataSource-DEg3igzS.js";
 import { k as P, l as U, g as c, h as m, A as u, C as x, i as B } from "./chunks/Algorithm-RQ629NLb.js";

package/dist/session.js

@@ -1,10 +1,10 @@
 import { R as A, e as R } from "./chunks/types-B7bX5c0K.js";
 import { A as _, a as C, G as g, i as m, b as L } from "./chunks/GraphtyError-BwcnblTH.js";
 import { g as U, h as I, i as N } from "./chunks/Algorithm-RQ629NLb.js";
-import { D as h } from "./chunks/GraphSession-CtqyVNsw.js";
-import { a as y, b as D, c as w, Q as b, R as v, d as G, e as x, S as z, T as F, f as M, i as j, g as H, h as Y, j as k } from "./chunks/GraphSession-CtqyVNsw.js";
+import { D as h } from "./chunks/GraphSession-D3AV8tpF.js";
+import { a as y, b as D, c as w, Q as b, R as v, d as G, e as x, S as z, T as F, f as M, i as j, g as H, h as Y, j as k } from "./chunks/GraphSession-D3AV8tpF.js";
 import { R as Q, w as X, x as B, y as J, z as K, A as V } from "./chunks/paletteRegistry-NrWOKT-A.js";
-import { a as n } from "./chunks/scales-BUS7NWy2.js";
+import { a as n } from "./chunks/scales-ulKMZPfG.js";
 const u = Object.freeze({
   /** Above this node count the element draws less visual detail. A shipped default, not measured. */
   largeGraphThreshold: 1e4,

package/dist/src/Graph.d.ts

@@ -178,7 +178,7 @@ export declare class Graph implements GraphContext {
      *
      * The settings take effect on the next layout the element runs. `preSteps` is read when a
      * layout starts, so setting it after a graph has already settled changes nothing that is
-     * already on screen.
+     * already on screen. `labels.declutter` is the exception: it takes effect on the next frame.
      * @param behavior - The fields to change. Anything omitted keeps its current value.
      */
     setLayoutBehavior(behavior: GraphBehaviorConfig): void;

package/dist/src/Node.d.ts

@@ -212,9 +212,8 @@ export declare class Node {
      * EFFECTS only on the branch that rebuilds the mesh, so an `instance` channel's edit reached
      * the screen only if some unrelated `mesh` channel happened to change in the same repaint.
      * That is why a glow was drawn when its colour was in the stack before the first frame and
-     * ignored when a layer added it afterwards, and why `node.glowStrength` had been declared a
-     * `mesh` channel: minting a source mesh per strength was the only way to force the rebuild
-     * that made the strength visible.
+     * ignored when a layer added it afterwards. (`node.glowStrength` is a `mesh` channel for a
+     * different reason: a glow's strength is set per SOURCE mesh, like its colour.)
      *
      * So this method is everything the `instance` role promises, and `paintFrom` calls it on BOTH
      * of its branches -- once when it has just rebuilt the mesh, because every one of these lives

package/dist/src/config/GraphBehavior.d.ts

@@ -27,6 +27,9 @@ export declare const GraphBehaviorOpts: z.ZodObject<{
     node: z.ZodPrefault<z.ZodObject<{
         pinOnDrag: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
+    labels: z.ZodPrefault<z.ZodObject<{
+        declutter: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
     fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
     fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
 }, z.core.$strict>;

package/dist/src/config/StyleTemplate.d.ts

@@ -928,6 +928,9 @@ declare const StyleTemplateV1: z.ZodObject<{
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
+        labels: z.ZodPrefault<z.ZodObject<{
+            declutter: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
         fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
         fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
     }, z.core.$strict>>;
@@ -1861,6 +1864,9 @@ export declare const StyleTemplate: z.ZodDiscriminatedUnion<[z.ZodObject<{
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
+        labels: z.ZodPrefault<z.ZodObject<{
+            declutter: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
         fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
         fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
     }, z.core.$strict>>;

package/dist/src/graphty-element.d.ts

@@ -425,13 +425,16 @@ export declare class Graphty extends LitElement {
      * unstepped force layout is a graph in mid-flight, and how far it has flown depends on when
      * the picture was taken. `layout.stepMultiplier`, `layout.minDelta` and
      * `layout.zoomStepInterval` pace the rest of it, and `node.pinOnDrag` decides whether a node
-     * a reader drags stays where they put it.
+     * a reader drags stays where they put it. `labels.declutter` (off by default) hides a node
+     * label whose words would be drawn over another label's, keeping a selected node's label
+     * first and then the label of the node with more edges; it takes effect on the next frame.
      *
      * Merged over what is already set, so naming one field leaves the others alone.
      * @since 2.0.0
      * @example
      * ```typescript
      * element.layoutBehavior = { layout: { preSteps: 1000 } };
+     * element.layoutBehavior = { labels: { declutter: true } };
      * ```
      * @returns The behaviour settings, or undefined when none have been set on this element
      */

package/dist/src/managers/DataManager.d.ts

@@ -67,6 +67,8 @@ export declare class DataManager implements Manager {
      * compiled, answered `undefined` for the edge whose id is `"0"`, and said nothing about it.
      */
     edges: Map<string, Edge>;
+    /** Goes up on every edge added or removed, so a cache over the edge set knows it is stale. */
+    edgeVersion: number;
     nodeCache: Map<NodeIdType, Node>;
     edgeCache: EdgeMap;
     /**

package/dist/src/managers/LabelDeclutter.d.ts

@@ -0,0 +1,97 @@
+import { type Camera, type Scene } from "@babylonjs/core";
+import type { Node } from "../Node";
+import type { GraphContext } from "./GraphContext";
+/**
+ * Hides node labels that would be drawn on top of each other, when the graph's behaviour
+ * configuration asks for it (`labels.declutter`, off by default).
+ *
+ * Every node label is its own billboarded plane, so two labelled nodes that land near each other
+ * on screen draw their words over one another. The pass projects each drawn label's WORDS -- not
+ * its padded plane -- to a screen rectangle, orders the labels by priority -- a selected node
+ * first, then the node with more edges, then the node id so the answer is stable -- and keeps a
+ * label only if its rectangle meets no label already kept. Kept rectangles are bucketed in a
+ * screen grid, so each label is tested against its neighbours rather than against every label.
+ *
+ * THE PASS RUNS ONLY WHEN SOMETHING THAT DECIDES PLACEMENT CHANGED: the camera's view or
+ * projection, the viewport size, a label added, rebuilt or removed, a node moved, shown, hidden
+ * or (de)selected, an edge added or removed, or the setting itself. A still scene costs one cheap
+ * walk over the labelled nodes per frame and no projection at all.
+ *
+ * A label that loses is hidden with `isVisible`, never with `setEnabled` and never through a
+ * style. `setEnabled` is the visibility mask's switch (`Node.applyRenderState`), and a style is
+ * the reader's answer to what a node looks like; this is a placement decision, so it has its own
+ * switch. Turning the setting off shows every label again.
+ *
+ * ONE PER SCENE, created by the first node that draws a label, and kept on `scene.metadata`
+ * the way `NodeEffects` keeps the glow layer.
+ */
+export declare class LabelDeclutter {
+    private readonly scene;
+    private readonly context;
+    /** How many full passes have run. Read by tests to prove a still scene is not re-measured. */
+    passes: number;
+    private readonly observer;
+    private readonly entries;
+    /** Reused every pass: the candidates in priority order. */
+    private readonly order;
+    /** Reused every pass: kept labels by grid cell. Emptied, not rebuilt. */
+    private readonly grid;
+    private columns;
+    private rows;
+    private dirty;
+    private wasOn;
+    private camera;
+    private readonly view;
+    private readonly projection;
+    private width;
+    private height;
+    private edgeVersion;
+    private degrees;
+    private readonly transform;
+    private readonly toPixels;
+    private readonly worldToPixels;
+    private readonly viewport;
+    private readonly right;
+    private readonly up;
+    private readonly centre;
+    private readonly corner;
+    private readonly centreOnScreen;
+    private readonly cornerOnScreen;
+    private constructor();
+    /**
+     * Make sure the scene has a declutter pass, and add a node that is drawing a label to it.
+     * @param scene - The scene the labels are drawn in.
+     * @param context - The graph: its configuration says whether to declutter, its edges give
+     *     the degree order.
+     * @param node - The node drawing a label.
+     */
+    static track(scene: Scene, context: GraphContext, node: Node): void;
+    /** Stop running before frames. */
+    dispose(): void;
+    /** Before every frame: decide whether placement could have changed, and if so, place. */
+    run(): void;
+    /**
+     * One full pass: decide which labels are drawn.
+     * @param camera - The camera the frame is drawn from.
+     */
+    place(camera: Camera): void;
+    /**
+     * Whether anything that decides placement differs from what the last pass saw.
+     * @param camera - The camera the frame is drawn from.
+     * @returns True when the labels have to be placed again.
+     */
+    private changed;
+    /**
+     * Record what this pass sees of one node, and drop it if its label is gone.
+     * @param entry - The node.
+     * @returns Its label plane, or null when it has none.
+     */
+    private observe;
+    private remember;
+    private isClear;
+    private keep;
+    /** The setting was turned off: every label is drawn again. */
+    private showAll;
+    /** How many edges each node has, counted again only when an edge is added or removed. */
+    private refreshDegrees;
+}

package/dist/src/meshes/NodeEffects.d.ts

@@ -114,14 +114,38 @@ export declare class NodeEffects {
      * material. Unfreezing to set `emissiveColor` would make every glowing style pay a material
      * re-bind per frame and would change the node's lit appearance as a side effect.
      *
-     * KNOWN LIMIT, stated rather than hidden: `intensity` is a property of the LAYER, not of a
-     * mesh, so with two glowing styles on screen the last one applied sets the strength for both.
-     * Colour is per style (see {@link NodeEffects.resolveRenderedMesh}). Per-style strength needs
-     * one layer per strength, which costs a full-screen pass each and was not worth it here.
+     * STRENGTH IS PER SOURCE MESH, like colour, through {@link NodeEffects.syncGlowStrengths}.
+     * It used to be written to `glowLayer.intensity`, which belongs to the one layer the scene
+     * shares, so the last glowing style applied set the strength of every glowing node.
      * @param mesh - The mesh to apply the effect to
      * @param effect - The effect configuration from the node style
      */
     static applyGlowEffect(mesh: AbstractMesh, effect: NodeStyleConfig["effect"] | undefined): void;
+    /**
+     * The glow strength each glowing source mesh asked for, kept on scene.metadata beside the
+     * glow colours.
+     * @param scene - The Babylon.js scene
+     * @returns The per-source-mesh strengths
+     */
+    private static glowStrengths;
+    /**
+     * Draw every glowing source mesh at its own strength, with one layer.
+     *
+     * Babylon multiplies a per-mesh `setEffectIntensity` into the glow colour as the glow map is
+     * drawn, and the layer's `intensity` scales the blurred result. The glow map is an 8-bit
+     * texture, so a per-mesh factor above 1 clamps and a strength of 3 would read the same as 1.
+     * So the layer carries the LARGEST strength on screen and each mesh carries its share of it,
+     * which is never above 1.
+     *
+     * Only source meshes that still draw a node count toward the largest strength. MeshCache
+     * never evicts a source mesh, so a strength that is no longer used (a slider dragged from 100
+     * back to 0.1) leaves a mesh with no instances behind; counted, it would hold the layer at 100
+     * and round the live glow away in the 8-bit map. It keeps its entry, because a node that goes
+     * back to that strength reuses the cached mesh. A disposed mesh is dropped.
+     * @param glowLayer - The scene's glow layer
+     * @param scene - The Babylon.js scene
+     */
+    private static syncGlowStrengths;
     /**
      * Remove a mesh from the highlight layer.
      *
@@ -149,7 +173,7 @@ export declare class NodeEffects {
      */
     static disposeHighlightLayer(scene: Scene): void;
     /**
-     * Dispose the glow layer for a scene, and forget the per-style colours with it.
+     * Dispose the glow layer for a scene, and forget the per-style colours and strengths with it.
      *
      * The colour map is keyed by mesh uniqueId, so it MUST die with the layer: leaving it behind
      * would let a later mesh that happens to reuse a uniqueId inherit a dead style's glow colour.

package/dist/src/meshes/RichTextLabel.d.ts

@@ -42,6 +42,8 @@ export declare class RichTextLabel {
     private parsedContent;
     private actualDimensions;
     private contentArea;
+    /** The size of the words alone, in the same units as `actualDimensions`. */
+    private textSize;
     private totalBorderWidth;
     private pointerInfo;
     private _progressValue;
@@ -112,6 +114,21 @@ export declare class RichTextLabel {
      * @returns The Babylon.js mesh or null if not created
      */
     get labelMesh(): Mesh | null;
+    /**
+     * Where the words sit on the label's plane, without its margins, padding, borders or pointer.
+     *
+     * Each edge is a fraction of the plane: `left`/`right` across it from its left edge, and
+     * `top`/`bottom` down it from its top edge, so a label whose words fill it reads
+     * `{ left: 0, right: 1, top: 0, bottom: 1 }`. Two labels whose planes overlap only in their
+     * padding do not draw over each other's words; this is what tells them apart.
+     * @returns The words' rectangle as fractions of the plane.
+     */
+    get textBounds(): {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
     /**
      * Gets the label's unique identifier
      * @returns The label ID

package/dist/src/session/styles/channels.d.ts

@@ -21,8 +21,6 @@
  *   compile error rather than a silent no-op.
  * - `edge.curvature` is a switch, not an amount. The edge renderer offsets its control points by
  *   a fixed fraction of the edge length, so "curve this edge" is the only thing it can be told.
- * - `node.glowStrength` is drawn, but Babylon keeps a glow's intensity on the LAYER rather than
- *   on a mesh, so two glowing styles on screen share whichever strength was applied last.
  * - `node.outline` is a colour and no width, for the same reason in the same shape: the stroke
  *   is drawn by a highlight LAYER whose blur size belongs to the layer, so every outline on
  *   screen is one width. This is the sentence the element's natural-language layer reads out

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graphty-element",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
   "type": "module",
   "customElements": "./dist/custom-elements.json",
@@ -185,8 +185,8 @@
     "toposort": "^2.0.2",
     "zod": "^3.25.28",
     "@graphty/algorithms": "^2.0.2",
-    "@graphty/graph-format": "^1.0.4",
-    "@graphty/layout": "^1.9.0"
+    "@graphty/layout": "^1.9.0",
+    "@graphty/graph-format": "^1.0.4"
   },
   "overrides": {
     "storybook": "$storybook"