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

package/src/ui/extensions/flow/organisms/Flow.mdx

@@ -0,0 +1,169 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import { FlowCanvas } from './FlowCanvas';
+import { FlowProvider } from './FlowProvider';
+import { FlowHandle } from '../atoms/FlowHandle';
+import { FlowNodeWrapper } from '../atoms/FlowNodeWrapper';
+import { CustomNode } from '../molecules/CustomNode';
+import { CustomEdge } from '../molecules/CustomEdge';
+import { FlowNodeToolbar } from '../molecules/FlowNodeToolbar';
+import { FlowControls } from './FlowControls';
+import { FlowMinimap } from './FlowMinimap';
+import { FlowBackground } from './FlowBackground';
+import { FlowPanel } from './FlowPanel';
+
+<Meta title="Extensions/Flow" />
+
+# Flow Components
+
+A comprehensive flow diagram system built on top of React Flow (@xyflow/react) with design system integration.
+
+## Overview
+
+The Flow system provides a complete solution for building interactive flow diagrams with:
+
+- **FlowProvider**: Context provider that combines ReactFlowProvider with design system functionality
+- **FlowCanvas**: Compound component for rendering flows with sub-components
+- **Custom Nodes & Edges**: Pre-built components following design system patterns
+- **Layout Engines**: Support for Dagre, ELK, and Force-Directed layouts (optional)
+- **Validation**: Connection rules and flow validation
+- **Theming**: Full support for light/dark themes
+- **Performance**: Memoization, virtualization, and optimization
+
+## Architecture
+
+The Flow system follows Atomic Design principles:
+
+- **Atoms**: `FlowHandle`, `FlowNodeWrapper` - Basic building blocks
+- **Molecules**: `CustomNode`, `CustomEdge`, `FlowNodeToolbar`, `FlowNodeContent` - Composed components
+- **Organisms**: `FlowCanvas`, `FlowProvider` - Complex components with compound patterns
+
+## Basic Usage
+
+```tsx
+import { FlowCanvas, FlowProvider } from '@fabio.caffarello/react-design-system';
+import { useNodesState, useEdgesState } from '@xyflow/react';
+
+function MyFlow() {
+  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
+  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);
+  
+  return (
+    <FlowProvider
+      nodes={nodes}
+      edges={edges}
+      onNodesChange={onNodesChange}
+      onEdgesChange={onEdgesChange}
+    >
+      <FlowCanvas.Root>
+        <FlowCanvas.Background />
+        <FlowCanvas.Controls />
+        <FlowCanvas.Minimap />
+      </FlowCanvas.Root>
+    </FlowProvider>
+  );
+}
+```
+
+## Components
+
+### FlowProvider
+
+Main provider that combines ReactFlowProvider with design system context. Supports both controlled and uncontrolled modes.
+
+### FlowCanvas
+
+Compound component with sub-components:
+- `FlowCanvas.Root` - Main canvas (wraps ReactFlow)
+- `FlowCanvas.Background` - Background pattern (dots, lines, cross)
+- `FlowCanvas.Controls` - Zoom/pan controls
+- `FlowCanvas.Minimap` - Minimap for navigation
+- `FlowCanvas.Panel` - Custom panels for UI overlays
+
+### Atoms
+
+- **FlowHandle**: Connection points for nodes with design system styling
+- **FlowNodeWrapper**: Styling wrapper for nodes with variants and sizes
+
+### Molecules
+
+- **CustomNode**: Default node component with design system integration
+- **CustomEdge**: Default edge component with animations and labels
+- **FlowNodeToolbar**: Toolbar for node actions
+- **FlowNodeContent**: Content wrapper with render props support
+
+## Customization
+
+Nodes and edges can be customized through 5 layers:
+
+1. **Variant and size props** - Quick styling
+2. **Custom components** - Replace default components
+3. **Render props** - Flexible content rendering
+4. **Slots** - Direct content injection
+5. **Theme overrides** - Advanced styling
+
+## Hooks
+
+- `useFlowState` - State management with React Flow hooks
+- `useFlowActions` - Actions for zoom, pan, fit view
+- `useNodeSelection` - Track selected nodes/edges
+- `useFlowValidation` - Validate flow with rules
+- `useAutoLayout` - Apply automatic layouts
+- `useFlowVirtualization` - Viewport-based rendering for large flows
+
+## Layout Engines
+
+Optional layout engines (install separately):
+- **Dagre**: Hierarchical layouts for directed graphs
+- **ELK**: Complex, configurable layouts
+- **Force-Directed**: Physical simulation layouts
+
+## Validation
+
+Connection rules and validation rules can be added to control flow behavior:
+
+```tsx
+import { FlowValidator } from '@fabio.caffarello/react-design-system';
+
+const validator = new FlowValidator();
+validator.addRule({
+  sourceType: 'input',
+  targetType: 'process',
+  allowed: true,
+  maxConnections: 1,
+});
+
+const isValidConnection = validator.createIsValidConnection(nodes, edges);
+```
+
+## Playground
+
+The **FlowPlayground** is the primary way to explore and interact with all Flow components. It provides a complete interactive environment where you can:
+
+- Create and edit flows in real-time
+- Configure all ReactFlow props
+- Customize nodes, edges, and backgrounds
+- Apply layout algorithms
+- Validate flows
+- Export code and share flows
+
+### Available Stories
+
+- **Interactive**: Complete playground with all features
+- **Getting Started**: Tutorial-friendly playground for beginners
+- **Customization**: Explore customization options for nodes and edges
+- **Layouts**: Experiment with different layout algorithms
+- **Validation**: Test flow validation and connection rules
+- **Advanced**: Advanced features (drag & drop, resizing, etc.)
+- **Examples**: Pre-configured templates and examples
+
+Access the playground in Storybook: `Extensions/Flow/FlowPlayground`
+
+## Examples
+
+All examples and demonstrations are available in the FlowPlayground. The playground provides interactive examples for:
+
+- Different node types (Default, Input, Output, Selector, Resizable)
+- Different edge types (Default, Smooth Step, Straight, Step, Floating)
+- Layout algorithms (Dagre, ELK, Force-Directed)
+- Customization options
+- Validation scenarios

