@anymux/ui-kit 0.1.0

package/src/tree/types/TreeTypes.ts

@@ -0,0 +1,279 @@
+/**
+ * Core type definitions for TreeComponent
+ * 
+ * These types define the fundamental data structures used throughout
+ * the tree component system, including node data, loading results,
+ * and configuration options.
+ */
+
+/**
+ * Represents a single node in the tree structure
+ * 
+ * This interface defines the core properties that every tree node must have,
+ * along with optional properties for enhanced functionality like lazy loading,
+ * custom styling, and metadata storage.
+ */
+export interface TreeNodeData {
+  /** Unique identifier for the node */
+  id: string;
+  
+  /** Display name of the node */
+  name: string;
+  
+  /** Full path or identifier for the node */
+  path: string;
+  
+  /** Type of node (file, directory, custom types) */
+  type: 'file' | 'directory' | string;
+  
+  /** Whether this node has children (for lazy loading) */
+  hasChildren?: boolean;
+  
+  /** Child nodes (if loaded) */
+  children?: TreeNodeData[];
+  
+  /** Custom metadata for the node */
+  metadata?: Record<string, any>;
+  
+  /** Size in bytes (for files) */
+  size?: number;
+  
+  /** Last modified date */
+  lastModified?: Date;
+  
+  /** Custom icon identifier */
+  icon?: string;
+  
+  /** Custom CSS class */
+  className?: string;
+  
+  /** Whether the node is disabled */
+  disabled?: boolean;
+  
+  /** Custom render data for this specific node */
+  renderData?: Record<string, any>;
+}
+
+/**
+ * Result of loading tree nodes
+ * 
+ * This interface defines what providers return when loading tree data,
+ * including the nodes themselves and metadata about the loading operation.
+ */
+export interface TreeLoadResult {
+  /** The loaded nodes */
+  nodes: TreeNodeData[];
+  
+  /** Whether there are more nodes to load */
+  hasMore?: boolean;
+  
+  /** Total count of nodes (for virtual scrolling) */
+  totalCount?: number;
+  
+  /** Any loading errors */
+  error?: Error;
+}
+
+/**
+ * Configuration options for loading tree data
+ */
+export interface TreeLoadOptions {
+  /**
+   * Filter to apply when loading nodes
+   */
+  filter?: string;
+  
+  /**
+   * Whether to force reload even if data is cached
+   */
+  forceReload?: boolean;
+  
+  /**
+   * Maximum depth to load initially
+   */
+  maxDepth?: number;
+}
+
+/**
+ * Context menu item definition
+ */
+export interface TreeContextMenuItem {
+  /**
+   * Unique identifier for the menu item
+   */
+  id: string;
+  
+  /**
+   * Display label for the menu item
+   */
+  label: string;
+  
+  /**
+   * Optional icon for the menu item
+   */
+  icon?: string;
+  
+  /**
+   * Whether the menu item is disabled
+   */
+  disabled?: boolean;
+  
+  /**
+   * Whether to show a separator after this item
+   */
+  separator?: boolean;
+  
+  /**
+   * Type of menu item (for separators)
+   */
+  type?: 'separator' | 'item';
+  
+  /**
+   * Handler function for menu item clicks
+   */
+  handler?: (node: TreeNodeData) => void;
+  
+  /**
+   * Submenu items (for nested menus)
+   */
+  submenu?: TreeContextMenuItem[];
+}
+
+/**
+ * Context menu event data
+ */
+export interface TreeContextMenuEvent {
+  /**
+   * The menu item that was clicked
+   */
+  menuItem: TreeContextMenuItem;
+  
+  /**
+   * The nodes that the context menu was triggered for
+   */
+  nodes: TreeNodeData[];
+  
+  /**
+   * The mouse event that triggered the menu
+   */
+  originalEvent: MouseEvent;
+}
+
+/**
+ * Column configuration for table view display
+ */
+export interface TreeTableColumn {
+  /** Unique identifier for the column */
+  id: string;
+  
+  /** Display label for the column header */
+  label: string;
+  
+  /** Property path in TreeNodeData to display (supports dot notation) */
+  dataKey: string;
+  
+  /** Column width (CSS value) */
+  width?: string;
+  
+  /** Minimum width (CSS value) */
+  minWidth?: string;
+  
+  /** Column alignment */
+  align?: 'left' | 'center' | 'right';
+  
+  /** Whether column is sortable */
+  sortable?: boolean;
+  
+  /** Whether column is filterable */
+  filterable?: boolean;
+  
+  /** Whether this column displays the tree hierarchy */
+  isTreeColumn?: boolean;
+  
+  /** Custom CSS classes for the column */
+  className?: string;
+  
+  /** Custom cell renderer function */
+  renderCell?: (value: any, node: TreeNodeData) => React.ReactNode;
+  
+  /** Custom value formatter */
+  formatValue?: (value: any, node: TreeNodeData) => string;
+}
+
+/**
+ * Sort configuration for table view
+ */
+export interface TreeTableSort {
+  /** Column ID to sort by */
+  columnId: string;
+  
+  /** Sort direction */
+  direction: 'asc' | 'desc';
+}
+
+/**
+ * Export configuration for table view
+ */
+export interface TreeTableExportOptions {
+  /** Export format */
+  format: 'csv' | 'json' | 'tsv';
+  
+  /** Column IDs to include (empty = all columns) */
+  columns?: string[];
+  
+  /** Whether to include hierarchy structure */
+  includeHierarchy?: boolean;
+  
+  /** Whether to flatten nested data */
+  flatten?: boolean;
+  
+  /** Custom filename for download */
+  filename?: string;
+}
+
+/**
+ * Selection theme color scheme
+ */
+export type SelectionColorScheme = 'primary' | 'secondary' | 'accent' | 'custom';
+
+/**
+ * Selection intensity levels
+ */
+export type SelectionIntensity = 'subtle' | 'prominent' | 'high-contrast';
+
+/**
+ * Focus indicator style
+ */
+export type FocusIndicatorStyle = 'ring' | 'outline' | 'border' | 'underline';
+
+/**
+ * Enhanced selection theme configuration
+ */
+export interface TreeSelectionTheme {
+  /** Color scheme for selection highlighting */
+  colorScheme: SelectionColorScheme;
+  
+  /** Selection intensity level */
+  intensity: SelectionIntensity;
+  
+  /** Focus indicator style */
+  focusStyle: FocusIndicatorStyle;
+  
+  /** Custom colors when using 'custom' color scheme */
+  customColors?: {
+    /** Background color for selected items */
+    background: string;
+    
+    /** Text color for selected items */
+    foreground: string;
+    
+    /** Border/focus color */
+    accent: string;
+  };
+  
+  /** Whether to animate selection changes */
+  animated?: boolean;
+  
+  /** Whether to show selection even when component loses focus */
+  persistSelection?: boolean;
+} 

