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

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

@@ -0,0 +1,106 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+import type {
+  Node,
+  Edge,
+  NodeChange,
+  EdgeChange,
+  Connection,
+  ReactFlowInstance,
+} from '@xyflow/react';
+import type {
+  FlowNodeData,
+  FlowEdgeData,
+  ValidationRule,
+  ConnectionRule,
+  LayoutStrategyName,
+  LayoutOptions,
+} from './FlowTypes';
+
+/**
+ * Flow Context Value
+ * 
+ * Context that complements ReactFlowProvider with design system specific
+ * functionality. This does NOT replace ReactFlowProvider.
+ */
+export interface FlowContextValue<
+  TNodeData extends FlowNodeData = FlowNodeData,
+  TEdgeData extends FlowEdgeData = FlowEdgeData
+> {
+  // Data
+  nodes: Node<TNodeData>[];
+  edges: Edge<TEdgeData>[];
+  
+  // React Flow Instance
+  reactFlowInstance: ReactFlowInstance | null;
+  setReactFlowInstance: (instance: ReactFlowInstance | null) => void;
+  
+  // State management
+  setNodes: (nodes: Node<TNodeData>[] | ((prev: Node<TNodeData>[]) => Node<TNodeData>[])) => void;
+  setEdges: (edges: Edge<TEdgeData>[] | ((prev: Edge<TEdgeData>[]) => Edge<TEdgeData>[])) => void;
+  
+  // Change handlers
+  onNodesChange?: (changes: NodeChange[]) => void;
+  onEdgesChange?: (changes: EdgeChange[]) => void;
+  onConnect?: (connection: Connection) => void;
+  
+  // Validation
+  validationRules: ValidationRule[];
+  connectionRules: ConnectionRule[];
+  addValidationRule: (rule: ValidationRule) => void;
+  removeValidationRule: (id: string) => void;
+  addConnectionRule: (rule: ConnectionRule) => void;
+  removeConnectionRule: (id: string) => void;
+  
+  // Layout
+  layoutStrategy: LayoutStrategyName | null;
+  setLayoutStrategy: (strategy: LayoutStrategyName | null) => void;
+  layoutOptions: LayoutOptions;
+  setLayoutOptions: (options: LayoutOptions) => void;
+  
+  // Theme
+  theme: 'light' | 'dark';
+  setTheme: (theme: 'light' | 'dark') => void;
+  
+  // Callbacks
+  onNodeAdd?: (node: Node<TNodeData>) => void;
+  onNodeRemove?: (nodeId: string) => void;
+  onNodeUpdate?: (nodeId: string, data: Partial<TNodeData>) => void;
+  onEdgeAdd?: (edge: Edge<TEdgeData>) => void;
+  onEdgeRemove?: (edgeId: string) => void;
+  onEdgeUpdate?: (edgeId: string, data: Partial<TEdgeData>) => void;
+}
+
+const FlowContext = createContext<FlowContextValue | undefined>(undefined);
+
+/**
+ * Hook to access Flow context
+ * 
+ * @throws Error if used outside of FlowProvider
+ */
+export function useFlowContext<
+  TNodeData extends FlowNodeData = FlowNodeData,
+  TEdgeData extends FlowEdgeData = FlowEdgeData
+>(): FlowContextValue<TNodeData, TEdgeData> {
+  const context = useContext(FlowContext);
+  
+  if (context === undefined) {
+    throw new Error('useFlowContext must be used within a FlowProvider');
+  }
+  
+  return context as unknown as FlowContextValue<TNodeData, TEdgeData>;
+}
+
+/**
+ * Hook to access Flow context (optional, returns undefined if not in FlowProvider)
+ */
+export function useFlowContextOptional<
+  TNodeData extends FlowNodeData = FlowNodeData,
+  TEdgeData extends FlowEdgeData = FlowEdgeData
+>(): FlowContextValue<TNodeData, TEdgeData> | undefined {
+  const context = useContext(FlowContext);
+  return context ? (context as unknown as FlowContextValue<TNodeData, TEdgeData>) : undefined;
+}
+
+export { FlowContext };

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