package/src/ui/extensions/flow/organisms/FlowBackground.tsx

@@ -0,0 +1,182 @@
+'use client';
+
+import React, { useMemo } from 'react';
+import { Background, type BackgroundProps } from '@xyflow/react';
+import { useFlowContext } from './FlowContext';
+import { useFlowStylesOptional } from '../hooks/useFlowStyles';
+import { getCSSVariable } from '../utils/cssUtils';
+import styles from '../styles/modules/FlowBackground.module.css';
+
+/**
+ * FlowBackground Component
+ * 
+ * Wrapper for React Flow's Background component with design system integration.
+ * Uses CSS variables from React Flow (--xy-background-*) and integrates with
+ * FlowStyleContext for theming support.
+ * 
+ * @example
+ * ```tsx
+ * <FlowBackground variant="dots" size={2} />
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * <FlowBackground 
+ *   variant="lines" 
+ *   bgColor="#ffffff" 
+ *   patternColor="#e5e7eb" 
+ * />
+ * ```
+ */
+export interface FlowBackgroundProps extends Omit<BackgroundProps, 'bgColor' | 'patternColor'> {
+  /**
+   * Background pattern variant
+   * @default 'dots'
+   */
+  variant?: 'dots' | 'lines' | 'cross';
+  
+  /**
+   * Pattern size in pixels
+   * @default 2
+   */
+  size?: number;
+  
+  /**
+   * Custom background color (overrides CSS variable)
+   */
+  bgColor?: string;
+  
+  /**
+   * Custom pattern color (overrides CSS variable)
+   */
+  patternColor?: string;
+  
+  /**
+   * Additional CSS class name
+   */
+  className?: string;
+  
+  /**
+   * Inline styles
+   */
+  style?: React.CSSProperties;
+}
+
+/**
+ * Get CSS variable value with fallback
+ */
+function getBackgroundCSSVariable(
+  varName: string,
+  fallback: string,
+  customValue?: string
+): string {
+  // If custom value provided, use it
+  if (customValue) {
+    return customValue;
+  }
+  
+  // Try to get from computed styles
+  const value = getCSSVariable(varName);
+  if (value) {
+    return value;
+  }
+  
+  // Fallback to default
+  return fallback;
+}
+
+/**
+ * Get pattern color based on variant
+ */
+function getPatternColorForVariant(
+  variant: 'dots' | 'lines' | 'cross',
+  customPatternColor?: string,
+  flowStyles?: ReturnType<typeof useFlowStylesOptional>
+): string {
+  // If custom pattern color provided, use it
+  if (customPatternColor) {
+    return customPatternColor;
+  }
+  
+  // Try to get from FlowStyleContext
+  if (flowStyles) {
+    const varName = 
+      variant === 'dots' ? 'backgroundPatternDotsColor' :
+      variant === 'lines' ? 'backgroundPatternLinesColor' :
+      'backgroundPatternCrossColor';
+    
+    const themeValue = flowStyles.getVariable(varName);
+    if (themeValue) {
+      return themeValue;
+    }
+  }
+  
+  // Try CSS variables from React Flow
+  const cssVarName = 
+    variant === 'dots' ? '--xy-background-pattern-dots-color-default' :
+    variant === 'lines' ? '--xy-background-pattern-lines-color-default' :
+    '--xy-background-pattern-cross-color-default';
+  
+  const cssValue = getCSSVariable(cssVarName);
+  if (cssValue) {
+    return cssValue;
+  }
+  
+  // Fallback values
+  const fallbacks = {
+    dots: '#91919a',
+    lines: '#e5e7eb',
+    cross: '#e2e2e2',
+  };
+  
+  return fallbacks[variant];
+}
+
+export function FlowBackground({
+  variant = 'dots',
+  size = 2,
+  bgColor: customBgColor,
+  patternColor: customPatternColor,
+  className,
+  style,
+  ...props
+}: FlowBackgroundProps) {
+  const { theme } = useFlowContext();
+  const flowStyles = useFlowStylesOptional();
+  
+  // Get background color with fallback chain
+  const bgColor = useMemo(() => {
+    return getBackgroundCSSVariable(
+      '--xy-background-color-default',
+      theme === 'dark' ? '#141414' : 'transparent',
+      customBgColor
+    );
+  }, [customBgColor, theme, flowStyles]);
+  
+  // Get pattern color based on variant
+  const patternColor = useMemo(() => {
+    return getPatternColorForVariant(variant, customPatternColor, flowStyles);
+  }, [variant, customPatternColor, flowStyles]);
+  
+  // Combine className
+  const combinedClassName = useMemo(() => {
+    const classes = [styles.background];
+    if (className) {
+      classes.push(className);
+    }
+    return classes.join(' ');
+  }, [className]);
+  
+  return (
+    <div className={combinedClassName} style={style}>
+      <Background
+        {...props}
+        variant={variant}
+        size={size}
+        bgColor={bgColor}
+        patternColor={patternColor}
+        className={styles.pattern}
+      />
+    </div>
+  );
+}