package/src/tree/utils/SelectionTheme.ts

@@ -0,0 +1,150 @@
+/**
+ * SelectionTheme - Utility for theme-aware selection styling
+ * 
+ * This module provides utilities for generating theme-aware CSS classes
+ * for tree node selection based on the configured selection theme.
+ */
+
+import { cn } from '../../lib/utils';
+import type { TreeSelectionTheme, SelectionColorScheme, SelectionIntensity, FocusIndicatorStyle } from '../types/TreeTypes';
+
+/**
+ * Default selection theme configuration
+ */
+export const DEFAULT_SELECTION_THEME: TreeSelectionTheme = {
+  colorScheme: 'primary',
+  intensity: 'subtle',
+  focusStyle: 'ring',
+  animated: true,
+  persistSelection: true
+};
+
+/**
+ * Generate selection background classes based on color scheme and intensity
+ */
+export function getSelectionBackground(colorScheme: SelectionColorScheme, intensity: SelectionIntensity): string {
+  if (colorScheme === 'custom') {
+    // Use inline styles for custom colors - return empty string for CSS classes
+    return '';
+  }
+
+  const intensityMap = {
+    subtle: {
+      primary: 'bg-primary/10',
+      secondary: 'bg-secondary/10',
+      accent: 'bg-accent/20',
+      muted: 'bg-muted'
+    },
+    prominent: {
+      primary: 'bg-primary/20',
+      secondary: 'bg-secondary/20', 
+      accent: 'bg-accent/40',
+      muted: 'bg-muted/60'
+    },
+    'high-contrast': {
+      primary: 'bg-primary text-primary-foreground',
+      secondary: 'bg-secondary text-secondary-foreground',
+      accent: 'bg-accent text-accent-foreground',
+      muted: 'bg-muted-foreground text-muted'
+    }
+  };
+
+  return intensityMap[intensity]?.[colorScheme] || intensityMap.subtle.primary;
+}
+
+/**
+ * Generate hover background classes
+ */
+export function getHoverBackground(colorScheme: SelectionColorScheme): string {
+  if (colorScheme === 'custom') {
+    // Use inline styles for custom colors instead of CSS custom properties
+    return '';
+  }
+
+  const hoverMap = {
+    primary: 'hover:bg-primary/5',
+    secondary: 'hover:bg-secondary/5',
+    accent: 'hover:bg-accent/10',
+    muted: 'hover:bg-muted/30'
+  };
+
+  return hoverMap[colorScheme] || hoverMap.primary;
+}
+
+/**
+ * Generate focus indicator classes based on focus style
+ */
+export function getFocusIndicator(focusStyle: FocusIndicatorStyle, colorScheme: SelectionColorScheme): string {
+  if (colorScheme === 'custom') {
+    return focusStyle === 'ring' 
+      ? 'ring-2 ring-[var(--tree-focus-ring)] ring-offset-1'
+      : 'border-l-2 border-[var(--tree-focus-border)]';
+  }
+
+  const focusMap = {
+    ring: {
+      primary: 'ring-2 ring-primary ring-offset-1',
+      secondary: 'ring-2 ring-secondary ring-offset-1',
+      accent: 'ring-2 ring-accent ring-offset-1',
+      muted: 'ring-2 ring-muted-foreground ring-offset-1'
+    },
+    outline: {
+      primary: 'outline-2 outline-primary',
+      secondary: 'outline-2 outline-secondary',
+      accent: 'outline-2 outline-accent',
+      muted: 'outline-2 outline-muted-foreground'
+    },
+    border: {
+      primary: 'border-l-2 border-primary',
+      secondary: 'border-l-2 border-secondary',
+      accent: 'border-l-2 border-accent',
+      muted: 'border-l-2 border-muted-foreground'
+    },
+    underline: {
+      primary: 'border-b-2 border-primary',
+      secondary: 'border-b-2 border-secondary',
+      accent: 'border-b-2 border-accent',
+      muted: 'border-b-2 border-muted-foreground'
+    }
+  };
+
+  return focusMap[focusStyle]?.[colorScheme] || focusMap.ring.primary;
+}
+
+/**
+ * Generate complete selection classes for a tree node
+ */
+export function getSelectionClasses(
+  theme: TreeSelectionTheme,
+  isSelected: boolean,
+  isFocused: boolean,
+  useCheckboxes: boolean = false
+): string {
+  const baseClasses = [
+    'transition-colors',
+    theme.animated ? 'duration-150' : '',
+    getHoverBackground(theme.colorScheme)
+  ];
+
+  if (isSelected) {
+    baseClasses.push(getSelectionBackground(theme.colorScheme, theme.intensity));
+  }
+
+  if (isFocused && !useCheckboxes) {
+    baseClasses.push(getFocusIndicator(theme.focusStyle, theme.colorScheme));
+  }
+
+  return cn(baseClasses);
+}
+
+
+
+/**
+ * Generate CSS custom properties for custom color schemes
+ * NOTE: This function is now simplified since we handle custom colors with inline styles
+ */
+export function getCustomColorVariables(theme: TreeSelectionTheme): Record<string, string> {
+  // Return empty object since we now handle custom colors with inline styles
+  // This avoids TypeScript issues with potentially undefined color properties
+  return {};
+} 

