@anymux/ui-kit 0.1.0

package/src/tree/providers/TreeProvider.ts

@@ -0,0 +1,308 @@
+/**
+ * TreeProvider Interface
+ * 
+ * Defines the contract for providing tree data to the Tree component.
+ * This abstraction allows different data sources (file systems, APIs, static data)
+ * to be used with the same tree component. Provider can work without React.
+ */
+
+import type React from 'react';
+import type { TreeNodeData, TreeLoadResult, TreeLoadOptions, TreeContextMenuItem, TreeTableColumn, TreeTableSort, TreeTableExportOptions, TreeSelectionTheme } from '../types/TreeTypes';
+
+export interface TreeNodeRenderer {
+  /** Render node as string (for non-React environments) */
+  renderText?(node: TreeNodeData): string;
+  /** Render node icon as string/identifier */
+  renderIcon?(node: TreeNodeData): string;
+  /** Get node display properties */
+  getDisplayProps?(node: TreeNodeData): {
+    className?: string;
+    style?: Record<string, string>;
+    title?: string;
+    ariaLabel?: string;
+  };
+  /** Custom React component for node (if in React environment) */
+  renderComponent?: React.ComponentType<{ node: TreeNodeData; [key: string]: any }>;
+}
+
+export interface TreeDragDropInfo {
+  /** Source node being dragged */
+  sourceNode: TreeNodeData;
+  /** Target node being dropped on */
+  targetNode: TreeNodeData;
+  /** Drop position relative to target */
+  position: 'before' | 'after' | 'inside';
+  /** Additional drag data */
+  dragData?: any;
+}
+
+export interface TreeSelectionInfo {
+  /** Selected nodes */
+  selectedNodes: TreeNodeData[];
+  /** Previously selected nodes */
+  previousSelection: TreeNodeData[];
+  /** Selection type */
+  selectionType: 'single' | 'multi' | 'range';
+  /** Selection trigger */
+  trigger: 'click' | 'keyboard' | 'api';
+}
+
+export interface TreeProvider {
+  /** Provider identifier */
+  readonly id: string;
+  /** Human-readable name */
+  readonly name: string;
+  /** Provider version */
+  readonly version: string;
+
+  // =====================
+  // Configuration Methods
+  // =====================
+
+  /**
+   * Whether multi-selection is enabled
+   */
+  isMultiSelectEnabled: boolean;
+
+  /**
+   * Whether drag and drop is enabled
+   */
+  readonly isDragDropEnabled: boolean;
+
+  /**
+   * Whether virtualization is enabled for large trees
+   */
+  readonly isVirtualizationEnabled: boolean;
+
+  /**
+   * Whether to use checkbox-based selection instead of highlight selection
+   */
+  readonly useCheckboxSelection?: boolean;
+
+  /**
+   * Whether to allow partial (indeterminate) checkbox selection for parent nodes
+   */
+  readonly allowPartialSelection?: boolean;
+
+  /**
+   * Whether table view is enabled for this provider
+   */
+  readonly isTableViewEnabled?: boolean;
+
+  /**
+   * Get virtualization configuration
+   */
+  getVirtualizationConfig?(): {
+    itemHeight: number;
+    overscan: number;
+    threshold: number;
+  };
+
+  /**
+   * Get table column configuration for table view
+   */
+  getTableColumns?(): TreeTableColumn[];
+
+  /**
+   * Get default sort configuration for table view
+   */
+  getDefaultTableSort?(): TreeTableSort | null;
+
+  /**
+   * Get selection theme configuration
+   */
+  getSelectionTheme?(): TreeSelectionTheme;
+
+  // =====================
+  // Data Loading Methods
+  // =====================
+
+  /**
+   * Load tree nodes
+   * @param options Loading options
+   * @returns Promise resolving to loaded nodes
+   */
+  loadNodes(options?: TreeLoadOptions): Promise<TreeLoadResult>;
+
+  /**
+   * Load children for a specific node
+   * @param node Parent node
+   * @param options Loading options
+   * @returns Promise resolving to child nodes
+   */
+  loadChildren(node: TreeNodeData, options?: TreeLoadOptions): Promise<TreeLoadResult>;
+
+  /**
+   * Refresh/reload nodes
+   * @param path Specific path to refresh (optional)
+   * @returns Promise resolving to refreshed nodes
+   */
+  refresh(path?: string): Promise<TreeLoadResult>;
+
+  /**
+   * Search nodes
+   * @param query Search query
+   * @param options Search options
+   * @returns Promise resolving to search results
+   */
+  search?(query: string, options?: TreeLoadOptions): Promise<TreeLoadResult>;
+
+  // =====================
+  // Node Context Menus
+  // =====================
+
+  /**
+   * Get context menu items for a specific node
+   * @param node Target node
+   * @returns Array of context menu items
+   */
+  getNodeContextMenu?(node: TreeNodeData): TreeContextMenuItem[];
+
+  /**
+   * Get context menu items for multiple selected nodes
+   * @param nodes Selected nodes
+   * @returns Array of context menu items
+   */
+  getMultiNodeContextMenu?(nodes: TreeNodeData[]): TreeContextMenuItem[];
+
+  /**
+   * Get context menu items for empty space (no node)
+   * @param parentNode Parent node where right-click occurred
+   * @returns Array of context menu items
+   */
+  getEmptySpaceContextMenu?(parentNode?: TreeNodeData): TreeContextMenuItem[];
+
+  // =====================
+  // Node Rendering
+  // =====================
+
+  /**
+   * Get custom renderer for a specific node
+   * @param node Target node
+   * @returns Node renderer or null for default rendering
+   */
+  getNodeRenderer?(node: TreeNodeData): TreeNodeRenderer | null;
+
+  /**
+   * Get default renderer for all nodes of this provider
+   * @returns Default node renderer
+   */
+  getDefaultRenderer?(): TreeNodeRenderer;
+
+  /**
+   * Get custom icon for a node
+   * @param node Target node
+   * @returns Icon identifier or component
+   */
+  getNodeIcon?(node: TreeNodeData): string | React.ComponentType<any>;
+
+  // =====================
+  // Node Capabilities
+  // =====================
+
+  /**
+   * Check if a node can be expanded
+   * @param node Target node
+   * @returns Whether node can be expanded
+   */
+  canExpand?(node: TreeNodeData): boolean;
+
+  /**
+   * Check if a node can be selected
+   * @param node Target node
+   * @returns Whether node can be selected
+   */
+  canSelect?(node: TreeNodeData): boolean;
+
+  /**
+   * Check if nodes can be dragged
+   * @param nodes Nodes to check
+   * @returns Whether nodes can be dragged
+   */
+  canDrag?(nodes: TreeNodeData[]): boolean;
+
+  /**
+   * Check if a drop operation is allowed
+   * @param dragInfo Drag and drop information
+   * @returns Whether drop is allowed
+   */
+  canDrop?(dragInfo: TreeDragDropInfo): boolean;
+
+  // =====================
+  // Event Callbacks
+  // =====================
+
+  /**
+   * Called when node selection changes
+   * @param selectionInfo Selection information
+   */
+  onSelectionChange?(selectionInfo: TreeSelectionInfo): void;
+
+  /**
+   * Called when a node is expanded or collapsed
+   * @param node Target node
+   * @param expanded New expansion state
+   */
+  onNodeExpansion?(node: TreeNodeData, expanded: boolean): void;
+
+  /**
+   * Called when a node is double-clicked
+   * @param node Target node
+   */
+  onNodeDoubleClick?(node: TreeNodeData): void;
+
+  /**
+   * Called when a drag and drop operation completes
+   * @param dragInfo Drag and drop information
+   * @returns Promise resolving when operation is complete
+   */
+  onDragDrop?(dragInfo: TreeDragDropInfo): Promise<void>;
+
+  /**
+   * Called when a context menu item is selected
+   * @param menuItemId Menu item identifier
+   * @param node Target node (or nodes for multi-selection)
+   */
+  onContextMenuAction?(menuItemId: string, nodes: TreeNodeData[]): void;
+
+  /**
+   * Called when a node is focused
+   * @param node Target node or null if focus lost
+   */
+  onNodeFocus?(node: TreeNodeData | null): void;
+
+  /**
+   * Called when table sort changes
+   * @param sort New sort configuration
+   */
+  onTableSort?(sort: TreeTableSort | null): void;
+
+  /**
+   * Called when table data export is requested
+   * @param options Export configuration
+   * @returns Promise resolving to exported data or download trigger
+   */
+  onTableExport?(options: TreeTableExportOptions): Promise<string | void>;
+
+  // =====================
+  // Lifecycle Methods
+  // =====================
+
+  /**
+   * Initialize the provider
+   * @returns Promise resolving when initialization is complete
+   */
+  initialize?(): Promise<void>;
+
+  /**
+   * Cleanup provider resources
+   */
+  dispose?(): void;
+
+  /**
+   * Provider-specific configuration
+   */
+  readonly config?: Record<string, any>;
+}
+
+// NOTE: No factory or registry pattern - providers passed directly to Tree component