package/src/ui/extensions/flow/organisms/FlowCanvas.test.tsx

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render } from '@testing-library/react';
+import { FlowCanvas } from './FlowCanvas';
+import { FlowProvider } from './FlowProvider';
+import type { Node } from '@xyflow/react';
+import type { FlowNodeData } from './FlowTypes';
+
+describe('FlowCanvas', () => {
+  const mockNodes: Node<FlowNodeData>[] = [
+    {
+      id: '1',
+      type: 'default',
+      position: { x: 0, y: 0 },
+      data: { label: 'Test' },
+    },
+  ];
+  const mockEdges: any[] = [];
+  
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  
+  it('renders FlowCanvas.Root', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowCanvas.Root />
+      </FlowProvider>
+    );
+    
+    // ReactFlow renders a div with class 'react-flow'
+    expect(container.querySelector('.react-flow')).toBeTruthy();
+  });
+  
+  it('renders with Background', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowCanvas.Root>
+          <FlowCanvas.Background />
+        </FlowCanvas.Root>
+      </FlowProvider>
+    );
+    
+    expect(container.querySelector('.react-flow__background')).toBeTruthy();
+  });
+  
+  it('renders with Controls', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowCanvas.Root>
+          <FlowCanvas.Controls />
+        </FlowCanvas.Root>
+      </FlowProvider>
+    );
+    
+    expect(container.querySelector('.react-flow__controls')).toBeTruthy();
+  });
+  
+  it('renders with Minimap', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowCanvas.Root>
+          <FlowCanvas.Minimap />
+        </FlowCanvas.Root>
+      </FlowProvider>
+    );
+    
+    expect(container.querySelector('.react-flow__minimap')).toBeTruthy();
+  });
+});