package/src/tree/utils/logger.ts

@@ -0,0 +1,203 @@
+interface LogContext {
+  component?: string;
+  nodeId?: string;
+  operation?: string;
+  [key: string]: any;
+}
+
+interface LogEntry {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  context?: LogContext;
+  data?: any;
+}
+
+class TreeLogger {
+  private isEnabled = true;
+  private logs: LogEntry[] = [];
+  private maxLogs = 1000;
+
+  enable() {
+    this.isEnabled = true;
+    console.log('🌳 TreeComponent logging enabled');
+  }
+
+  disable() {
+    this.isEnabled = false;
+    console.log('🌳 TreeComponent logging disabled');
+  }
+
+  private log(level: LogEntry['level'], message: string, context?: LogContext, data?: any) {
+    if (!this.isEnabled) return;
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      context,
+      data
+    };
+
+    // Store log entry
+    this.logs.push(entry);
+    if (this.logs.length > this.maxLogs) {
+      this.logs.shift();
+    }
+
+    // Format console output
+    const prefix = this.getPrefix(level);
+    const contextStr = context ? this.formatContext(context) : '';
+    const fullMessage = `${prefix} ${message}${contextStr}`;
+
+    // Console output with appropriate level
+    switch (level) {
+      case 'debug':
+        console.debug(fullMessage, data || '');
+        break;
+      case 'info':
+        console.info(fullMessage, data || '');
+        break;
+      case 'warn':
+        console.warn(fullMessage, data || '');
+        break;
+      case 'error':
+        console.error(fullMessage, data || '');
+        break;
+    }
+  }
+
+  private getPrefix(level: LogEntry['level']): string {
+    const timestamp = new Date().toLocaleTimeString();
+    switch (level) {
+      case 'debug': return `🔍 [${timestamp}] TreeComponent:`;
+      case 'info': return `ℹ️  [${timestamp}] TreeComponent:`;
+      case 'warn': return `⚠️  [${timestamp}] TreeComponent:`;
+      case 'error': return `❌ [${timestamp}] TreeComponent:`;
+    }
+  }
+
+  private formatContext(context: LogContext): string {
+    const parts: string[] = [];
+    
+    if (context.component) parts.push(`[${context.component}]`);
+    if (context.nodeId) parts.push(`(node: ${context.nodeId})`);
+    if (context.operation) parts.push(`{${context.operation}}`);
+    
+    // Add other context properties
+    Object.entries(context).forEach(([key, value]) => {
+      if (!['component', 'nodeId', 'operation'].includes(key)) {
+        parts.push(`${key}=${value}`);
+      }
+    });
+
+    return parts.length > 0 ? ` ${parts.join(' ')}` : '';
+  }
+
+  debug(message: string, context?: LogContext, data?: any) {
+    this.log('debug', message, context, data);
+  }
+
+  info(message: string, context?: LogContext, data?: any) {
+    this.log('info', message, context, data);
+  }
+
+  warn(message: string, context?: LogContext, data?: any) {
+    this.log('warn', message, context, data);
+  }
+
+  error(message: string, context?: LogContext, data?: any) {
+    this.log('error', message, context, data);
+  }
+
+  // Specialized logging methods for common TreeComponent operations
+  selection(operation: string, nodeId: string, data?: any) {
+    this.debug(`Selection ${operation}`, { 
+      component: 'Selection', 
+      nodeId, 
+      operation 
+    }, data);
+  }
+
+  expansion(operation: string, nodeId: string, data?: any) {
+    this.debug(`Expansion ${operation}`, { 
+      component: 'Expansion', 
+      nodeId, 
+      operation 
+    }, data);
+  }
+
+  interaction(operation: string, nodeId: string, data?: any) {
+    this.debug(`User interaction: ${operation}`, { 
+      component: 'Interaction', 
+      nodeId, 
+      operation 
+    }, data);
+  }
+
+  rendering(component: string, nodeId: string, data?: any) {
+    this.debug(`Rendering`, { 
+      component, 
+      nodeId, 
+      operation: 'render' 
+    }, data);
+  }
+
+  cssClasses(nodeId: string, classes: string, selected: boolean, focused: boolean) {
+    this.debug(`CSS classes applied`, { 
+      component: 'Styling', 
+      nodeId,
+      selected: selected.toString(),
+      focused: focused.toString()
+    }, { classes });
+  }
+
+  providerCall(method: string, data?: any) {
+    this.debug(`Provider method called`, { 
+      component: 'Provider', 
+      operation: method 
+    }, data);
+  }
+
+  stateChange(component: string, property: string, oldValue: any, newValue: any) {
+    this.debug(`State change`, { 
+      component, 
+      operation: 'state-change',
+      property 
+    }, { oldValue, newValue });
+  }
+
+  // Get logs for debugging
+  getLogs(filter?: { level?: LogEntry['level'], component?: string }): LogEntry[] {
+    if (!filter) return [...this.logs];
+    
+    return this.logs.filter(log => {
+      if (filter.level && log.level !== filter.level) return false;
+      if (filter.component && log.context?.component !== filter.component) return false;
+      return true;
+    });
+  }
+
+  // Clear logs
+  clearLogs() {
+    this.logs = [];
+    console.log('🌳 TreeComponent logs cleared');
+  }
+
+  // Export logs for analysis
+  exportLogs(): string {
+    return JSON.stringify(this.logs, null, 2);
+  }
+}
+
+// Global logger instance
+export const logger = new TreeLogger();
+
+// Enable by default in development
+if (typeof window !== 'undefined' && process.env.NODE_ENV === 'development') {
+  logger.enable();
+  // Make logger available globally for debugging
+  (window as any).treeLogger = logger;
+}
+
+export type { LogContext, LogEntry }; 

package/src/types-common.ts

@@ -0,0 +1,21 @@
+export type ObjectType = 'media' | 'contact' | 'calendar-event';
+
+export interface ObjectMetadata {
+  id: string;
+  type: ObjectType;
+  title: string;
+  description?: string;
+  thumbnail?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  tags?: string[];
+}
+
+export interface IObjectProvider<T extends ObjectMetadata> {
+  listItems(): Promise<T[]>;
+  getItem(id: string): Promise<T | null>;
+  createItem(item: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T>;
+  updateItem(id: string, updates: Partial<T>): Promise<T>;
+  deleteItem(id: string): Promise<void>;
+  search(query: string): Promise<T[]>;
+}