@graphty/cytoscape-extensions 0.0.28 → 0.0.29

package/dist/layouts.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Every @graphty/layout layout as a Cytoscape.js 3.x layout extension, named "graphty-<name>".
+ *
+ * Two kinds:
+ * - static layouts compute once and hand their positions to Cytoscape's `layoutPositions`, which supplies the
+ *   events, `fit`, `spacingFactor`, `transform` and the tween for any truthy `animate`;
+ * - the force simulations (ForceAtlas2, Fruchterman-Reingold, spring-electrical) step a `LayoutSimulation`. With
+ *   `animate: true` they draw every frame and own their events; otherwise they run to the end and finish through
+ *   `layoutPositions` like a static layout.
+ *
+ * Positions are 2D. A 3D run (`dim: 3`) is projected onto the x-y plane.
+ */
+import { type ArfOptions, type BipartiteLayoutOptions, type ForceAtlas2Options, type FruchtermanReingoldOptions, type GridLayoutOptions, type KamadaKawaiOptions, type LayoutAccelerator, type SimulationType, type SpiralLayoutOptions, type SpringElectricalOptions } from "@graphty/layout";
+import type { BoundingBox12, BoundingBoxWH, Collection, LayoutHandler, Layouts as CytoscapeLayouts, NodeSingular, Position } from "cytoscape";
+import { type Backend, type GpuMode } from "./gpu.js";
+import { type NodeSelection } from "./snapshot.js";
+/**
+ * Every option this package defines for the "graphty-*" layouts, shared and per layout. A layout takes the shared ones
+ * and its own (see GraphtyLayoutOptionsByName); its other options go to the @graphty/layout function unchanged.
+ * Exported for scripts/reference.ts, which documents every layout option from it.
+ * @internal
+ */
+export interface LayoutOptionFields {
+    readonly name: GraphtyLayoutName;
+    /** Set by `cy.layout()` / `eles.layout()`. */
+    readonly eles?: Collection;
+    /** false: jump; "end" or any truthy value on a static layout: tween to the result; true on a simulation: draw every frame. */
+    readonly animate?: boolean | "end";
+    /** Length of the tween, in milliseconds. */
+    readonly animationDuration?: number;
+    /** Easing of the tween, as Cytoscape's built-in layouts take it (for example "ease-out"). */
+    readonly animationEasing?: string;
+    /** Tween only the nodes for which this returns true; the others jump to their positions. */
+    readonly animateFilter?: (node: NodeSingular, i: number) => boolean;
+    /** Fit the viewport to the result. Default true. */
+    readonly fit?: boolean;
+    /** Space around the result when `fit` is true, in pixels. */
+    readonly padding?: number;
+    /**
+     * Where to place the result. Default: the viewport, which is 1 x 1 pixel on a headless core. The result keeps its
+     * shape: its centroid goes to the center of the box, and it is scaled so the node farthest from the centroid is
+     * half the box's shorter side away. A box wider than it is tall is therefore not filled from side to side. A
+     * simulation with locked nodes keeps them in place and scales the free nodes around them instead.
+     */
+    readonly boundingBox?: BoundingBox12 | BoundingBoxWH;
+    /**
+     * Expands (above 1) or compresses (below 1) the area the result takes up, after it is fitted to `boundingBox`, so
+     * a value above 1 can put nodes outside the box.
+     */
+    readonly spacingFactor?: number;
+    /** Changes each final position: called with the node and its computed position, returns the position to use. */
+    readonly transform?: (node: NodeSingular, position: Position) => Position;
+    /** Called on layoutready. */
+    readonly ready?: LayoutHandler;
+    /** Called on layoutstop. */
+    readonly stop?: LayoutHandler;
+    /**
+     * 2 (default) or 3. With 3, graphty-circular puts the nodes on a sphere, and graphty-random, graphty-kamada-kawai,
+     * graphty-arf and the simulations place them in 3D; z is then dropped, so the drawing is that 3D result seen from
+     * above and no longer looks like the 2D layout (circular is no longer a circle). The other layouts ignore it.
+     * Cytoscape draws in 2D, so 3 only gives a different flattened drawing; it is there because the underlying layout
+     * functions take it.
+     */
+    readonly dim?: 2 | 3;
+    /**
+     * Seed of the layouts that draw random numbers: graphty-random, graphty-spectral (above 500 nodes), graphty-arf
+     * and the three simulations. The same seed gives the same positions; without one, positions that depend on random
+     * numbers differ from run to run. The other layouts ignore it.
+     */
+    readonly seed?: number;
+    /**
+     * Edge data field holding the weight; a function of the edge also works at runtime. An edge without a number
+     * counts as 1. Only graphty-forceatlas2 and graphty-kamada-kawai read it, in opposite directions: forceatlas2
+     * treats it as attraction (higher pulls the ends closer), kamada-kawai as edge length (higher pushes them
+     * apart). Default: unweighted.
+     */
+    readonly weight?: string;
+    /** Simulations: start from random positions (true, default) or from the current ones. Locked nodes never move. */
+    readonly randomize?: boolean;
+    /** Simulations with `animate: true`: iterations per frame. Default 1. */
+    readonly refresh?: number;
+    /**
+     * Simulations: "auto" (default) runs on the core's GPU when the runtime has a usable WebGPU device, else on the
+     * CPU. In Node or a browser with `navigator.gpu`, a run that has to look for a device finishes after `run()`
+     * returns, whichever it picks, so listen for layoutstop. "off" runs on the CPU, synchronously when `animate` is false; "require" emits layouterror instead of running on the CPU. `layout.backend` says which ran. Any other value makes `run()` throw a TypeError.
+     */
+    readonly gpu?: GpuMode;
+    /**
+     * Simulations: an accelerator the caller built and owns (for example the `createAccelerator` of
+     * `@graphty/webgpu-graph-algorithms`); overrides `gpu`. null forces the CPU.
+     */
+    readonly accelerator?: LayoutAccelerator | null;
+    /** shell: the shells, innermost first. */
+    readonly nlist?: readonly NodeSelection[];
+    /**
+     * multipartite: a node data field whose value names the layer (default "subset"), or the layers in order. Layers
+     * named by a field are ordered by value, numbers ascending and other values alphabetically. A node with no value in
+     * the field is not placed and keeps its position, so on a graph where no node has the field nothing moves.
+     */
+    readonly subsets?: string | readonly NodeSelection[];
+    /**
+     * bipartite: the nodes of the first line, the left column when `align` is "vertical" and the top row when it is
+     * "horizontal". Absent: the first, third, fifth and so on of the laid-out nodes.
+     */
+    readonly top?: NodeSelection;
+    /**
+     * multipartite, bipartite and bfs: "vertical" (default) puts each layer in a column, its nodes sharing one x;
+     * "horizontal" puts each layer in a row, its nodes sharing one y.
+     */
+    readonly align?: "vertical" | "horizontal";
+    /**
+     * bfs: the start node, default the first node; radial: the center node, default the node with the most neighbors.
+     */
+    readonly root?: NodeSelection;
+    /**
+     * forceatlas2: each node's mass. The name of a node data field (a node without a number there gets the default),
+     * an object keyed by node id, or one number per node in node order (an array or a typed array; see Per-node
+     * arrays). Default: the node's degree + 1.
+     */
+    readonly nodeMass?: string | ArrayLike<number> | Readonly<Record<string, number>>;
+    /** forceatlas2: accepted in the same forms as `nodeMass` and not used yet: nodes are treated as points. */
+    readonly nodeSize?: string | ArrayLike<number> | Readonly<Record<string, number>>;
+}
+/** The options of LayoutOptionFields that only some layouts take. */
+type PerLayoutField = "nlist" | "subsets" | "top" | "align" | "root" | "nodeMass" | "nodeSize";
+/** The options every layout takes. */
+type Shared = Omit<LayoutOptionFields, "name" | PerLayoutField>;
+/** Some of the per-layout options. */
+type Own<K extends PerLayoutField> = Pick<LayoutOptionFields, K>;
+/**
+ * A @graphty/layout options type without what this package sets itself (the frame and the stepping, `fixed` from
+ * locked nodes) or spells its own way (bfs `start` is `root` here).
+ */
+type Library<T, Drop extends string = never> = Omit<T, keyof LayoutOptionFields | "scale" | "center" | "iterationsPerStep" | "fixed" | "start" | "weights" | "weighted" | Drop>;
+/**
+ * The options of each "graphty-*" layout, by name. A simulation's `pos` is the nodes' current positions, so only the
+ * static layouts that take a start (arf, kamada-kawai) list it.
+ */
+export interface GraphtyLayoutOptionsByName {
+    "graphty-random": Shared;
+    "graphty-circular": Shared;
+    "graphty-spiral": Shared & Library<SpiralLayoutOptions>;
+    "graphty-grid": Shared & Library<GridLayoutOptions>;
+    "graphty-spectral": Shared;
+    "graphty-planar": Shared;
+    "graphty-arf": Shared & Library<ArfOptions>;
+    "graphty-kamada-kawai": Shared & Library<KamadaKawaiOptions>;
+    "graphty-shell": Shared & Own<"nlist">;
+    "graphty-multipartite": Shared & Own<"subsets" | "align">;
+    "graphty-bipartite": Shared & Own<"top" | "align"> & Library<BipartiteLayoutOptions>;
+    "graphty-bfs": Shared & Own<"root" | "align">;
+    "graphty-radial": Shared & Own<"root">;
+    "graphty-forceatlas2": Shared & Own<"nodeMass" | "nodeSize"> & Library<ForceAtlas2Options>;
+    "graphty-fruchterman-reingold": Shared & Library<FruchtermanReingoldOptions, "pos">;
+    "graphty-spring-electrical": Shared & Library<SpringElectricalOptions, "pos">;
+}
+/** Every layout this package registers, by its registered name. */
+export type GraphtyLayoutName = keyof GraphtyLayoutOptionsByName;
+/**
+ * The options of a "graphty-*" layout: a union over the layout names, so a variable annotated with it keeps its
+ * layout's options type, and a misspelled name or option does not compile. `GraphtyLayoutOptions<"graphty-bfs">` is
+ * one layout's.
+ */
+export type GraphtyLayoutOptions<N extends GraphtyLayoutName = GraphtyLayoutName> = N extends GraphtyLayoutName ? GraphtyLayoutOptionsByName[N] & {
+    readonly name: N;
+} : never;
+/**
+ * The layout a "graphty-*" layout name gives. `backend` is set on a simulation (forceatlas2, fruchterman-reingold,
+ * spring-electrical) once it has decided between GPU and CPU, before layoutready; static layouts leave it unset.
+ */
+export type GraphtyLayouts = CytoscapeLayouts & {
+    readonly backend?: Backend;
+};
+declare module "cytoscape" {
+    interface CoreLayout {
+        layout(options: GraphtyLayoutOptions): GraphtyLayouts;
+        makeLayout(options: GraphtyLayoutOptions): GraphtyLayouts;
+        createLayout(options: GraphtyLayoutOptions): GraphtyLayouts;
+    }
+    interface CollectionLayout {
+        layout(options: GraphtyLayoutOptions): GraphtyLayouts;
+        makeLayout(options: GraphtyLayoutOptions): GraphtyLayouts;
+        createLayout(options: GraphtyLayoutOptions): GraphtyLayouts;
+    }
+}
+export declare const DEFAULTS: {
+    readonly animate: false;
+    readonly animationDuration: 500;
+    readonly fit: true;
+    readonly padding: 30;
+    readonly randomize: true;
+    readonly refresh: 1;
+};
+export declare const SIMULATION_DEFAULTS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/** Registered name suffix -> @graphty/layout simulation type. */
+export declare const SIMULATIONS: Readonly<Record<string, SimulationType>>;
+/** Every layout name this package registers, without the "graphty-" prefix. */
+export declare const LAYOUT_NAMES: readonly string[];
+/** The registration function Cytoscape's `use()` calls. */
+type Register = (type: string, name: string, registrant: unknown) => void;
+/**
+ * Registers every graphty layout as "graphty-<name>": `cytoscape.use(graphtyCytoscape)`.
+ * @param cytoscape - the cytoscape function
+ */
+export declare function registerLayouts(cytoscape: Register): void;
+export {};
+//# sourceMappingURL=layouts.d.ts.map

package/dist/layouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layouts.d.ts","sourceRoot":"","sources":["../src/layouts.ts"],"names":[],"mappings":"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"}