package/src/ui/extensions/flow/organisms/FlowCanvas.tsx

@@ -0,0 +1,193 @@
+'use client';
+
+import React, { useMemo, useCallback } from 'react';
+import { ReactFlow, type ReactFlowProps, type ReactFlowInstance, MarkerType } from '@xyflow/react';
+import { useFlowContext } from './FlowContext';
+import { NodeTypeRegistry } from '../utils/nodeTypes';
+import { EdgeTypeRegistry } from '../utils/edgeTypes';
+import { FlowBackground } from './FlowBackground';
+import { FlowControls } from './FlowControls';
+import { FlowMinimap } from './FlowMinimap';
+import { FlowPanel } from './FlowPanel';
+
+/**
+ * FlowCanvasRoot Component
+ * 
+ * Root component that wraps ReactFlow with design system integration.
+ * Single Responsibility: Render ReactFlow with design system configuration.
+ * 
+ * Features:
+ * - Memoized nodeTypes and edgeTypes for performance
+ * - Theme support
+ * - Prop filtering to prevent React warnings
+ */
+export interface FlowCanvasRootProps extends Omit<ReactFlowProps, 'nodes' | 'edges' | 'nodeTypes' | 'edgeTypes'> {
+  nodeTypes?: ReactFlowProps['nodeTypes'];
+  edgeTypes?: ReactFlowProps['edgeTypes'];
+  className?: string;
+  /**
+   * Custom connection line component
+   */
+  connectionLineComponent?: ReactFlowProps['connectionLineComponent'];
+  /**
+   * Default edge options (applied to all new edges)
+   */
+  defaultEdgeOptions?: ReactFlowProps['defaultEdgeOptions'];
+  /**
+   * Node origin for better positioning (default: [0, 0])
+   */
+  nodeOrigin?: [number, number];
+  /**
+   * Enable snap to grid
+   */
+  snapToGrid?: boolean;
+  /**
+   * Grid size for snapping [x, y]
+   */
+  snapGrid?: [number, number];
+  /**
+   * Only render visible elements for performance (useful for large flows)
+   * @default true
+   */
+  onlyRenderVisibleElements?: boolean;
+}
+
+export const FlowCanvasRoot = React.memo(function FlowCanvasRoot({
+  nodeTypes,
+  edgeTypes,
+  className = '',
+  children,
+  connectionLineComponent,
+  defaultEdgeOptions,
+  nodeOrigin = [0, 0],
+  snapToGrid = false,
+  snapGrid = [16, 16],
+  onlyRenderVisibleElements = true, // Default to true for better performance
+  ...props
+}: FlowCanvasRootProps) {
+  const {
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange,
+    onConnect,
+    setReactFlowInstance,
+    theme,
+  } = useFlowContext();
+  
+  // Memoize nodeTypes and edgeTypes to prevent unnecessary re-renders
+  // Merge provided nodeTypes with registry defaults
+  const finalNodeTypes = useMemo(() => {
+    try {
+      const registryTypes = NodeTypeRegistry.getAll();
+      return nodeTypes ? { ...registryTypes, ...nodeTypes } : registryTypes;
+    } catch (error) {
+      console.error('Error getting node types:', error);
+      return nodeTypes || {};
+    }
+  }, [nodeTypes]);
+
+  const finalEdgeTypes = useMemo(() => {
+    try {
+      return edgeTypes || EdgeTypeRegistry.getAll();
+    } catch (error) {
+      console.error('Error getting edge types:', error);
+      return {};
+    }
+  }, [edgeTypes]);
+  
+  // Memoize default edge options
+  const memoizedDefaultEdgeOptions = useMemo(() => {
+    return defaultEdgeOptions || {
+      type: 'default',
+      animated: false,
+      markerEnd: {
+        type: MarkerType.ArrowClosed,
+      },
+    };
+  }, [defaultEdgeOptions]);
+  
+  // Memoize theme-based classes
+  const canvasClasses = useMemo(() => {
+    return `
+      ${theme === 'dark' ? 'bg-gray-900' : 'bg-white'}
+      ${className}
+    `.trim().replace(/\s+/g, ' ');
+  }, [theme, className]);
+
+  // Filter out any invalid props that might cause React warnings
+  // ReactFlow should handle all valid ReactFlowProps, but we ensure
+  // no unexpected props are passed
+  const {
+    // Extract any props that ReactFlow doesn't expect
+    // These should be filtered out if they exist
+    ...restProps
+  } = props;
+  
+  // Handle onInit to set instance and optionally apply fitView
+  // Note: fitView is not a ReactFlow prop, it's a method on the instance
+  // We check for it in restProps but it won't be passed to ReactFlow
+  const { fitView, fitViewOptions, ...reactFlowProps } = restProps;
+  
+  const handleInit = useCallback((instance: ReactFlowInstance) => {
+    setReactFlowInstance(instance);
+    // Apply fitView if configured (fitView is a boolean flag we check)
+    if (fitView) {
+      // Use longer timeout to ensure nodes are rendered
+      setTimeout(() => {
+        instance.fitView(fitViewOptions || { padding: 0.2, duration: 400 });
+      }, 300);
+    }
+  }, [setReactFlowInstance, fitView, fitViewOptions]);
+
+  return (
+    <ReactFlow
+      nodes={nodes}
+      edges={edges}
+      onNodesChange={onNodesChange}
+      onEdgesChange={onEdgesChange}
+      onConnect={onConnect}
+      onInit={handleInit}
+      nodeTypes={finalNodeTypes}
+      edgeTypes={finalEdgeTypes}
+      className={canvasClasses}
+      connectionLineComponent={connectionLineComponent}
+      defaultEdgeOptions={memoizedDefaultEdgeOptions}
+      nodeOrigin={nodeOrigin}
+      snapToGrid={snapToGrid}
+      snapGrid={snapGrid}
+      onlyRenderVisibleElements={onlyRenderVisibleElements}
+      aria-label="Flow diagram canvas"
+      role="application"
+      {...reactFlowProps}
+    >
+      {children}
+    </ReactFlow>
+  );
+}, (prevProps, nextProps) => {
+  // Custom comparison for memoization
+  // Only re-render if critical props change
+  return (
+    prevProps.nodeTypes === nextProps.nodeTypes &&
+    prevProps.edgeTypes === nextProps.edgeTypes &&
+    prevProps.className === nextProps.className &&
+    prevProps.connectionLineComponent === nextProps.connectionLineComponent &&
+    prevProps.defaultEdgeOptions === nextProps.defaultEdgeOptions &&
+    prevProps.nodeOrigin === nextProps.nodeOrigin &&
+    prevProps.snapToGrid === nextProps.snapToGrid &&
+    prevProps.onlyRenderVisibleElements === nextProps.onlyRenderVisibleElements
+  );
+});
+
+/**
+ * FlowCanvas Compound Component
+ * 
+ * Provides a hierarchical structure of components following compound components pattern.
+ */
+export const FlowCanvas = {
+  Root: FlowCanvasRoot,
+  Background: FlowBackground,
+  Controls: FlowControls,
+  Minimap: FlowMinimap,
+  Panel: FlowPanel,
+};