@graphty/graphty-element 2.0.1 → 2.2.1

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

@@ -122,7 +122,7 @@ export declare class Graphty extends LitElement {
      * properties can be used in style selectors and accessed via `node.data`.
      * @since 1.0.0
      * @see {@link edgeData} for edge data
-     * @see {@link https://graphty.app/storybook/element/?path=/story/graphty--default | Basic Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/graphty--graphty | Basic Examples}
      * @example HTML attribute (JSON string)
      * ```html
      * <graphty-element
@@ -388,7 +388,7 @@ export declare class Graphty extends LitElement {
      * - `fixed`: Pre-defined positions from node data
      * @since 1.0.0
      * @see {@link layoutConfig} for layout-specific options
-     * @see {@link https://graphty.app/storybook/element/?path=/story/layout--default | Layout Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/layout-3d--circular | Layout Examples}
      * @example
      * ```typescript
      * // Set force-directed layout
@@ -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
      */
@@ -509,7 +512,7 @@ export declare class Graphty extends LitElement {
      *
      * VR and AR modes require WebXR support in the browser.
      * @since 1.0.0
-     * @see {@link https://graphty.app/storybook/element/?path=/story/viewmode--default | View Mode Examples}
+     * @see {@link https://graphty.app/storybook/graphty-element/?path=/story/viewmode--switch-view-modes | View Mode Examples}
      * @example
      * ```typescript
      * element.viewMode = "2d";  // Switch to 2D orthographic view
@@ -1526,6 +1529,27 @@ export declare class Graphty extends LitElement {
      * ```
      */
     isRunning(): boolean;
+    /**
+     * Play or pause the layout.
+     *
+     * `setRunning(true)` on a layout that has already settled restarts it, so "play" is
+     * something the reader can see; `setRunning(false)` stops the per-frame stepping and nothing
+     * else -- work already handed to an accelerator lands, the scene keeps rendering, and the
+     * camera, picking and styling stay live. There is no event for this: `isRunning()` reports
+     * the state and `graph-settled` reports the arrangement coming to rest.
+     *
+     * A pause is not a mode the element remembers: anything that (re)starts a layout -- loading
+     * more nodes, an accelerator attaching, setting another layout, dropping a dragged node --
+     * runs it again, so pause it after those, not before.
+     * @param running - True to run the layout, false to pause it.
+     * @since 2.0.0
+     * @example
+     * ```typescript
+     * element.setRunning(false); // pause
+     * element.setRunning(true); // play again, from where it stopped
+     * ```
+     */
+    setRunning(running: boolean): void;
     /**
      * Convert world coordinates to screen coordinates.
      * @param worldPos - Position in world space
@@ -1870,6 +1894,30 @@ export declare class Graphty extends LitElement {
      * healthy.
      */
     set acceleration(value: AccelerationPolicy);
+    /**
+     * The node count at or above which accelerated work uses the accelerator.
+     *
+     * Below it the element takes the CPU path even with an accelerator attached, and
+     * `capabilities.acceleration.state` reads `"idle"`. Default 0: use the accelerator whenever
+     * there is one. Raise it when the graphs you show are small enough that uploading costs more
+     * than computing; the number is machine-specific, which is why the element does not guess.
+     * @since 2.0.0
+     * @example
+     * ```html
+     * <graphty-element acceleration-min-nodes="5000"></graphty-element>
+     * ```
+     * @returns The threshold in force.
+     */
+    get accelerationMinNodes(): number;
+    /**
+     * Sets the threshold and applies it immediately.
+     *
+     * A value that is not a whole number of 0 or more is reported and then ignored, leaving the
+     * previous threshold in force, for the reason the `acceleration` setter states: Lit drives
+     * this from `attributeChangedCallback`, and a throw there would leave the element unrendered.
+     * @param value - The node count at or above which accelerated work uses the accelerator.
+     */
+    set accelerationMinNodes(value: number);
 }
 export type GraphtyElement = Graphty;
 declare global {

package/dist/src/layout/ForceAtlas2LayoutEngine.d.ts

@@ -1,56 +1,39 @@
-import { z } from "zod/v4";
+/**
+ * @file The ForceAtlas2 layout: the Gephi arrangement, computed on the CPU or on an accelerator.
+ *
+ * It used to be a one-shot pass -- run `forceatlas2Layout` over a node and edge list, publish the
+ * answer, stop -- which is why the catalogue called it a batch layout. It is now a steppable
+ * simulation from `@graphty/layout`, so it keeps running until the arrangement settles and reheats
+ * on a drag or a pin, and the element decides at every load whether the simulation is the CPU's or
+ * the accelerator's.
+ */
+import type { SimulationType } from "@graphty/layout";
 import { type OptionsSchema } from "../config";
-import { SimpleLayoutEngine } from "./LayoutEngine";
-declare const ForceAtlas2LayoutConfig: z.ZodObject<{
-    pos: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodArray<z.ZodNumber>>, z.ZodNull]>>;
-    maxIter: z.ZodDefault<z.ZodNumber>;
-    jitterTolerance: z.ZodDefault<z.ZodNumber>;
-    scalingRatio: z.ZodDefault<z.ZodNumber>;
-    gravity: z.ZodDefault<z.ZodNumber>;
-    distributedAction: z.ZodDefault<z.ZodBoolean>;
-    strongGravity: z.ZodDefault<z.ZodBoolean>;
-    nodeMass: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodNumber>, z.ZodNull]>>;
-    nodeSize: z.ZodDefault<z.ZodUnion<[z.ZodRecord<z.ZodNumber, z.ZodNumber>, z.ZodNull]>>;
-    weighted: z.ZodDefault<z.ZodBoolean>;
-    dissuadeHubs: z.ZodDefault<z.ZodBoolean>;
-    linlog: z.ZodDefault<z.ZodBoolean>;
-    seed: z.ZodDefault<z.ZodUnion<[z.ZodNumber, z.ZodNull]>>;
-    dim: z.ZodDefault<z.ZodNumber>;
-    scalingFactor: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strict>;
-type ForceAtlas2LayoutConfigType = z.infer<typeof ForceAtlas2LayoutConfig>;
-type ForceAtlas2LayoutOpts = Partial<ForceAtlas2LayoutConfigType>;
+import { SimulationLayoutEngine } from "./SimulationLayoutEngine";
 /**
- * ForceAtlas2 layout engine for graph visualization with scaling and gravity options
+ * The ForceAtlas2 engine, as the element declares it.
+ *
+ * Every member is a static the element reads: `LayoutManager` builds the bridge itself, with the
+ * graph's acceleration controller, so this class never runs a layout of its own. It declares no
+ * `static descriptor` because its arrangement is authored in the layout catalogue, where it sits
+ * under `force`.
  */
-export declare class ForceAtlas2Layout extends SimpleLayoutEngine {
+export declare class ForceAtlas2Layout extends SimulationLayoutEngine {
     static type: string;
+    static simulationType: SimulationType;
     static maxDimensions: number;
-    static honoursWeights: boolean;
-    static zodOptionsSchema: OptionsSchema;
-    scalingFactor: number;
-    config: ForceAtlas2LayoutConfigType;
     /**
-     * Create a ForceAtlas2 layout engine
-     * @param opts - Configuration options for the ForceAtlas2 algorithm
+     * A WEIGHT IS AN ATTRACTION STRENGTH HERE, and is passed through as it is stored: a heavier
+     * edge pulls its two nodes closer, which is what a weight means everywhere else in the
+     * element. Kamada-Kawai reads the very same number as a distance and therefore inverts it; the
+     * two engines disagree about the arithmetic so that they agree about the meaning.
      */
-    constructor(opts: ForceAtlas2LayoutOpts);
+    static honoursWeights: boolean;
+    static zodOptionsSchema: OptionsSchema;
     /**
-     * Get dimension-specific options for ForceAtlas2 layout
-     * @param dimension - The desired dimension (2 or 3)
-     * @returns Options object with dim parameter
+     * Get dimension-specific options for ForceAtlas2 layout.
+     * @param dimension - The desired dimension (2 or 3).
+     * @returns Options object with dim parameter.
      */
     static getOptionsForDimension(dimension: 2 | 3): object;
-    /**
-     * Compute node positions using the ForceAtlas2 algorithm
-     *
-     * A WEIGHT IS PASSED THROUGH AS IT IS STORED. ForceAtlas2 reads a weight as an attraction
-     * STRENGTH -- it becomes the adjacency matrix entry the attraction force is scaled by -- which
-     * is already what a weight means everywhere else in the element, so a heavier edge pulls its
-     * two nodes closer and nothing has to be inverted. Kamada-Kawai reads the very same number as
-     * a distance and therefore does invert it; the two engines disagree about the arithmetic so
-     * that they agree about the meaning.
-     */
-    doLayout(): void;
 }
-export {};

package/dist/src/layout/LayoutEngine.d.ts

@@ -48,15 +48,15 @@ export interface LayoutEngineStatics {
     /**
      * Whether this engine arranges a graph differently when its edges carry weights.
      *
-     * Optional, and false for all but two of the element's own sixteen. It exists so that a
+     * Optional, and false for all but two of the element's own seventeen. It exists so that a
      * picker can tell a reader which arrangements the `weighted` option actually does something
-     * for, instead of offering it on fourteen layouts that ignore it.
+     * for, instead of offering it on fifteen layouts that ignore it.
      */
     honoursWeights?: boolean;
     /**
      * What the catalogue publishes about this layout, so a picker can offer it.
      *
-     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own sixteen, whose
+     * REQUIRED OF A THIRD PARTY'S ENGINE and absent from the element's own seventeen, whose
      * arrangements are authored in `src/catalog/layouts.ts` instead. `descriptor.id` must equal
      * {@link LayoutEngineStatics.type}: one key, so nothing is named twice and `layoutIdForEngine`
      * can answer a plugin's own id.
@@ -94,7 +94,7 @@ export declare abstract class LayoutEngine {
      * Whether this engine reads edge weights. See {@link LayoutEngineStatics.honoursWeights}.
      *
      * False here because most layouts have no weight channel at all: of the element's own
-     * sixteen, only Kamada-Kawai and ForceAtlas2 can read one, and the other fourteen would be
+     * seventeen, only Kamada-Kawai and ForceAtlas2 can read one, and the other fifteen would be
      * advertising a control that changes nothing.
      */
     static honoursWeights: boolean;
@@ -162,7 +162,7 @@ export declare abstract class LayoutEngine {
      * Take a node out of the layout, before the element disposes the mesh that drew it.
      *
      * Declared here, with a default that does nothing, because it used to be duck-typed by the
-     * element's data manager and implemented by none of the sixteen engines that ship here: an
+     * element's data manager and implemented by none of the seventeen engines that ship here: an
      * author learned it existed by reading the element's source, and got no worked example. An
      * engine that keeps its own node list must override this, or it holds every removed node --
      * and everything that node references -- for as long as the engine lives.
@@ -260,7 +260,7 @@ export declare abstract class LayoutEngine {
      * freeze counts as placed, which is what makes a file's own coordinates yield to it.
      *
      * A PINNED ROW REFUSES A LAYOUT STEP. This is the whole of "a pin is meaningful under every
-     * arrangement": fourteen of the element's sixteen engines implement `pin()` as a no-op and
+     * arrangement": twelve of the element's seventeen engines implement `pin()` as a no-op and
      * `setNodePosition` as a no-op too, so before this guard a reader who dragged a node under a
      * static layout watched it snap back the next time the layout recomputed. One refusal here
      * covers every engine, including one written by a third party that has never heard of pinning,
@@ -351,7 +351,7 @@ export declare abstract class LayoutEngine {
      * offered by a picker, described in a reader's language, or found by `layoutIdForEngine`.
      *
      * A third party's class must declare a `static descriptor` whose `id` equals its
-     * `static type`. The element's own sixteen are the one exemption, because their arrangements
+     * `static type`. The element's own seventeen are the one exemption, because their arrangements
      * are authored centrally in the layout catalogue where several engines may sit behind one
      * public name.
      * @param cls - The layout engine class.