@@ -0,0 +1,67 @@
+'use client';
+
+import React from 'react';
+import { Controls, type ControlsProps } from '@xyflow/react';
+import { useFlowContext } from './FlowContext';
+import { getColorClass, getSpacingClass, getRadiusClass } from '../../../tokens';
+import styles from '../styles/modules/FlowControls.module.css';
+
+/**
+ * FlowControls Component
+ * 
+ * Wrapper for React Flow's Controls component with design system tokens.
+ * Single Responsibility: Render controls with design system styling.
+ */
+export interface FlowControlsProps extends Omit<ControlsProps, 'className' | 'position'> {
+  className?: string;
+  variant?: 'default' | 'minimal' | 'full';
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
+export function FlowControls({
+  className = '',
+  variant = 'default',
+  position = 'bottom-left',
+  ...props
+}: FlowControlsProps) {
+  const { theme } = useFlowContext();
+  
+  // Theme-based styling
+  const bgColor = theme === 'dark'
+    ? getColorClass('neutral', 'dark', 'bg')
+    : getColorClass('neutral', 'light', 'bg');
+  
+  const borderColor = getColorClass('neutral', 'DEFAULT', 'border');
+  const spacing = getSpacingClass('sm', 'p');
+  const radius = getRadiusClass('md');
+  
+  const controlsClasses = `
+    ${styles.controls}
+    ${variant === 'full' ? '' : styles.horizontal}
+    ${bgColor}
+    ${borderColor}
+    ${spacing}
+    ${radius}
+    border
+    shadow-md
+    ${className}
+  `.trim().replace(/\s+/g, ' ');
+  
+  // Show/hide controls based on variant
+  const showZoomIn = variant === 'full' || variant === 'default';
+  const showZoomOut = variant === 'full' || variant === 'default';
+  const showFitView = variant === 'full' || variant === 'default';
+  const showInteractive = variant === 'full';
+  
+  return (
+    <Controls
+      {...props}
+      className={controlsClasses}
+      showZoom={showZoomIn && showZoomOut}
+      showFitView={showFitView}
+      showInteractive={showInteractive}
+      position={position}
+      aria-label="Flow diagram controls"
+    />
+  );
+}

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

@@ -0,0 +1,70 @@
+'use client';
+
+import React from 'react';
+import type { HTMLAttributes } from 'react';
+
+/**
+ * FlowDragHandle Component
+ * 
+ * Custom drag handle for nodes. Use this component to create a specific area
+ * within a node that can be used for dragging, while other parts remain non-draggable.
+ * 
+ * Add the class "nodrag" to other elements to prevent dragging from those areas.
+ * 
+ * Single Responsibility: Provide a draggable handle area within a node.
+ */
+export interface FlowDragHandleProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Icon or content to display in the drag handle
+   */
+  icon?: React.ReactNode;
+  /**
+   * Size of the drag handle
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /**
+   * Variant for styling
+   */
+  variant?: 'default' | 'primary' | 'subtle';
+}
+
+export function FlowDragHandle({
+  icon,
+  size = 'md',
+  variant = 'default',
+  className = '',
+  children,
+  ...props
+}: FlowDragHandleProps) {
+  const sizeClasses = {
+    sm: 'w-4 h-4',
+    md: 'w-6 h-6',
+    lg: 'w-8 h-8',
+  };
+
+  const variantClasses = {
+    default: 'bg-gray-300 dark:bg-gray-600 hover:bg-gray-400 dark:hover:bg-gray-500',
+    primary: 'bg-blue-500 hover:bg-blue-600',
+    subtle: 'bg-gray-200 dark:bg-gray-700 hover:bg-gray-300 dark:hover:bg-gray-600',
+  };
+
+  return (
+    <div
+      className={`
+        custom-drag-handle
+        ${sizeClasses[size]}
+        ${variantClasses[variant]}
+        rounded-full
+        cursor-grab active:cursor-grabbing
+        flex items-center justify-center
+        transition-colors
+        ${className}
+      `.trim().replace(/\s+/g, ' ')}
+      {...props}
+    >
+      {icon || children || (
+        <div className="w-2 h-2 bg-current opacity-50 rounded-full" />
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,95 @@
+'use client';
+
+import React from 'react';
+import { EdgeToolbar, Position, type EdgeToolbarProps as ReactFlowEdgeToolbarProps } from '@xyflow/react';
+import { Button } from '../../../atoms';
+
+/**
+ * FlowEdgeToolbar Component
+ * 
+ * Enhanced wrapper for React Flow's EdgeToolbar with design system components.
+ * Similar to FlowNodeToolbar but for edges.
+ * 
+ * Single Responsibility: Render edge toolbar with design system Button components.
+ */
+export interface FlowEdgeToolbarProps extends Omit<ReactFlowEdgeToolbarProps, 'children'> {
+  /**
+   * Toolbar position relative to edge
+   */
+  position?: Position | 'top' | 'right' | 'bottom' | 'left';
+  /**
+   * Toolbar alignment
+   */
+  align?: 'start' | 'center' | 'end';
+  /**
+   * Actions to display in toolbar
+   */
+  actions?: Array<{
+    label: string;
+    icon?: React.ReactNode;
+    onClick: () => void;
+    variant?: 'primary' | 'regular' | 'secondary' | 'error' | 'outline' | 'ghost';
+    disabled?: boolean;
+  }>;
+  /**
+   * Whether toolbar is visible (defaults to true)
+   */
+  visible?: boolean;
+  /**
+   * Animation variant
+   */
+  animation?: 'none' | 'fade' | 'slide' | 'scale';
+  children?: React.ReactNode;
+}
+
+export function FlowEdgeToolbar({
+  actions,
+  children,
+  position = Position.Top,
+  align = 'center',
+  visible = true,
+  animation = 'fade',
+  ...props
+}: FlowEdgeToolbarProps) {
+  // Don't render if not visible
+  if (!visible) {
+    return null;
+  }
+  
+  // Animation classes
+  const animationClasses = {
+    none: '',
+    fade: 'animate-in fade-in duration-200',
+    slide: 'animate-in slide-in-from-top-1 duration-200',
+    scale: 'animate-in zoom-in-95 duration-200',
+  };
+  
+  // Convert string position to Position enum if needed
+  const toolbarPosition = typeof position === 'string' 
+    ? Position[position.charAt(0).toUpperCase() + position.slice(1) as keyof typeof Position] || Position.Top
+    : position;
+  
+  return (
+    <EdgeToolbar 
+      position={toolbarPosition}
+      align={align}
+      {...props}
+    >
+      <div className={`flex gap-1 ${animationClasses[animation]}`}>
+        {actions?.map((action, index) => (
+          <Button
+            key={index}
+            variant={action.variant || 'outline'}
+            size="sm"
+            onClick={action.onClick}
+            leftIcon={action.icon}
+            disabled={action.disabled}
+          >
+            {action.label}
+          </Button>
+        ))}
+        {children}
+      </div>
+    </EdgeToolbar>
+  );
+}

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

@@ -0,0 +1,63 @@
+'use client';
+
+import React from 'react';
+import { MiniMap, type MiniMapProps } from '@xyflow/react';
+import { useFlowContext } from './FlowContext';
+import { getColorClass, getSpacingClass, getRadiusClass } from '../../../tokens';
+import styles from '../styles/modules/FlowMinimap.module.css';
+
+/**
+ * FlowMinimap Component
+ * 
+ * Wrapper for React Flow's MiniMap component with design system tokens.
+ * Single Responsibility: Render minimap with design system styling.
+ */
+export interface FlowMinimapProps extends Omit<MiniMapProps, 'className'> {
+  className?: string;
+  nodeColor?: (node: unknown) => string;
+}
+
+export function FlowMinimap({
+  className = '',
+  nodeColor,
+  ...props
+}: FlowMinimapProps) {
+  const { theme } = useFlowContext();
+  
+  // Theme-based styling
+  const bgColor = theme === 'dark'
+    ? getColorClass('neutral', 'dark', 'bg')
+    : getColorClass('neutral', 'light', 'bg');
+  
+  const borderColor = getColorClass('neutral', 'DEFAULT', 'border');
+  const spacing = getSpacingClass('sm', 'p');
+  const radius = getRadiusClass('md');
+  
+  const minimapClasses = `
+    ${styles.minimap}
+    ${bgColor}
+    ${borderColor}
+    ${spacing}
+    ${radius}
+    border
+    shadow-md
+    ${className}
+  `.trim().replace(/\s+/g, ' ');
+  
+  // Default node color function
+  const defaultNodeColor = (node: unknown) => {
+    const variant = node.data?.variant || 'default';
+    const colorRole = variant === 'default' ? 'neutral' : variant;
+    return getColorClass(colorRole, 'DEFAULT', 'bg').replace('bg-', '');
+  };
+  
+  return (
+    <MiniMap
+      {...props}
+      className={minimapClasses}
+      nodeColor={nodeColor || defaultNodeColor}
+      maskColor={theme === 'dark' ? 'rgba(0, 0, 0, 0.5)' : 'rgba(255, 255, 255, 0.5)'}
+      aria-label="Flow diagram minimap"
+    />
+  );
+}

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

@@ -0,0 +1,76 @@
+'use client';
+
+import React from 'react';
+import { NodeResizer, type NodeResizerProps } from '@xyflow/react';
+
+/**
+ * FlowNodeResizer Component
+ * 
+ * Wrapper for React Flow's NodeResizer with design system integration.
+ * Provides resizing capability for nodes with constraints and aspect ratio support.
+ * 
+ * Single Responsibility: Render NodeResizer with design system styling.
+ */
+export interface FlowNodeResizerProps extends NodeResizerProps {
+  /**
+   * Show resize handles (defaults to selected state)
+   */
+  isVisible?: boolean;
+  /**
+   * Minimum width
+   */
+  minWidth?: number;
+  /**
+   * Maximum width
+   */
+  maxWidth?: number;
+  /**
+   * Minimum height
+   */
+  minHeight?: number;
+  /**
+   * Maximum height
+   */
+  maxHeight?: number;
+  /**
+   * Keep aspect ratio while resizing
+   */
+  keepAspectRatio?: boolean;
+  /**
+   * Line color for resize handles
+   */
+  lineColor?: string;
+  /**
+   * Handle color
+   */
+  handleColor?: string;
+}
+
+export function FlowNodeResizer({
+  isVisible = true,
+  minWidth,
+  maxWidth,
+  minHeight,
+  maxHeight,
+  keepAspectRatio = false,
+  lineColor,
+  handleColor,
+  ...props
+}: FlowNodeResizerProps) {
+  if (!isVisible) {
+    return null;
+  }
+
+  return (
+    <NodeResizer
+      minWidth={minWidth}
+      maxWidth={maxWidth}
+      minHeight={minHeight}
+      maxHeight={maxHeight}
+      keepAspectRatio={keepAspectRatio}
+      lineColor={lineColor}
+      handleColor={handleColor}
+      {...props}
+    />
+  );
+}

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

@@ -0,0 +1,50 @@
+'use client';
+
+import React from 'react';
+import { Panel, type PanelProps } from '@xyflow/react';
+import { getColorClass, getSpacingClass, getRadiusClass, getShadowClass } from '../../../tokens';
+import { useFlowContext } from './FlowContext';
+
+/**
+ * FlowPanel Component
+ * 
+ * Wrapper for React Flow's Panel component with design system tokens.
+ * Single Responsibility: Render panel with design system styling.
+ */
+export interface FlowPanelProps extends PanelProps {
+  variant?: 'default' | 'elevated' | 'outlined';
+}
+
+export function FlowPanel({
+  variant = 'default',
+  className = '',
+  ...props
+}: FlowPanelProps) {
+  const { theme } = useFlowContext();
+  
+  // Theme-based styling
+  const bgColor = theme === 'dark'
+    ? getColorClass('neutral', 'dark', 'bg')
+    : getColorClass('neutral', 'light', 'bg');
+  
+  const borderColor = getColorClass('neutral', 'DEFAULT', 'border');
+  const spacing = getSpacingClass('md', 'p');
+  const radius = getRadiusClass('lg');
+  const shadow = variant === 'elevated' ? getShadowClass('lg') : getShadowClass('sm');
+  
+  const panelClasses = `
+    ${bgColor}
+    ${variant === 'outlined' ? `${borderColor} border` : ''}
+    ${spacing}
+    ${radius}
+    ${shadow}
+    ${className}
+  `.trim().replace(/\s+/g, ' ');
+  
+  return (
+    <Panel
+      {...props}
+      className={panelClasses}
+    />
+  );
+}