@gravity-ui/graph
Version:
Modern graph editor component
225 lines (224 loc) • 9 kB
TypeScript
import { GraphComponent } from "./components/canvas/GraphComponent";
import { ESelectionStrategy } from "./services/selection";
import type { TMouseWheelBehavior, TWheelInputDevice } from "./utils/functions/wheelIntent";
export type { TResolveWheelIntent, TResolveWheelIntentOptions, TWheelInputDevice, TWheelIntentRule, } from "./utils/functions/wheelIntent";
export { createWheelIntentResolver, enableWheelIntentDebug, EWheelIntent, isI3WheelIntentRule, isI4WheelIntentRule, WHEEL_INTENT_RULE, } from "./utils/functions/wheelIntent";
export type { TMouseWheelBehavior };
export type TGraphColors = {
canvas?: Partial<TCanvasColors>;
block?: Partial<TBlockColors>;
anchor?: Partial<TAnchorColors>;
connection?: Partial<TConnectionColors>;
connectionLabel?: Partial<TConnectionLabelColors>;
selection?: Partial<TSelectionColors>;
};
export type TSelectionColors = {
background: string;
border: string;
};
export type TConnectionLabelColors = {
background: string;
hoverBackground: string;
selectedBackground: string;
text: string;
hoverText: string;
selectedText: string;
};
export type TConnectionColors = {
background: string;
selectedBackground: string;
};
export type TAnchorColors = {
background: string;
selectedBorder: string;
};
export type TBlockColors = {
background: string;
border: string;
text: string;
selectedBorder: string;
};
export type TCanvasColors = {
belowLayerBackground: string;
layerBackground: string;
dots: string;
border: string;
};
export declare const initGraphColors: TGraphColors;
/**
* Constructor type for any class that extends GraphComponent
*/
export type GraphComponentConstructor = new (...args: unknown[]) => GraphComponent;
export type TGraphConstants = {
/**
* Configuration for the selection layer behavior.
* The selection layer is responsible for rendering the selection rectangle
* and managing which entities can be selected when the user draws a selection box on the canvas.
*/
selectionLayer: {
/**
* List of entity types that can be selected via the selection rectangle.
*
* Only entities whose constructors are included in this array will be selectable
* when the user draws a selection rectangle on the canvas. This allows fine-grained
* control over which types of graph components can be multi-selected.
*
* @remarks
* - By default, only `Block` entities are selectable
* - You can extend this to include other entity types like connections, anchors, etc.
* - Each entry must be a constructor (class) that extends `GraphComponent`
*
* @example
* ```typescript
* // Allow selecting both blocks and connections
* selectionLayer: {
* SELECTABLE_ENTITY_TYPES: [GraphComponent, Block, Connection]
* }
* ```
*
* @default [Block]
*/
SELECTABLE_ENTITY_TYPES: GraphComponentConstructor[];
/**
* Selection strategy that determines how newly selected entities interact with existing selection.
*
* Available strategies:
* - **`REPLACE`** - New selection replaces the current selection entirely
* - **`APPEND`** - New selection is added to the current selection
* - **`SUBTRACT`** - New selection is removed from the current selection
* - **`TOGGLE`** - New selection toggles the selection state of entities
*
* @remarks
* This strategy is applied when the user completes drawing a selection rectangle
* and determines how the entities inside the rectangle affect the overall selection state.
*
* @example
* ```typescript
* // Additive selection mode
* selectionLayer: {
* STRATEGY: ESelectionStrategy.APPEND
* }
* ```
*
* @default ESelectionStrategy.REPLACE
*/
STRATEGY?: ESelectionStrategy;
/**
* Selection strategy that determines how newly selected entities interact with existing selection when Shift key is pressed.
*
* Available strategies:
* - **`REPLACE`** - New selection replaces the current selection entirely
* - **`APPEND`** - New selection is added to the current selection
* - **`SUBTRACT`** - New selection is removed from the current selection
* - **`TOGGLE`** - New selection toggles the selection state of entities
*
* @default ESelectionStrategy.APPEND
*/
SHIFT_STRATEGY?: ESelectionStrategy;
};
system: {
GRID_SIZE: number;
/**
* @deprecated this config is not used anymore, Layers checks devicePixelRatio internally
*/
PIXEL_RATIO: number;
USABLE_RECT_GAP: number;
/** For preload blocks on the html layer (camera dimensions * (1 + this value)) */
CAMERA_VIEWPORT_TRESHOLD: number;
};
camera: {
SPEED: number;
STEP: number;
/**
* Auto-panning threshold: distance from edge in pixels to activate auto-panning
* @default 50
*/
AUTO_PAN_THRESHOLD: number;
/**
* Auto-panning speed: base pixels per frame for camera movement
* @default 10
*/
AUTO_PAN_SPEED: number;
/**
* Controls the behavior of mouse wheel events.
*
* - **"zoom"**: Mouse wheel will zoom in/out the graph
* - **"scroll"**: Mouse wheel will scroll the graph vertically by default, or horizontally when Shift is pressed
*
* @remarks
* **Mouse wheel scrolling behavior:**
* - Default scroll direction is vertical (up/down)
* - Holding Shift key switches to horizontal scrolling (left/right)
* - This is an environment-dependent behavior as per W3C UI Events specification
* - Different browsers and operating systems may handle Shift+wheel differently
*
* **Trackpad behavior (via `resolveWheelIntent`):**
* - Integer PIXEL two-finger swipe resolves to pan (I3) — not affected by this constant
* - Pinch-to-zoom (Cmd/Ctrl + scroll) resolves to zoom with {@link PINCH_ZOOM_SPEED}
* - Horizontal / diagonal swipe resolves to pan (I2)
* - Override ambiguous Mac Chrome input with camera constant `WHEEL_INPUT_DEVICE`
* - See `docs/system/wheel-intent.md` for classification rules
*
* @default "zoom"
* @see https://w3c.github.io/uievents/#events-wheelevents - W3C UI Events Wheel Events specification
*/
MOUSE_WHEEL_BEHAVIOR: TMouseWheelBehavior;
/**
* Explicit primary wheel input device passed to {@link TResolveWheelIntent}.
* When `"auto"`, the resolver infers trackpad vs mouse from gesture shape.
* Set to `"trackpad"` or `"mouse"` when the app knows the device (e.g. Mac Chrome
* where both emit integer PIXEL + linear wheelDelta).
*
* @default "auto"
*/
WHEEL_INPUT_DEVICE: TWheelInputDevice;
/**
* Multiplier for trackpad pinch-to-zoom gesture speed.
* Applied when zooming with trackpad using pinch gesture (Cmd/Ctrl + scroll).
*
* @default 1
*/
PINCH_ZOOM_SPEED: number;
/**
* Multiplier for camera pan speed applied to trackpad two-finger swipe (and
* mouse-wheel scroll when MOUSE_WHEEL_BEHAVIOR is "scroll"). Pointer drag
* (mouse drag and single-finger trackpad drag) tracks the cursor 1:1 and
* is not affected — applying a multiplier there would slide the canvas
* out from under the cursor. Does not affect auto-panning (see AUTO_PAN_SPEED)
* or zoom speed (see SPEED, PINCH_ZOOM_SPEED).
*
* @default 1
*/
PAN_SPEED: number;
};
block: {
WIDTH_MIN: number;
BORDER_WIDTH: number;
HEAD_HEIGHT: number;
BODY_PADDING: number;
SCALES: [number, number, number];
DEFAULT_Z_INDEX: number;
INCRIMENT_Z_INDEX: number;
GHOST_BLOCK_OPACITY: number;
WIDTH: number;
HEIGHT: number;
SNAPPING_GRID_SIZE: number;
};
connection: {
MUTED_CANVAS_CONNECTION_WIDTH: number;
SCALES: [number, number, number];
DEFAULT_Z_INDEX: number;
THRESHOLD_LINE_HIT: number;
MIN_ZOOM_FOR_CONNECTION_ARROW_AND_LABEL: number;
/** Size of Path2D chunks for batch rendering */
PATH2D_CHUNK_SIZE: number;
LABEL: {
INNER_PADDINGS: [number, number, number, number];
};
};
text: {
BASE_FONT_SIZE: number;
PADDING: number;
};
};
export declare const initGraphConstants: TGraphConstants;