@joint/core 4.2.0-alpha.1 → 4.2.0-beta.1

package/dist/joint.d.ts

@@ -1,4 +1,4 @@
-/*! JointJS v4.2.0-alpha.1 (2025-09-25) - JavaScript diagramming library
+/*! JointJS v4.2.0-beta.1 (2025-11-03) - JavaScript diagramming library
 
 This Source Code Form is subject to the terms of the Mozilla Public
 License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -431,6 +431,7 @@ export declare namespace config {
     var doubleTapInterval: number;
     var cellMergeStrategy: util.MergeCustomizer | null;
     var cellDefaultsMergeStrategy: util.MergeCustomizer | null;
+    var layerAttribute: string;
 }
 
 export declare namespace connectionPoints {
@@ -761,6 +762,89 @@ export declare namespace dia {
     util.filter.FilterJSON<'brightness'> |
     util.filter.FilterJSON<'contrast'>;
 
+    export class CellCollection<C extends Cell = Cell> extends mvc.Collection<C> {
+
+        cellNamespace: any;
+        layer: GraphLayer;
+
+        minZIndex(): number;
+
+        maxZIndex(): number;
+    }
+
+    export class GraphLayerCollection<L extends GraphLayer = GraphLayer> extends mvc.Collection<L> {
+
+        cellNamespace: any;
+        layerNamespace: any;
+        graph: Graph;
+
+        insert(layer: Graph.LayerInit, beforeId: GraphLayer.ID | null, opt?: ObjectHash): void;
+
+        getCell(cellRef: Graph.CellRef): Cell | undefined;
+
+        getCells(): Cell[];
+
+        removeCell(cell: Cell, opt?: ObjectHash): void;
+
+        moveCellBetweenLayers(cell: Cell, targetLayerId: GraphLayer.ID, opt?: ObjectHash): void;
+
+        addCellToLayer(cell: Cell, layerId: GraphLayer.ID, opt?: ObjectHash): void;
+    }
+
+    export class GraphLayersController extends mvc.Listener<[]> {
+
+        graph: Graph;
+
+        layerCollection: GraphLayerCollection;
+
+        startListening(): void;
+
+        protected onCellChange(cell: Cell, opt: ObjectHash): void;
+
+        protected onCellRemove(cell: Cell, opt: ObjectHash): void;
+
+        protected onLayerCollectionEvent(eventName: string, ...args: any[]): void;
+
+        protected forwardLayerEvent(...args: any[]): void;
+
+        protected forwardCellEvent(...args: any[]): void;
+
+        protected forwardCellCollectionEvent(...args: any[]): void;
+
+        protected forwardLayerCollectionEvent(...args: any[]): void;
+    }
+
+    export class GraphTopologyIndex extends mvc.Listener<[]> {
+
+        layerCollection: GraphLayerCollection;
+
+        startListening(): void;
+
+        getOutboundEdges(id: Cell.ID): { [edgeId: string]: true };
+
+        getInboundEdges(id: Cell.ID): { [edgeId: string]: true };
+
+        getSinkNodes(): string[];
+
+        getSourceNodes(): string[];
+
+        isSinkNode(id: Cell.ID): boolean;
+
+        isSourceNode(id: Cell.ID): boolean;
+
+        protected initializeIndex(): void;
+
+        protected _restructureOnReset(): void;
+
+        protected _restructureOnAdd(cell: Cell): void;
+
+        protected _restructureOnRemove(cell: Cell): void;
+
+        protected _restructureOnChangeSource(cell: Cell): void;
+
+        protected _restructureOnChangeTarget(cell: Cell): void;
+    }
+
     export namespace Graph {
 
         export interface Options {
@@ -784,35 +868,100 @@ export declare namespace dia {
             strict?: boolean;
         }
 
+        export interface SyncCellOptions extends Options {
+            remove?: boolean;
+        }
+
+        export interface RemoveCellOptions extends Options {
+            disconnectLinks?: boolean;
+            replace?: boolean;
+            clear?: boolean;
+        }
+
         export type SearchByKey = 'bbox' | PositionName;
 
         export interface FindUnderElementOptions extends FindInAreaOptions, FindAtPointOptions {
             searchBy?: SearchByKey;
         }
 
-        export class Cells extends mvc.Collection<Cell> {
-            graph: Graph;
-            cellNamespace: any;
-        }
+        export type Cells = CellCollection;
+
+        export type CellInit = Cell | Cell.JSON;
+
+        export type CellRef = Cell | Cell.ID;
+
+        export type LayerInit = GraphLayer | GraphLayer.Attributes;
+
+        export type LayerRef = GraphLayer | GraphLayer.ID;
 
         export interface Attributes {
-            cells?: Cells;
+            /** @deprecated use cellsCollection property **/
+            cells?: CellCollection;
             [key: string]: any;
         }
