Item Management

/**
 * Base interface for all graph items
 */
interface IItemBase {
  _cfg: IItemBaseConfig | null;
  destroyed: boolean;
  
  // Type and identification
  isItem(): boolean;
  getType(): ITEM_TYPE;
  getID(): string;
  
  // Model and configuration
  getModel(): NodeConfig | EdgeConfig | ComboConfig | TreeGraphData;
  getShapeCfg(model: ModelConfig): ModelConfig;
  get<T = any>(key: string): T;
  set<T = any>(key: string, value: T): void;
  
  // Graphics and rendering
  getContainer(): IGroup;
  getKeyShape(): IShapeBase;
  draw(): void;
  updateShape(): void;
  updatePosition(cfg: Point): void;
  refresh(): void;
  update(cfg: ModelConfig, onlyMove?: boolean): void;
  
  // Style and state management
  getShapeStyleByName(name?: string): ShapeStyle;
  getStates(): string[];
  hasState(state: string): boolean;
  getStateStyle(state: string): ShapeStyle;
  getOriginStyle(): ShapeStyle;
  getCurrentStatesStyle(): ShapeStyle;
  setState(state: string, value: string | boolean): void;
  clearStates(states?: string | string[]): void;
  
  // Bounding box calculations
  getBBox(): IBBox;
  getCanvasBBox(): IBBox;
  
  // Visibility and z-index
  show(): void;
  hide(): void;
  changeVisibility(visible: boolean): void;
  isVisible(): boolean;
  toFront(): void;
  toBack(): void;
  
  // Interaction
  enableCapture(enable: boolean): void;
  
  // Utilities
  isOnlyMove(cfg: ModelConfig): boolean;
  destroy(): void;
}

/**
 * Node interface extending base item with edge connections and anchor points
 */
interface INode extends IItemBase {
  // Edge management
  getEdges(): IEdge[];
  getInEdges(): IEdge[];
  getOutEdges(): IEdge[];
  addEdge(edge: IEdge): void;
  removeEdge(edge: IEdge): void;
  
  // Connection points
  getLinkPointByAnchor(index: number): IPoint;
  getLinkPoint(point: IPoint): IPoint | null;
  getAnchorPoints(): IPoint[] | number[][];
  
  // Lock functionality
  hasLocked(): boolean;
  lock(): void;
  unlock(): void;
  
  // Graph analysis
  getNeighbors(type?: 'source' | 'target' | undefined): INode[];
}

// Get all connected edges
const allEdges = node.getEdges();
const incomingEdges = node.getInEdges();
const outgoingEdges = node.getOutEdges();

// Work with connection points
const anchorPoints = node.getAnchorPoints();
const linkPoint = node.getLinkPointByAnchor(0);

// Node locking
node.lock();   // Prevent node from moving
node.unlock(); // Allow node movement
const isLocked = node.hasLocked();

// Get neighboring nodes
const allNeighbors = node.getNeighbors();
const sourceNodes = node.getNeighbors('source');
const targetNodes = node.getNeighbors('target');

/**
 * Edge interface extending base item with source/target connections
 */
interface IEdge extends IItemBase {
  // Connection management
  setSource(source: INode | ICombo): void;
  setTarget(target: INode | ICombo): void;
  getSource(): INode | ICombo;
  getTarget(): INode | ICombo;
}

// Get edge endpoints
const sourceItem = edge.getSource();
const targetItem = edge.getTarget();

// Change edge connections
edge.setSource(newSourceNode);
edge.setTarget(newTargetNode);

// Type checking edge endpoints
if (sourceItem.getType() === 'node') {
  const sourceNode = sourceItem as INode;
  // Work with source node
}

/**
 * Combo interface extending node with child management capabilities
 */
interface ICombo extends INode {
  // Child management
  getChildren(): { nodes: INode[]; combos: ICombo[] };
  getNodes(): INode[];
  getCombos(): INode[];
  
  // Adding children
  addChild(item: INode | ICombo): boolean;
  addCombo(combo: ICombo): boolean;
  addNode(node: string | INode): boolean;
  
