@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/extensions/flow/factories/builders/EdgeBuilder.ts

@@ -0,0 +1,185 @@
+/**
+ * Edge Builder
+ * 
+ * Builder pattern for fluent edge construction.
+ */
+
+import type { Edge, MarkerType } from '@xyflow/react';
+import type { FlowEdgeData, EdgeCustomization } from '../../organisms/FlowTypes';
+import { EdgeFactory } from '../../utils/edgeFactory';
+
+/**
+ * Edge Builder
+ * 
+ * Fluent builder for creating edges with method chaining.
+ */
+export class EdgeBuilder<T extends FlowEdgeData = FlowEdgeData> {
+  private id?: string;
+  private source: string;
+  private target: string;
+  private type: string;
+  private sourceHandle?: string;
+  private targetHandle?: string;
+  private data: Partial<T>;
+  private customization?: EdgeCustomization;
+  private animated?: boolean;
+  private selected?: boolean;
+  private hidden?: boolean;
+  private deletable?: boolean;
+  private focusable?: boolean;
+  private selectable?: boolean;
+  private zIndex?: number;
+  private markerStart?: { type: MarkerType; color?: string; width?: number; height?: number };
+  private markerEnd?: { type: MarkerType; color?: string; width?: number; height?: number };
+  private style?: React.CSSProperties;
+  private className?: string;
+  private label?: string | React.ReactNode;
+  private labelStyle?: React.CSSProperties;
+  private labelBgStyle?: React.CSSProperties;
+  private labelBgPadding?: [number, number];
+  private labelBgBorderRadius?: number;
+  private labelShowBg?: boolean;
+
+  constructor(source: string, target: string) {
+    this.source = source;
+    this.target = target;
+    this.type = 'default';
+    this.data = {};
+  }
+
+  withId(id: string): this {
+    this.id = id;
+    return this;
+  }
+
+  withType(type: string): this {
+    this.type = type;
+    return this;
+  }
+
+  withHandles(sourceHandle?: string, targetHandle?: string): this {
+    this.sourceHandle = sourceHandle;
+    this.targetHandle = targetHandle;
+    return this;
+  }
+
+  withData(data: Partial<T>): this {
+    this.data = { ...this.data, ...data };
+    return this;
+  }
+
+  withLabel(label: string | React.ReactNode): this {
+    this.label = label;
+    this.data.label = label as unknown;
+    return this;
+  }
+
+  withLabelStyle(style: React.CSSProperties): this {
+    this.labelStyle = style;
+    return this;
+  }
+
+  withLabelBackground(options: {
+    style?: React.CSSProperties;
+    padding?: [number, number];
+    borderRadius?: number;
+    show?: boolean;
+  }): this {
+    if (options.style) this.labelBgStyle = options.style;
+    if (options.padding) this.labelBgPadding = options.padding;
+    if (options.borderRadius) this.labelBgBorderRadius = options.borderRadius;
+    if (options.show !== undefined) this.labelShowBg = options.show;
+    return this;
+  }
+
+  withAnimated(animated: boolean = true): this {
+    this.animated = animated;
+    this.data.animated = animated as unknown;
+    return this;
+  }
+
+  withStyle(style: React.CSSProperties): this {
+    this.style = style;
+    return this;
+  }
+
+  withClassName(className: string): this {
+    this.className = className;
+    return this;
+  }
+
+  withMarkerStart(type: MarkerType, options?: { color?: string; width?: number; height?: number }): this {
+    this.markerStart = { type, ...options };
+    return this;
+  }
+
+  withMarkerEnd(type: MarkerType, options?: { color?: string; width?: number; height?: number }): this {
+    this.markerEnd = { type, ...options };
+    return this;
+  }
+
+  withCustomization(customization: EdgeCustomization): this {
+    this.customization = customization;
+    return this;
+  }
+
+  withSelection(selected: boolean): this {
+    this.selected = selected;
+    return this;
+  }
+
+  withInteractivity(options: {
+    selectable?: boolean;
+    deletable?: boolean;
+    focusable?: boolean;
+  }): this {
+    if (options.selectable !== undefined) this.selectable = options.selectable;
+    if (options.deletable !== undefined) this.deletable = options.deletable;
+    if (options.focusable !== undefined) this.focusable = options.focusable;
+    return this;
+  }
+
+  withVisibility(hidden: boolean): this {
+    this.hidden = hidden;
+    return this;
+  }
+
+  withZIndex(zIndex: number): this {
+    this.zIndex = zIndex;
+    return this;
+  }
+
+  build(): Edge<T> {
+    const edge = EdgeFactory.create<T>(
+      this.source,
+      this.target,
+      this.id,
+      this.type,
+      this.data as T,
+      this.customization
+    );
+
+    // Add additional properties
+    if (this.sourceHandle !== undefined) edge.sourceHandle = this.sourceHandle;
+    if (this.targetHandle !== undefined) edge.targetHandle = this.targetHandle;
+    if (this.animated !== undefined) edge.animated = this.animated;
+    if (this.selected !== undefined) edge.selected = this.selected;
+    if (this.hidden !== undefined) edge.hidden = this.hidden;
+    if (this.deletable !== undefined) edge.deletable = this.deletable;
+    if (this.focusable !== undefined) edge.focusable = this.focusable;
+    if (this.selectable !== undefined) edge.selectable = this.selectable;
+    if (this.zIndex !== undefined) edge.zIndex = this.zIndex;
+    if (this.markerStart !== undefined) edge.markerStart = this.markerStart;
+    if (this.markerEnd !== undefined) edge.markerEnd = this.markerEnd;
+    if (this.style !== undefined) edge.style = this.style;
+    if (this.className !== undefined) edge.className = this.className;
+    if (this.label !== undefined) edge.label = this.label;
+    if (this.labelStyle !== undefined) edge.labelStyle = this.labelStyle;
+    if (this.labelBgStyle !== undefined) edge.labelBgStyle = this.labelBgStyle;
+    if (this.labelBgPadding !== undefined) edge.labelBgPadding = this.labelBgPadding;
+    if (this.labelBgBorderRadius !== undefined) edge.labelBgBorderRadius = this.labelBgBorderRadius;
+    if (this.labelShowBg !== undefined) edge.labelShowBg = this.labelShowBg;
+
+    return edge;
+  }
+}