+
+        export interface JSON {
+            cells: Array<Cell.JSON>;
+            layers?: Array<GraphLayer.Attributes>;
+            defaultLayer?: string;
+            [key: string]: any;
+        }
+
+        export interface InsertLayerOptions extends Options {
+            before?: GraphLayer.ID | null;
+            index?: number;
+        }
     }
 
     export class Graph<A extends ObjectHash = Graph.Attributes, S = dia.ModelSetOptions> extends mvc.Model<A, S> {
 
-        constructor(attributes?: Graph.Attributes, opt?: { cellNamespace?: any, cellModel?: typeof Cell });
+        layerCollection: GraphLayerCollection;
+
+        defaultLayerId: GraphLayer.ID;
+
+        layersController: GraphLayersController;
+
+        topologyIndex: GraphTopologyIndex;
+
+        constructor(attributes?: Graph.Attributes, opt?: {
+            cellNamespace?: any,
+            layerNamespace?: any,
+            /** @deprecated use cellNamespace instead */
+            cellModel?: typeof Cell
+        });
+
+        addCell(cell: Graph.CellInit, opt?: CollectionAddOptions): this;
+        addCell(cell: Array<Graph.CellInit>, opt?: CollectionAddOptions): this;
+
+        addCells(cells: Array<Graph.CellInit>, opt?: CollectionAddOptions): this;
+
+        removeCell(cell: Graph.CellRef, opt?: Graph.RemoveCellOptions): void;
+
+        removeCells(cells: Array<Graph.CellRef>, opt?: Graph.RemoveCellOptions): this;
+
+        resetCells(cells: Array<Graph.CellInit>, opt?: Graph.Options): this;
+
+        syncCells(cells: Array<Graph.CellInit>, opt?: Graph.SyncCellOptions): void;
+
+        addLayer(layerInit: Graph.LayerInit, opt?: Graph.InsertLayerOptions): void;
+
+        moveLayer(layerRef: Graph.LayerRef, opt?: Graph.InsertLayerOptions): void;
+
+        removeLayer(layerRef: Graph.LayerRef, opt?: Graph.Options): void;
 
-        addCell(cell: Cell.JSON | Cell, opt?: CollectionAddOptions): this;
-        addCell(cell: Array<Cell | Cell.JSON>, opt?: CollectionAddOptions): this;
+        getDefaultLayer(): GraphLayer;
 
-        addCells(cells: Array<Cell | Cell.JSON>, opt?: CollectionAddOptions): this;
+        setDefaultLayer(id: string, opt?: Graph.Options): void;
 
-        resetCells(cells: Array<Cell | Cell.JSON>, opt?: Graph.Options): this;
+        getLayer(id: string): GraphLayer;
 
-        getCell(id: Cell.ID | Cell): Cell;
+        hasLayer(id: string): boolean;
+
+        getLayers(): GraphLayer[];
+
+        getCellLayerId(cell: Graph.CellRef): GraphLayer.ID;
+
+        getCell(id: Graph.CellRef): Cell;
 
         getElements(): Element[];
 
@@ -820,15 +969,15 @@ export declare namespace dia {
 
         getCells(): Cell[];
 
-        getFirstCell(): Cell | undefined;
+        getFirstCell(layerId?: string): Cell | undefined;
 
-        getLastCell(): Cell | undefined;
+        getLastCell(layerId?: string): Cell | undefined;
 
         getConnectedLinks(cell: Cell, opt?: Graph.ConnectionOptions): Link[];
 
         disconnectLinks(cell: Cell, opt?: S): void;
 
-        removeLinks(cell: Cell, opt?: Cell.DisconnectableOptions): void;
+        removeLinks(cell: Graph.CellRef, opt?: Graph.RemoveCellOptions): void;
 
         translate(tx: number, ty?: number, opt?: Element.TranslateOptions): this;
 
@@ -900,6 +1049,12 @@ export declare namespace dia {
 
         protected _filterCellsUnderElement(cells: Cell[], element: Element, opt: Graph.FindUnderElementOptions): Cell[];
 
+        protected _syncCell(cellInit: Graph.CellInit, opt?: Graph.Options): void;
+
+        protected _replaceCell(currentCell: Cell, newCellInit: Graph.CellInit,  opt?: Graph.Options): void;
+
+        protected _resetLayers(layers: Array<Graph.LayerInit>, defaultLayerId: GraphLayer.ID | null, opt?: Graph.Options): this;
+
         /** @deprecated use `findElementsAtPoint` instead */
         findModelsFromPoint(p: Point): Element[];
 
@@ -915,11 +1070,9 @@ export declare namespace dia {
 
         hasActiveBatch(name?: string | string[]): boolean;
 
-        maxZIndex(): number;
+        maxZIndex(layerId?: GraphLayer.ID): number;
 
-        minZIndex(): number;
-
-        removeCells(cells: Cell[], opt?: Cell.DisconnectableOptions): this;
+        minZIndex(layerId?: GraphLayer.ID): number;
 
         transferCellEmbeds(sourceCell: Cell, targetCell: Cell, opt?: S): void;
 
@@ -978,9 +1131,7 @@ export declare namespace dia {
             deep?: T;
         }
 
-        export interface DisconnectableOptions extends Options {
-            disconnectLinks?: boolean;
-        }
+        export type DisconnectableOptions = Graph.RemoveCellOptions;
 
         export interface GetEmbeddedCellsOptions extends EmbeddableOptions {
             breadthFirst?: boolean;
@@ -1060,9 +1211,9 @@ export declare namespace dia {
 
         protected generateId(): string | number;
 
-        protected stopPendingTransitions(path?: string, delim?: string): void;
+        protected stopPendingTransitions(path?: Path, delim?: string): void;
 
-        protected stopScheduledTransitions(path?: string, delim?: string): void;
+        protected stopScheduledTransitions(path?: Path, delim?: string): void;
 
         toJSON(opt?: dia.Cell.ExportOptions): Cell.JSON<any, A>;
 
@@ -1100,11 +1251,11 @@ export declare namespace dia {
 
         removeAttr(path: Path, opt?: Cell.Options): this;
 
-        transition(path: string, value?: any, opt?: Cell.TransitionOptions, delim?: string): number;
+        transition(path: Path, value?: any, opt?: Cell.TransitionOptions, delim?: string): number;
 
         getTransitions(): string[];
 
-        stopTransitions(path?: string, delim?: string): this;
+        stopTransitions(path?: Path, delim?: string): this;
 
         embed(cell: Cell | Cell[], opt?: Cell.EmbedOptions): this;
 
@@ -1128,6 +1279,9 @@ export declare namespace dia {
 
         z(): number;
 
+        layer(): string | null;
+        layer(id: string | null, opt?: Graph.Options): this;
+
         angle(): number;
 
         getBBox(): g.Rect;
@@ -1258,7 +1412,7 @@ export declare namespace dia {
         }
 
         export interface FitParentOptions extends FitToChildrenOptions {
-            terminator?: Cell | Cell.ID;
+            terminator?: Graph.CellRef;
         }
 
         export interface RotateOptions {
@@ -1985,14 +2139,17 @@ export declare namespace dia {
         }
 
         export enum Layers {
-            CELLS = 'cells',
             LABELS = 'labels',
             BACK = 'back',
             FRONT = 'front',
+            /** @deprecated */
+            CELLS = 'cells',
             TOOLS = 'tools',
             GRID = 'grid',
         }
 
+        export type LayerRef = Layers | string | dia.LayerView | dia.GraphLayer;
+
         export interface RenderStats {
             priority: number;
             updated: number;
@@ -2135,6 +2292,7 @@ export declare namespace dia {
             validateUnembedding?: (this: Paper, childView: ElementView) => boolean;
             // default views, models & attributes
             cellViewNamespace?: any;
+            layerViewNamespace?: any;
             routerNamespace?: any;
             connectorNamespace?: any;
             highlighterNamespace?: any;
@@ -2308,6 +2466,11 @@ export declare namespace dia {
             view: CellView;
             magnet: SVGElement;
         }
+
+        export interface InsertLayerViewOptions {
+            before?: LayerRef | null;
+            index?: number;
+        }
     }
 
     export class Paper extends mvc.View<Graph> {
@@ -2320,10 +2483,14 @@ export declare namespace dia {
 
         svg: SVGSVGElement;
         defs: SVGDefsElement;
+
+        /** @deprecated use getLayerViewNode()*/
         cells: SVGGElement;
+        /** @deprecated use layers property*/
+        viewport: SVGGElement;
+
         tools: SVGGElement;
         layers: SVGGElement;
-        viewport: SVGGElement;
 
         GUARDED_TAG_NAMES: string[];
         FORM_CONTROLS_TAG_NAMES: string[];
@@ -2399,7 +2566,7 @@ export declare namespace dia {
 
         findView<T extends ElementView | LinkView>(element: mvc.$SVGElement): T;
 
-        findViewByModel<T extends ElementView | LinkView>(model: Cell | Cell.ID): T;
+        findViewByModel<T extends ElementView | LinkView>(model: Graph.CellRef): T;
 
         /**
          * Finds all the element views at the specified point
@@ -2461,7 +2628,7 @@ export declare namespace dia {
 
         getDefaultLink(cellView: CellView, magnet: SVGElement): Link;
 
-        getModelById(id: Cell.ID | Cell): Cell;
+        getModelById(id: Graph.CellRef): Cell;
 
         setDimensions(width: Paper.Dimension, height: Paper.Dimension, data?: any): void;
 
@@ -2497,29 +2664,38 @@ export declare namespace dia {
 
         // layers
 
-        getLayerNode(layerName: Paper.Layers | string): SVGGElement;
+        getLayerView(layerRef: Paper.LayerRef): LayerView;
+        getLayerView(layer: GraphLayer): GraphLayerView;
+
+        hasLayerView(layerRef: Paper.LayerRef): boolean;
+
+        getLayerViews(): Array<LayerView>;
+
+        getGraphLayerViews(): Array<GraphLayerView>;
 
-        getLayerView(layerName: Paper.Layers | string): PaperLayer;
+        addLayerView(layerView: LayerView, options?: Paper.InsertLayerViewOptions): void;
 
-        hasLayerView(layerName: Paper.Layers | string): boolean;
+        moveLayerView(layerRef: Paper.LayerRef, options?: Paper.InsertLayerViewOptions): void;
 
-        renderLayers(layers: Array<{ name: string }>): void;
+        removeLayerView(layerRef: Paper.LayerRef): void;
 
-        protected removeLayers(): void;
+        protected insertLayerView(layerView: LayerView, before?: Paper.LayerRef): void;
 
-        protected resetLayers(): void;
+        protected requestLayerViewRemoval(layerRef: Paper.LayerRef): void;
 
-        addLayer(layerName: string, layerView: PaperLayer, options?: { insertBefore?: string }): void;
+        protected createLayerView(options: Omit<LayerView.Options, 'paper'>): LayerView;
 
-        removeLayer(layer: string | PaperLayer): void;
+        protected getLayerViewOrder(): string[];
 
-        moveLayer(layer: string | PaperLayer, insertBefore: string | PaperLayer | null): void;
+        protected renderLayerViews(): void;
 
-        hasLayer(layer: string | PaperLayer): boolean;
+        protected renderImplicitLayerViews(): void;
 
-        getLayerNames(): string[];
+        protected renderGraphLayerViews(): void;
 
-        getLayers(): Array<PaperLayer>;
+        protected removeLayerViews(): void;
+
+        protected resetLayerViews(): void;
 
         // rendering
 
@@ -2533,7 +2709,9 @@ export declare namespace dia {
 
         requestViewUpdate(view: mvc.View<any, any>, flag: number, priority: number, opt?: { [key: string]: any }): void;
 
-        requireView<T extends ElementView | LinkView>(cellOrId: Cell | Cell.ID, opt?: Paper.UpdateViewOptions & Paper.RenderCallbackOptions): T;
+        requestCellViewInsertion(cell: Graph.CellRef, opt?: { [key: string]: any }): void;
+
+        requireView<T extends ElementView | LinkView>(cellOrId: Graph.CellRef, opt?: Paper.UpdateViewOptions & Paper.RenderCallbackOptions): T;
 
         updateViews(opt?: Paper.UpdateViewsOptions): Paper.RenderStats & { batches: number };
 
@@ -2541,10 +2719,10 @@ export declare namespace dia {
 
         disposeHiddenCellViews(): void;
 
-        isCellVisible(cellOrId: dia.Cell | dia.Cell.ID): boolean;
+        isCellVisible(cellOrId: Graph.CellRef): boolean;
 
         updateCellVisibility(
-        cell: Cell | Cell.ID,
+        cell: Graph.CellRef,
         opt?: Paper.CellVisibilityOptions & Paper.UpdateViewOptions & Paper.RenderCallbackOptions
         ): void;
 
@@ -2596,9 +2774,9 @@ export declare namespace dia {
 
         protected checkUnmountedViews(viewport: Paper.ViewportCallback, opt?: Paper.MountOptions): number;
 
-        protected prioritizeCellViewMount(cellOrId: dia.Cell | dia.Cell.ID): boolean;
+        protected prioritizeCellViewMount(cellOrId: Graph.CellRef): boolean;
 
-        protected prioritizeCellViewUnmount(cellOrId: dia.Cell | dia.Cell.ID): boolean;
+        protected prioritizeCellViewUnmount(cellOrId: Graph.CellRef): boolean;
 
         protected isViewMounted(viewOrCid: dia.CellView | string): boolean;
 
@@ -2659,6 +2837,14 @@ export declare namespace dia {
         protected onCellChanged(cell: Cell, opt: dia.Cell.Options): void;
         protected onCellChanged(cell: mvc.Collection<Cell>, opt: dia.Graph.Options): void;
 
+        protected onGraphLayerAdd(layer: GraphLayer, collection: mvc.Collection<GraphLayer>, opt: dia.Graph.Options): void;
+
+        protected onGraphLayerRemove(layer: GraphLayer, collection: mvc.Collection<GraphLayer>, opt: dia.Graph.Options): void;
+
+        protected onGraphLayerCollectionReset(layer: mvc.Collection<GraphLayer>, opt: dia.Graph.Options): void;
+
+        protected onGraphLayerCollectionSort(layer: GraphLayer[]): void;
+
         protected onGraphReset(cells: mvc.Collection<Cell>, opt: dia.Graph.Options): void;
 
         protected onGraphSort(): void;
@@ -2689,6 +2875,11 @@ export declare namespace dia {
 
         protected addStylesheet(stylesheet: string): void;
 
+        /**
+         * @deprecated use `getLayerView(id).el` instead
+         * **/
+        getLayerNode(id: Paper.Layers | string): SVGElement;
+
         /**
          * @deprecated use `findElementViewsAtPoint()
          */
@@ -2715,17 +2906,20 @@ export declare namespace dia {
         dumpViews(opt?: Paper.ScheduleCellsVisibilityUpdateOptions & Paper.UpdateViewsOptions): void;
     }
 
-    export namespace PaperLayer {
+    export namespace LayerView {
 
-        export interface Options extends mvc.ViewOptions<undefined, SVGElement> {
-            name: string;
+        export interface Options<T extends mvc.Model | undefined = undefined> extends mvc.ViewOptions<T, SVGElement> {
+            id: string;
+            paper: Paper;
+            type?: string;
         }
     }
-    export class PaperLayer extends mvc.View<undefined, SVGElement> {
 
-        constructor(opt?: PaperLayer.Options);
+    export class LayerView<T extends mvc.Model | undefined = undefined> extends mvc.View<T, SVGElement> {
 
-        options: PaperLayer.Options;
+        constructor(opt?: LayerView.Options);
+
+        options: LayerView.Options;
 
         pivotNodes: { [z: number]: Comment };
 
@@ -2735,7 +2929,78 @@ export declare namespace dia {
 
         insertPivot(z: number): Comment;
 
-        removePivots(): void;
+        isEmpty(): boolean;
+
+        reset(): void;
+
+        setPaperReference(paper: Paper): void;
+
+        unsetPaperReference(): void;
+
+        protected removePivots(): void;
+
+        protected afterPaperReferenceSet(paper: Paper): void;
+
+        protected beforePaperReferenceUnset(paper: Paper): void;
+
+        protected assertPaperReferenceSet(): void;
+    }
+
+    export namespace GraphLayer {
+
+        export type ID = string;
+
+        export interface Attributes extends mvc.ObjectHash {
+            id: ID;
+            type?: string;
+        }
+    }
+
+    export class GraphLayer<C extends CellCollection = CellCollection, A extends GraphLayer.Attributes = GraphLayer.Attributes, S extends mvc.ModelSetOptions = dia.ModelSetOptions> extends mvc.Model<A, S> {
+
+        id: string;
+
+        cellCollection: C;
+        graph: Graph | null;
+
+        constructor(attributes?: DeepPartial<A>, options?: mvc.ModelConstructorOptions<GraphLayer>);
+
+        getCells(): Cell[];
+    }
+
+    export class GraphLayerView<T extends GraphLayer = GraphLayer> extends LayerView<T> {
+
+        sort(): void;
+
+        sortExact(): void;
+
+        insertCellView(cellView: CellView): void;
+
+        protected onCellMove(cell: Cell, opt: Graph.Options): void;
+
+        protected onCellChange(cell: Cell, opt: Cell.Options): void;
+
+        protected onCellCollectionSort(collection: CellCollection, opt: Graph.Options): void;
+
+        protected onGraphBatchStop(data: any): void;
+    }
+
+    export namespace GridLayerView {
+
+        export interface Options extends LayerView.Options {
+            patterns?: Record<string, Paper.GridOptions[]>;
+        }
+    }
+
+    export class GridLayerView extends LayerView {
+
+        setGrid(opt?: null | boolean | string | Paper.GridOptions | Paper.GridOptions[]): void;
+
+        renderGrid(): void;
+
+        updateGrid(): void;
+
+        removeGrid(): void;
     }
 
     export namespace ToolsView {
@@ -4529,6 +4794,7 @@ export declare namespace mvc {
 
     export interface ModelConstructorOptions<TModel extends Model = Model> extends ModelSetOptions, Parseable {
         collection?: Collection<TModel> | undefined;
+        eventPrefix?: string | undefined;
     }
 
     export type CombinedModelConstructorOptions<E, M extends Model<any, any, E> = Model> = ModelConstructorOptions<M> & E;