  // Removing children
  removeChild(item: ICombo | INode): boolean;
  removeCombo(combo: ICombo): boolean;
  removeNode(node: string | INode): boolean;
}

// Get combo children
const children = combo.getChildren();
const childNodes = combo.getNodes();
const childCombos = combo.getCombos();

// Add items to combo
combo.addNode(nodeInstance);
combo.addNode('node-id');
combo.addCombo(childCombo);
combo.addChild(nodeOrCombo);

// Remove items from combo
combo.removeNode(nodeInstance);
combo.removeNode('node-id');
combo.removeCombo(childCombo);
combo.removeChild(nodeOrCombo);

// Check if operations succeeded
const added = combo.addNode(node);
const removed = combo.removeNode(node);

/**
 * Set item state with value
 * @param state - State name (e.g., 'hover', 'selected', 'active')
 * @param value - State value (boolean or string)
 */
setState(state: string, value: string | boolean): void;

/**
 * Get all current states
 * @returns Array of active state names
 */
getStates(): string[];

/**
 * Check if item has specific state
 * @param state - State name to check
 * @returns True if item has the state
 */
hasState(state: string): boolean;

/**
 * Clear specific states or all states
 * @param states - State names to clear (all if not specified)
 */
clearStates(states?: string | string[]): void;

/**
 * Get style for specific state
 * @param state - State name
 * @returns State-specific style object
 */
getStateStyle(state: string): ShapeStyle;

/**
 * Get current combined style from all active states
 * @returns Combined style from all states
 */
getCurrentStatesStyle(): ShapeStyle;

/**
 * Get original style without state modifications
 * @returns Original item style
 */
getOriginStyle(): ShapeStyle;

// Set various states
item.setState('selected', true);
item.setState('hover', true);
item.setState('custom-state', 'value');

// Check states
const isSelected = item.hasState('selected');
const allStates = item.getStates(); // ['selected', 'hover', 'custom-state']

// Clear states
item.clearStates('hover');           // Clear specific state
item.clearStates(['hover', 'selected']); // Clear multiple states
item.clearStates();                  // Clear all states

// Get styling information
const hoverStyle = item.getStateStyle('hover');
const currentStyle = item.getCurrentStatesStyle();
const originalStyle = item.getOriginStyle();

/**
 * Get local bounding box
 * @returns Local bounding box coordinates
 */
getBBox(): IBBox;

/**
 * Get canvas bounding box (transformed coordinates)
 * @returns Canvas bounding box coordinates
 */
getCanvasBBox(): IBBox;

/**
 * Update item position only
 * @param cfg - New position coordinates
 */
updatePosition(cfg: Point): void;

/**
 * Check if update only affects position
 * @param cfg - Configuration to check
 * @returns True if only position changes
 */
isOnlyMove(cfg: ModelConfig): boolean;

/**
 * Get graphics container holding item shapes
 * @returns Graphics group container
 */
getContainer(): IGroup;

/**
 * Get key shape used for bounds calculation and events
 * @returns Main shape element
 */
getKeyShape(): IShapeBase;

/**
 * Draw item initially
 */
draw(): void;

/**
 * Update item appearance based on current configuration
 */
updateShape(): void;

/**
 * Full refresh of item display
 */
refresh(): void;

/**
 * Update item with new configuration
 * @param cfg - Updated model configuration
 * @param onlyMove - Whether update only affects position
 */
update(cfg: ModelConfig, onlyMove?: boolean): void;

/**
 * Get shape style by shape name
 * @param name - Shape name (optional, gets key shape if not specified)
 * @returns Shape style object
 */
getShapeStyleByName(name?: string): ShapeStyle;

/**
 * Show hidden item
 */
show(): void;

/**
 * Hide visible item
 */
hide(): void;

/**
 * Change visibility state
 * @param visible - Whether item should be visible
 */
changeVisibility(visible: boolean): void;

/**
 * Check if item is currently visible
 * @returns True if item is visible
 */
isVisible(): boolean;

/**
 * Bring item to front (highest z-index)
 */
toFront(): void;