package/src/ui/extensions/flow/factories/builders/NodeBuilder.ts

@@ -0,0 +1,172 @@
+/**
+ * Node Builder
+ * 
+ * Builder pattern for fluent node construction.
+ */
+
+import type { Node, XYPosition, Position } from '@xyflow/react';
+import type { FlowNodeData, NodeCustomization } from '../../organisms/FlowTypes';
+import { NodeFactory } from '../../utils/nodeFactory';
+
+/**
+ * Node Builder
+ * 
+ * Fluent builder for creating nodes with method chaining.
+ */
+export class NodeBuilder<T extends FlowNodeData = FlowNodeData> {
+  private id: string;
+  private type: string;
+  private position: XYPosition;
+  private data: Partial<T>;
+  private customization?: NodeCustomization;
+  private width?: number;
+  private height?: number;
+  private parentId?: string;
+  private extent?: 'parent' | [number, number, number, number];
+  private expandParent?: boolean;
+  private selected?: boolean;
+  private draggable?: boolean;
+  private selectable?: boolean;
+  private connectable?: boolean;
+  private deletable?: boolean;
+  private focusable?: boolean;
+  private hidden?: boolean;
+  private zIndex?: number;
+  private sourcePosition?: Position;
+  private targetPosition?: Position;
+
+  constructor(id?: string) {
+    this.id = id || `node-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.type = 'default';
+    this.position = { x: 0, y: 0 };
+    this.data = {};
+  }
+
+  withId(id: string): this {
+    this.id = id;
+    return this;
+  }
+
+  withType(type: string): this {
+    this.type = type;
+    return this;
+  }
+
+  withPosition(position: XYPosition): this {
+    this.position = position;
+    return this;
+  }
+
+  withData(data: Partial<T>): this {
+    this.data = { ...this.data, ...data };
+    return this;
+  }
+
+  withLabel(label: string): this {
+    this.data.label = label as unknown;
+    return this;
+  }
+
+  withDescription(description: string): this {
+    this.data.description = description as unknown;
+    return this;
+  }
+
+  withVariant(variant: FlowNodeData['variant']): this {
+    this.data.variant = variant as unknown;
+    return this;
+  }
+
+  withSize(size: FlowNodeData['size']): this {
+    this.data.size = size as unknown;
+    return this;
+  }
+
+  withIcon(icon: React.ReactNode): this {
+    this.data.icon = icon as unknown;
+    return this;
+  }
+
+  withCustomization(customization: NodeCustomization): this {
+    this.customization = customization;
+    return this;
+  }
+
+  withDimensions(width: number, height: number): this {
+    this.width = width;
+    this.height = height;
+    return this;
+  }
+
+  withParent(parentId: string, options?: { extent?: 'parent' | [number, number, number, number]; expandParent?: boolean }): this {
+    this.parentId = parentId;
+    if (options?.extent) this.extent = options.extent;
+    if (options?.expandParent !== undefined) this.expandParent = options.expandParent;
+    return this;
+  }
+
+  withSelection(selected: boolean): this {
+    this.selected = selected;
+    return this;
+  }
+
+  withInteractivity(options: {
+    draggable?: boolean;
+    selectable?: boolean;
+    connectable?: boolean;
+    deletable?: boolean;
+    focusable?: boolean;
+  }): this {
+    if (options.draggable !== undefined) this.draggable = options.draggable;
+    if (options.selectable !== undefined) this.selectable = options.selectable;
+    if (options.connectable !== undefined) this.connectable = options.connectable;
+    if (options.deletable !== undefined) this.deletable = options.deletable;
+    if (options.focusable !== undefined) this.focusable = options.focusable;
+    return this;
+  }
+
+  withVisibility(hidden: boolean): this {
+    this.hidden = hidden;
+    return this;
+  }
+
+  withZIndex(zIndex: number): this {
+    this.zIndex = zIndex;
+    return this;
+  }
+
+  withHandlePositions(sourcePosition?: Position, targetPosition?: Position): this {
+    this.sourcePosition = sourcePosition;
+    this.targetPosition = targetPosition;
+    return this;
+  }
+
+  build(): Node<T> {
+    const node = NodeFactory.create<T>(
+      this.type,
+      this.id,
+      this.position,
+      this.data as T,
+      this.customization
+    );
+
+    // Add additional properties
+    if (this.width !== undefined) node.width = this.width;
+    if (this.height !== undefined) node.height = this.height;
+    if (this.parentId !== undefined) node.parentId = this.parentId;
+    if (this.extent !== undefined) node.extent = this.extent;
+    if (this.expandParent !== undefined) node.expandParent = this.expandParent;
+    if (this.selected !== undefined) node.selected = this.selected;
+    if (this.draggable !== undefined) node.draggable = this.draggable;
+    if (this.selectable !== undefined) node.selectable = this.selectable;
+    if (this.connectable !== undefined) node.connectable = this.connectable;
+    if (this.deletable !== undefined) node.deletable = this.deletable;
+    if (this.focusable !== undefined) node.focusable = this.focusable;
+    if (this.hidden !== undefined) node.hidden = this.hidden;
+    if (this.zIndex !== undefined) node.zIndex = this.zIndex;
+    if (this.sourcePosition !== undefined) node.sourcePosition = this.sourcePosition;
+    if (this.targetPosition !== undefined) node.targetPosition = this.targetPosition;
+
+    return node;
+  }
+}

package/src/ui/extensions/flow/factories/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Flow Factories
+ * 
+ * Factory pattern implementations for Flow components.
+ */
+
+export { NodeFactory } from '../utils/nodeFactory';
+export { EdgeFactory } from '../utils/edgeFactory';
+export { FlowFactory } from './FlowFactory';
+export { NodeBuilder } from './builders/NodeBuilder';
+export { EdgeBuilder } from './builders/EdgeBuilder';
+export type { NodeTemplate } from '../utils/nodeFactory';
+export type { EdgeTemplate } from '../utils/edgeFactory';

package/src/ui/extensions/flow/hooks/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Flow Hooks
+ * 
+ * Custom hooks for Flow components.
+ */
+
+export { useFlowState } from './useFlowState';
+export { useFlowActions } from './useFlowActions';
+export { useNodeSelection } from './useNodeSelection';
+export { useFlowStyles, useFlowStylesOptional } from './useFlowStyles';
+export { useFlowPerformance } from './useFlowPerformance';
+export { useFlowEvents } from './useFlowEvents';
+export { useFlowUtils } from './useFlowUtils';
+export { useFlowSelection } from './useFlowSelection';
+export { useFlowViewport } from './useFlowViewport';
+export type { UseFlowStylesReturn } from './useFlowStyles';
+export type { UseFlowPerformanceReturn } from './useFlowPerformance';
+export type { UseFlowEventsReturn } from './useFlowEvents';
+export type { UseFlowUtilsReturn } from './useFlowUtils';
+export type { UseFlowSelectionReturn } from './useFlowSelection';
+export type { UseFlowViewportReturn } from './useFlowViewport';
+export { useFlowValidation } from './useFlowValidation';
+export { useAutoLayout } from './useAutoLayout';
+export { useFlowVirtualization } from './useFlowVirtualization';
+export { usePlaygroundHistory } from './usePlaygroundHistory';
+export type { UsePlaygroundHistoryReturn, HistoryState } from './usePlaygroundHistory';
+export { useKeyboardShortcuts, PLAYGROUND_SHORTCUTS } from './useKeyboardShortcuts';
+export type { KeyboardShortcut, UseKeyboardShortcutsOptions } from './useKeyboardShortcuts';
+export { usePlaygroundKeyboardNavigation } from './usePlaygroundKeyboardNavigation';
+export type { PlaygroundKeyboardNavigationOptions } from './usePlaygroundKeyboardNavigation';

package/src/ui/extensions/flow/hooks/useAutoLayout.ts

@@ -0,0 +1,49 @@
+'use client';
+
+/**
+ * useAutoLayout Hook
+ * 
+ * Hook for applying automatic layouts to flows.
+ */
+
+import { useCallback } from 'react';
+import { useReactFlow } from '@xyflow/react';
+import type { Node, Edge } from '@xyflow/react';
+import { layoutEngine } from '../utils/layoutEngine';
+import type { LayoutStrategyName, LayoutOptions, LayoutResult } from '../organisms/FlowTypes';
+
+/**
+ * Hook for automatic layout
+ * 
+ * Provides methods to apply layouts automatically.
+ */
+export function useAutoLayout(strategy: LayoutStrategyName = 'dagre') {
+  const { getNodes, getEdges, setNodes, setEdges } = useReactFlow();
+  
+  const applyLayout = useCallback(async (
+    customNodes?: Node[],
+    customEdges?: Edge[],
+    options?: LayoutOptions
+  ): Promise<LayoutResult> => {
+    const nodes = customNodes || getNodes();
+    const edges = customEdges || getEdges();
+    
+    const result = await layoutEngine.calculate(strategy, nodes, edges, options);
+    
+    // Apply layout to flow
+    setNodes(result.nodes);
+    setEdges(result.edges);
+    
+    return result;
+  }, [strategy, getNodes, getEdges, setNodes, setEdges]);
+  
+  const getAvailableStrategies = useCallback(() => {
+    return layoutEngine.getAvailableStrategies();
+  }, []);
+  
+  return {
+    applyLayout,
+    getAvailableStrategies,
+    currentStrategy: strategy,
+  };
+}

package/src/ui/extensions/flow/hooks/useFlowActions.ts

@@ -0,0 +1,71 @@
+'use client';
+
+/**
+ * useFlowActions Hook
+ * 
+ * Hook that uses React Flow's useReactFlow to provide actions.
+ */
+
+import { useReactFlow } from '@xyflow/react';
+import type { FitViewOptions, ReactFlowJsonObject } from '@xyflow/react';
+
+/**
+ * Hook for flow actions
+ * 
+ * Provides actions for manipulating the flow (zoom, pan, fit view, etc.)
+ */
+export function useFlowActions() {
+  const reactFlowInstance = useReactFlow();
+  
+  return {
+    // Viewport actions
+    fitView: (options?: FitViewOptions) => {
+      reactFlowInstance.fitView(options);
+    },
+    zoomIn: () => {
+      reactFlowInstance.zoomIn();
+    },
+    zoomOut: () => {
+      reactFlowInstance.zoomOut();
+    },
+    zoomTo: (zoomLevel: number) => {
+      reactFlowInstance.setZoom(zoomLevel);
+    },
+    panTo: (x: number, y: number) => {
+      reactFlowInstance.setCenter(x, y);
+    },
+    
+    // Get viewport
+    getViewport: () => {
+      return reactFlowInstance.getViewport();
+    },
+    
+    // Export/Import
+    exportToJSON: (): ReactFlowJsonObject => {
+      return reactFlowInstance.toObject();
+    },
+    importFromJSON: (json: ReactFlowJsonObject) => {
+      const { x = 0, y = 0, zoom = 1 } = json.viewport || {};
+      reactFlowInstance.setNodes(json.nodes || []);
+      reactFlowInstance.setEdges(json.edges || []);
+      reactFlowInstance.setViewport({ x, y, zoom });
+    },
+    
+    // Node/Edge queries
+    getNode: (nodeId: string) => {
+      return reactFlowInstance.getNode(nodeId);
+    },
+    getNodes: () => {
+      return reactFlowInstance.getNodes();
+    },
+    getEdge: (edgeId: string) => {
+      return reactFlowInstance.getEdges().find((e) => e.id === edgeId);
+    },
+    getEdges: () => {
+      return reactFlowInstance.getEdges();
+    },
+    
+    // React Flow instance (for advanced usage)
+    reactFlowInstance,
+  };
+}

package/src/ui/extensions/flow/hooks/useFlowEvents.ts

@@ -0,0 +1,82 @@
+'use client';
+
+/**
+ * useFlowEvents Hook
+ * 
+ * Hook for subscribing to and emitting Flow events.
+ */
+
+import { useFlowEventContext } from '../context/FlowEventContext';
+import type { FlowEventType, FlowEvent, FlowEventHandler } from '../context/FlowEventContext';
+
+/**
+ * Flow Events Hook Return
+ */
+export interface UseFlowEventsReturn {
+  // Event bus operations
+  subscribe: <T = unknown>(eventType: FlowEventType, handler: FlowEventHandler<T>) => { unsubscribe: () => void };
+  unsubscribe: (eventType: FlowEventType, handler: FlowEventHandler) => void;
+  emit: <T = unknown>(eventType: FlowEventType, payload: T, source?: string) => void;
+  
+  // Event filtering
+  once: <T = unknown>(eventType: FlowEventType, handler: FlowEventHandler<T>) => { unsubscribe: () => void };
+  filter: <T = unknown>(
+    eventType: FlowEventType,
+    predicate: (event: FlowEvent<T>) => boolean,
+    handler: FlowEventHandler<T>
+  ) => { unsubscribe: () => void };
+  
+  // Event history
+  getHistory: (eventType?: FlowEventType, limit?: number) => FlowEvent[];
+  clearHistory: () => void;
+  
+  // Convenience methods
+  onNodeAdd: (handler: FlowEventHandler<Node>) => { unsubscribe: () => void };
+  onNodeRemove: (handler: FlowEventHandler<string>) => { unsubscribe: () => void };
+  onNodeUpdate: (handler: FlowEventHandler<{ nodeId: string; data: unknown }>) => { unsubscribe: () => void };
+  onEdgeAdd: (handler: FlowEventHandler<Edge>) => { unsubscribe: () => void };
+  onEdgeRemove: (handler: FlowEventHandler<string>) => { unsubscribe: () => void };
+  onSelectionChange: (handler: FlowEventHandler<{ nodes: Node[]; edges: Edge[] }>) => { unsubscribe: () => void };
+}
+
+/**
+ * Hook for subscribing to and emitting Flow events
+ */
+export function useFlowEvents(): UseFlowEventsReturn {
+  const context = useFlowEventContext();
+  
+  // Convenience methods for common events
+  const onNodeAdd = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('node:add', handler);
+  };
+  
+  const onNodeRemove = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('node:remove', handler);
+  };
+  
+  const onNodeUpdate = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('node:update', handler);
+  };
+  
+  const onEdgeAdd = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('edge:add', handler);
+  };
+  
+  const onEdgeRemove = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('edge:remove', handler);
+  };
+  
+  const onSelectionChange = (handler: FlowEventHandler<unknown>) => {
+    return context.subscribe('selection:change', handler);
+  };
+  
+  return {
+    ...context,
+    onNodeAdd,
+    onNodeRemove,
+    onNodeUpdate,
+    onEdgeAdd,
+    onEdgeRemove,
+    onSelectionChange,
+  };
+}

package/src/ui/extensions/flow/hooks/useFlowPerformance.ts

@@ -0,0 +1,101 @@
+'use client';
+
+/**
+ * useFlowPerformance Hook
+ * 
+ * Hook for monitoring and optimizing Flow performance.
+ */
+
+import { useFlowPerformanceContext } from '../context/FlowPerformanceContext';
+import type { PerformanceMetrics, PerformanceOptions } from '../context/FlowPerformanceContext';
+
+/**
+ * Flow Performance Hook Return
+ */
+export interface UseFlowPerformanceReturn {
+  // Metrics
+  metrics: PerformanceMetrics;
+  updateMetrics: (metrics: Partial<PerformanceMetrics>) => void;
+  
+  // Performance state
+  isOptimized: boolean;
+  optimizations: {
+    virtualization: boolean;
+    memoization: boolean;
+    lazyLoading: boolean;
+  };
+  
+  // Operations
+  optimize: () => void;
+  resetOptimizations: () => void;
+  
+  // Monitoring
+  startMonitoring: () => void;
+  stopMonitoring: () => void;
+  isMonitoring: boolean;
+  
+  // Options
+  options: PerformanceOptions;
+  setOptions: (options: Partial<PerformanceOptions>) => void;
+  
+  // Convenience methods
+  shouldVirtualize: () => boolean;
+  shouldLazyLoad: () => boolean;
+  getPerformanceScore: () => number; // 0-100
+}
+
+/**
+ * Hook for monitoring and optimizing Flow performance
+ */
+export function useFlowPerformance(): UseFlowPerformanceReturn {
+  const context = useFlowPerformanceContext();
+  
+  // Convenience methods
+  const shouldVirtualize = (): boolean => {
+    return context.optimizations.virtualization;
+  };
+  
+  const shouldLazyLoad = (): boolean => {
+    return context.optimizations.lazyLoading;
+  };
+  
+  const getPerformanceScore = (): number => {
+    // Calculate performance score based on metrics
+    let score = 100;
+    
+    // Penalize for high render time
+    if (context.metrics.renderTime > 100) {
+      score -= 20;
+    } else if (context.metrics.renderTime > 50) {
+      score -= 10;
+    }
+    
+    // Penalize for high node/edge count
+    if (context.metrics.nodeCount > (context.options.maxNodes || 1000)) {
+      score -= 30;
+    } else if (context.metrics.nodeCount > (context.options.maxNodes || 1000) * 0.8) {
+      score -= 15;
+    }
+    
+    // Penalize for high memory usage
+    if (context.metrics.memoryUsage && context.metrics.memoryUsage > 100) {
+      score -= 20;
+    }
+    
+    // Penalize for low frame rate
+    if (context.metrics.frameRate && context.metrics.frameRate < 30) {
+      score -= 30;
+    } else if (context.metrics.frameRate && context.metrics.frameRate < 45) {
+      score -= 15;
+    }
+    
+    return Math.max(0, Math.min(100, score));
+  };
+  
+  return {
+    ...context,
+    shouldVirtualize,
+    shouldLazyLoad,
+    getPerformanceScore,
+  };
+}