/**
 * Send item to back (lowest z-index)
 */
toBack(): void;

/**
 * Enable or disable event capture for item
 * @param enable - Whether to capture events
 */
enableCapture(enable: boolean): void;

/**
 * Destroy item and clean up resources
 * Removes from graph and clears all references
 */
destroy(): void;

/**
 * Check if item has been destroyed
 * @returns True if item is destroyed
 */
isDestroyed(): boolean;

/**
 * Add edge connection to this node
 * @param edge - Edge to add
 */
addEdge(edge: IEdge): void;

/**
 * Remove edge connection from this node
 * @param edge - Edge to remove
 */
removeEdge(edge: IEdge): void;

/**
 * Get link point for edge connection
 * @param point - Target point for connection
 * @returns Calculated link point or null
 */
getLinkPoint(point: IPoint): IPoint | null;

/**
 * Check if node is locked (cannot be moved)
 * @returns True if node is locked
 */
hasLocked(): boolean;

/**
 * Lock node to prevent movement
 */
lock(): void;

/**
 * Unlock node to allow movement
 */
unlock(): void;

interface NodeConfig extends ModelConfig {
  id: string;
  groupId?: string;
  comboId?: string;
  children?: TreeGraphData[];
  description?: string;
  descriptionCfg?: { style?: object; [key: string]: any };
  img?: string;
  innerR?: number;
  direction?: string;
  preRect?: { show?: boolean; [key: string]: any };
  logoIcon?: { show?: boolean; [key: string]: any };
  stateIcon?: { show?: boolean; [key: string]: any };
  linkPoints?: {
    top?: boolean;
    right?: boolean;
    bottom?: boolean;
    left?: boolean;
    size?: number;
    lineWidth?: number;
    fill?: string;
    stroke?: string;
    r?: number;
    [key: string]: any;
  };
  icon?: {
    show?: boolean;
    img?: string;
    width?: number;
    height?: number;
    offset?: number;
  };
  clipCfg?: {
    show?: boolean;
    type?: string;
    r?: number;
    rx?: number;
    ry?: number;
    width?: number;
    height?: number;
    points?: number[][];
    path?: Array<Array<string | number>>;
    x?: number;
    y?: number;
  };
}

interface EdgeConfig extends ModelConfig {
  id?: string;
  source?: string;
  target?: string;
  sourceNode?: Node;
  targetNode?: Node;
  startPoint?: IPoint;
  endPoint?: IPoint;
  controlPoints?: IPoint[];
  curveOffset?: number | number[];
  loopCfg?: LoopConfig;
  labelCfg?: ILabelConfig;
}

interface ComboConfig extends ModelConfig {
  id: string;
  parentId?: string;
  children?: ComboTree[];
  depth?: number;
  padding?: number | number[];
  collapseIcon?: Partial<{
    show: boolean;
    collapseSymbol: any;
    expandSymbol: any;
    r: number;
    lineWidth: number;
    stroke: string;
    offsetX: number;
    offsetY: number;
  }>;
}

interface ModelConfig {
  type?: string;
  label?: string | LabelStyle;
  labelCfg?: ILabelConfig;
  x?: number;
  y?: number;
  size?: number | number[];
  color?: string;
  anchorPoints?: number[][];
  startPoint?: { x: number; y: number };
  endPoint?: { x: number; y: number };
  visible?: boolean;
}

interface IItemBaseConfig {
  type: string;
  model: ModelConfig;
  group: IGroup;
  keyShape: IShapeBase;
  [key: string]: any;
}

interface ComboTree {
  id: string;
  children?: ComboTree[];
  depth?: number;
  [key: string]: any;
}

interface LoopConfig {
  dist?: number;
  position?: string;
  clockwise?: boolean;
}

interface ILabelConfig {
  position?: string;
  offset?: number;
  refX?: number;
  refY?: number;
  autoRotate?: boolean;
  style?: LabelStyle;
}

interface LabelStyle {
  fill?: string;
  fontSize?: number;
  fontWeight?: string | number;
  textAlign?: string;
  textBaseline?: string;
  [key: string]: any;
}