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

package/src/ui/extensions/flow/MIGRATION_STORIES.md

@@ -0,0 +1,183 @@
+# Migration Guide: Stories Individuais → FlowPlayground
+
+Este documento mapeia as stories individuais removidas para suas funcionalidades correspondentes no FlowPlayground.
+
+## Visão Geral
+
+Todas as stories individuais da extensão Flow foram consolidadas no **FlowPlayground** como playground interativo principal. Isso permite demonstrar os componentes trabalhando em conjunto, proporcionando uma experiência mais realista e completa.
+
+## Mapeamento de Stories
+
+### Atoms
+
+#### FlowHandle.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Node Types Panel
+- Preview de diferentes tipos de nodes mostra diferentes configurações de handles
+- Configuração de handles ao criar/editar nodes
+- Demonstração de posições (top, bottom, left, right)
+
+#### FlowNodeWrapper.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Node Types Panel
+- Todos os tipos de nodes usam FlowNodeWrapper
+- Preview mostra diferentes variantes e tamanhos
+- Customização disponível no editor de nodes
+
+### Molecules
+
+#### CustomNode.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Node Types Panel → "Default"
+- Preview do tipo "Default" node
+- Demonstração de variantes e tamanhos
+- Edição completa no NodeEditor quando node está selecionado
+
+#### CustomEdge.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Edge Types Panel → "Default"
+- Preview do tipo "Default" edge
+- Demonstração de diferentes tipos de edges
+- Edição completa no EdgeEditor quando edge está selecionado
+
+#### FlowNodeToolbar.stories.tsx
+**Localização no Playground**: 
+- Funcionalidade integrada no playground
+- Toolbar aparece quando nodes são selecionados
+- Ações disponíveis no editor de nodes
+
+### Organisms
+
+#### FlowBackground.stories.tsx
+**Localização no Playground**: Seção "Background"
+- Painel completo de configuração de background
+- Preview em tempo real
+- Presets disponíveis
+- Customização de cores
+
+#### FlowCanvas.stories.tsx
+**Localização no Playground**: Base de todas as stories
+- FlowCanvas é o componente base do playground
+- Todas as funcionalidades do FlowCanvas estão disponíveis
+- Configurações no ReactFlowPropsPanel (seção "Canvas")
+
+#### FlowControls.stories.tsx
+**Localização no Playground**: Sempre visível no canvas
+- Controles de zoom e pan sempre disponíveis
+- Posicionados em "bottom-left" por padrão
+- Configurável via ReactFlowPropsPanel
+
+#### FlowMinimap.stories.tsx
+**Localização no Playground**: Sempre visível no canvas (quando habilitado)
+- Minimap integrado no playground
+- Configurável via ReactFlowPropsPanel
+
+#### FlowPanel.stories.tsx
+**Localização no Playground**: Painel lateral direito
+- Painel lateral do playground usa FlowPanel
+- Customizável e colapsável
+
+#### FlowNodeResizer.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Node Types Panel → "Resizable"
+- Preview do tipo "Resizable" node
+- Demonstração de resizing no canvas
+- Funcionalidade completa disponível
+
+#### FlowCustomNodes.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Node Types Panel
+- Todos os tipos customizados disponíveis:
+  - Input Node
+  - Output Node
+  - Selector Node
+  - Resizable Node
+- Preview de cada tipo
+- Demonstração de uso
+
+#### FlowCustomEdges.stories.tsx
+**Localização no Playground**: Seção "Nodes & Edges" → Edge Types Panel
+- Todos os tipos customizados disponíveis:
+  - Default (Bezier)
+  - Smooth Step
+  - Straight
+  - Step
+  - Floating
+- Preview de cada tipo
+- Demonstração de uso
+
+#### FlowCustomization.stories.tsx
+**Localização no Playground**: Story "Customization"
+- Story dedicada para customização
+- Demonstração de todas as opções de customização
+- Preview de variantes, tamanhos, estilos
+
+#### FlowLayouts.stories.tsx
+**Localização no Playground**: Seção "Layout" e Story "Layouts"
+- Painel completo de configuração de layouts
+- Preview de diferentes algoritmos
+- Story "Layouts" focada em layouts
+
+#### FlowValidation.stories.tsx
+**Localização no Playground**: Story "Validation"
+- Story dedicada para validação
+- Painel de validação em tempo real
+- Demonstração de regras de conexão
+
+#### FlowDragNDrop.stories.tsx
+**Localização no Playground**: Story "Advanced"
+- Funcionalidade de drag & drop integrada
+- Demonstração na story "Advanced"
+- Disponível em todas as stories do playground
+
+#### FlowExamples.stories.tsx
+**Localização no Playground**: Story "Examples"
+- Story dedicada com templates
+- Carregamento de templates pré-configurados
+- Exemplos de diferentes padrões de flow
+
+## Como Usar o Playground
+
+### Para Desenvolvedores
+
+1. **Explorar Componentes**: Use a story "Interactive" para acesso completo
+2. **Aprender**: Use "Getting Started" para tutorial passo a passo
+3. **Customizar**: Use "Customization" para ver opções de customização
+4. **Aplicar Layouts**: Use "Layouts" para experimentar algoritmos
+5. **Validar**: Use "Validation" para testar validação
+6. **Avançado**: Use "Advanced" para funcionalidades avançadas
+7. **Exemplos**: Use "Examples" para templates prontos
+
+### Navegação por Seções
+
+Use a barra de navegação lateral (ícones) para alternar entre seções:
+- Cada seção mostra painéis específicos
+- Seções podem ser colapsadas
+- Atalhos de teclado disponíveis
+
+## Benefícios da Consolidação
+
+1. **Experiência Realista**: Componentes demonstrados trabalhando juntos
+2. **Menos Manutenção**: Um único ponto de entrada ao invés de múltiplas stories
+3. **Melhor Documentação**: Documentação centralizada e mais completa
+4. **Interatividade**: Playground interativo mais rico que stories estáticas
+5. **Foco**: Uma única entrada para explorar toda a extensão
+
+## Perguntas Frequentes
+
+**Q: Onde encontro exemplos de FlowHandle?**
+A: Na seção "Nodes & Edges" → Node Types Panel. Cada preview de node mostra diferentes configurações de handles.
+
+**Q: Como vejo diferentes tipos de edges?**
+A: Na seção "Nodes & Edges" → Edge Types Panel. Você verá previews de todos os tipos disponíveis.
+
+**Q: Onde configuro o background?**
+A: Use a seção "Background" no playground. Há um painel completo com presets e customização.
+
+**Q: Como aplico layouts?**
+A: Use a seção "Layout" ou a story "Layouts". Configure o algoritmo e clique em "Apply Layout".
+
+**Q: Onde estão os templates?**
+A: Na story "Examples". Você pode carregar diferentes templates pré-configurados.
+
+## Suporte
+
+Se você não encontrar uma funcionalidade específica:
+1. Verifique todas as seções do playground
+2. Consulte a documentação do FlowPlayground.mdx
+3. Explore diferentes stories do playground
+4. Use a busca no Storybook para encontrar componentes específicos

package/src/ui/extensions/flow/PLAYGROUND_GUIDE.md

@@ -0,0 +1,267 @@
+# Flow Playground Guide
+
+Guia completo de uso do Flow Playground no Storybook.
+
+## Índice
+
+1. [Introdução](#introdução)
+2. [Interface](#interface)
+3. [Operações Básicas](#operações-básicas)
+4. [Operações Avançadas](#operações-avançadas)
+5. [Validação](#validação)
+6. [Export/Import](#exportimport)
+7. [Dicas e Truques](#dicas-e-truques)
+8. [Troubleshooting](#troubleshooting)
+
+## Introdução
+
+O Flow Playground é uma ferramenta interativa que permite criar, editar e testar diagramas de fluxo diretamente no Storybook. É ideal para:
+
+- Prototipar flows rapidamente
+- Testar diferentes layouts e estruturas
+- Validar regras de conexão
+- Exportar flows para uso em produção
+
+## Interface
+
+### Sidebar Esquerda
+
+A sidebar contém todos os controles do playground:
+
+- **Theme Toggle**: Alterna entre temas light e dark
+- **Add Node**: Formulário para adicionar novos nodes
+- **Node Actions**: Ações para o node selecionado
+- **Flow Statistics**: Estatísticas do flow atual
+- **Validation**: Painel de validação
+- **Export/Import**: Controles de exportação e importação
+
+### Canvas
+
+O canvas é a área principal onde você trabalha com o flow:
+
+- **Drag & Drop**: Arraste nodes para reposicioná-los
+- **Connect**: Clique e arraste de um handle para outro para criar conexões
+- **Select**: Clique em nodes para selecioná-los
+- **Zoom/Pan**: Use os controles ou scroll do mouse
+
+## Operações Básicas
+
+### Adicionar um Node
+
+1. Preencha o campo "Label" com o nome do node
+2. Selecione uma "Variant" (default, primary, success, warning, error)
+3. Clique em "Add Node"
+4. O node aparecerá em uma posição aleatória no canvas
+
+### Selecionar um Node
+
+- Clique em qualquer node no canvas
+- O node selecionado será destacado
+- As informações do node aparecerão no painel "Selected Node"
+
+### Editar um Node
+
+1. Selecione o node que deseja editar
+2. Modifique o "Label" ou "Variant" nos campos
+3. Clique em "Update Node"
+4. As mudanças serão aplicadas imediatamente
+
+### Remover um Node
+
+1. Selecione o node que deseja remover
+2. Clique em "Delete Node"
+3. O node e todas as suas conexões serão removidos
+
+### Criar uma Conexão
+
+1. Passe o mouse sobre um node para ver os handles
+2. Clique e segure em um handle (círculo pequeno)
+3. Arraste até outro node
+4. Solte para criar a conexão
+
+### Remover uma Conexão
+
+1. Selecione a edge (linha) que deseja remover
+2. Pressione Delete ou Backspace
+3. A edge será removida
+
+## Operações Avançadas
+
+### Clonar um Node
+
+1. Selecione o node que deseja clonar
+2. Clique em "Clone Node"
+3. Uma cópia do node será criada próxima ao original
+
+### Alternar Tema
+
+1. Use o seletor "Theme" na parte superior da sidebar
+2. Escolha entre "Light" e "Dark"
+3. O canvas será atualizado imediatamente
+
+### Usar o Minimap
+
+- O minimap mostra uma visão geral do flow
+- Clique e arraste no minimap para navegar
+- Útil para flows grandes
+
+### Usar os Controls
+
+Os controles no canto inferior esquerdo permitem:
+
+- **Zoom In/Out**: Aumentar ou diminuir o zoom
+- **Fit View**: Ajustar a visualização para mostrar todos os nodes
+- **Lock/Unlock**: Travar ou destravar a interação
+
+## Validação
+
+### Validar o Flow
+
+1. Clique em "Validate Flow"
+2. O sistema verificará:
+   - IDs duplicados
+   - Conexões inválidas
+   - Regras de conexão
+   - Estrutura mínima
+
+### Interpretar Resultados
+
+- **Errors**: Problemas críticos que impedem o funcionamento
+- **Warnings**: Problemas que podem causar comportamento inesperado
+- **Info**: Informações sobre o flow
+
+### Corrigir Erros
+
+1. Leia a mensagem de erro no painel de validação
+2. Identifique o node ou edge problemático
+3. Corrija o problema (ex: remover ID duplicado, corrigir conexão)
+4. Valide novamente
+
+## Export/Import
+
+### Exportar um Flow
+
+1. Clique em "Export JSON"
+2. Um arquivo JSON será baixado
+3. O arquivo contém toda a estrutura do flow
+
+### Importar um Flow
+
+1. Clique em "Import JSON"
+2. Selecione um arquivo JSON válido
+3. O flow será carregado no canvas
+4. Certifique-se de que o formato está correto
+
+### Formato do JSON
+
+O JSON deve seguir esta estrutura:
+
+```json
+{
+  "nodes": [
+    {
+      "id": "string",
+      "type": "string",
+      "position": { "x": number, "y": number },
+      "data": {
+        "label": "string",
+        "variant": "string"
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "string",
+      "source": "string",
+      "target": "string",
+      "data": {}
+    }
+  ],
+  "viewport": {
+    "x": number,
+    "y": number,
+    "zoom": number
+  }
+}
+```
+
+## Dicas e Truques
+
+### Organização
+
+- Use variants para categorizar nodes visualmente
+- Agrupe nodes relacionados próximos uns dos outros
+- Use labels descritivos nas edges
+
+### Performance
+
+- Para flows muito grandes (>100 nodes), considere dividir em múltiplos flows
+- Use o minimap para navegação rápida
+- Exporte regularmente para não perder trabalho
+
+### Acessibilidade
+
+- Use labels claros e descritivos
+- Evite cores como única forma de diferenciação
+- Teste em diferentes temas
+
+### Boas Práticas
+
+1. **Valide Regularmente**: Valide o flow após mudanças significativas
+2. **Exporte Frequentemente**: Salve seu trabalho regularmente
+3. **Use Variants Consistentemente**: Mantenha uma convenção de variants
+4. **Documente**: Adicione descrições aos nodes quando necessário
+
+## Troubleshooting
+
+### Problema: Nodes não aparecem
+
+**Solução:**
+- Verifique se as posições dos nodes estão dentro do viewport
+- Use "Fit View" nos controls para ajustar a visualização
+- Verifique se há erros no console
+
+### Problema: Não consigo criar conexões
+
+**Solução:**
+- Certifique-se de que os handles estão visíveis
+- Verifique se há regras de conexão bloqueando
+- Tente conectar de handles diferentes (top, bottom, left, right)
+
+### Problema: Erro ao importar JSON
+
+**Solução:**
+- Verifique se o JSON está bem formatado
+- Certifique-se de que todos os nodes referenciados nas edges existem
+- Verifique se os IDs são únicos
+
+### Problema: Performance lenta
+
+**Solução:**
+- Reduza o número de nodes no flow
+- Desabilite animações se não forem necessárias
+- Use o minimap em vez de pan/zoom constante
+
+### Problema: Mudanças não são salvas
+
+**Solução:**
+- Exporte o flow antes de sair
+- O playground não salva automaticamente
+- Use o botão de export regularmente
+
+## Recursos Adicionais
+
+- [Documentação do React Flow](https://reactflow.dev/)
+- [Flow Examples](./FlowExamples.stories.tsx)
+- [Flow Layouts](./FlowLayouts.stories.tsx)
+- [Flow Validation](./FlowValidation.stories.tsx)
+- [Flow Customization](./FlowCustomization.stories.tsx)
+
+## Suporte
+
+Para problemas ou dúvidas:
+
+1. Verifique este guia
+2. Consulte a documentação MDX
+3. Revise os exemplos nas stories
+4. Abra uma issue no repositório

package/src/ui/extensions/flow/README.md

@@ -0,0 +1,204 @@
+# Flow Extension
+
+Complete flow diagram system built on top of React Flow (@xyflow/react) with design system integration.
+
+## Overview
+
+The Flow extension provides a comprehensive 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 extension follows Atomic Design principles within its own structure:
+
+- **Atoms**: `FlowHandle`, `FlowNodeWrapper` - Basic building blocks
+- **Molecules**: `CustomNode`, `CustomEdge`, `FlowNodeToolbar` - Composed components
+- **Organisms**: `FlowCanvas`, `FlowProvider` - Complex components with compound patterns
+
+Additionally, the extension includes:
+
+- **Factories**: Factory pattern for creating nodes and edges
+- **Registries**: Registry pattern for managing node types, edge types, layouts, and plugins
+- **Strategies**: Strategy pattern for layouts, edge routing, and animations
+- **Contexts**: Specialized contexts for styles, events, and performance
+- **Providers**: Specialized providers for theming, events, performance, and debugging
+- **Hooks**: Specialized hooks for styles, performance, events, utils, selection, and viewport
+- **Styles**: CSS variables and modules for theming
+- **Utils**: Utility functions for CSS, geometry, and performance
+
+## Installation
+
+The Flow extension is part of the design system. Ensure you have the required peer dependencies:
+
+```bash
+npm install @xyflow/react
+```
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { FlowCanvas, FlowProvider } from '@fabio.caffarello/react-design-system/extensions/flow';
+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>
+  );
+}
+```
+
+### Alternative Import Paths
+
+You can also import from the main extensions export:
+
+```tsx
+import { FlowCanvas, FlowProvider } from '@fabio.caffarello/react-design-system/extensions';
+```
+
+Or from the main package (with deprecation warning):
+
+```tsx
+import { FlowCanvas, FlowProvider } from '@fabio.caffarello/react-design-system';
+```
+
+## 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
+- **InputNode**: Node with only source handles
+- **OutputNode**: Node with only target handles
+- **SelectorNode**: Node with interactive controls
+- **ResizableNode**: Node with resizing capabilities
+- **FloatingEdge**: Edge that dynamically adjusts its path
+
+## Hooks
+
+- `useFlowStyles` - Access and manage CSS variables and theming
+- `useFlowPerformance` - Monitor and optimize performance
+- `useFlowEvents` - Subscribe to and emit Flow events
+- `useFlowUtils` - Utility functions for geometry and helpers
+- `useFlowSelection` - Advanced selection management
+- `useFlowViewport` - Viewport management (zoom, pan, fit view)
+- `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
+
+## Factories
+
+- `FlowFactory` - Main factory for creating flows, nodes, and edges
+- `NodeBuilder` - Fluent builder for creating nodes
+- `EdgeBuilder` - Fluent builder for creating edges
+
+## Registries
+
+- `NodeTypeRegistry` - Registry for managing node types
+- `EdgeTypeRegistry` - Registry for managing edge types
+- `LayoutRegistry` - Registry for managing layout strategies
+- `PluginRegistry` - Registry for managing Flow plugins
+
+## Strategies
+
+- `LayoutStrategyManager` - Manages layout algorithms (Dagre, ELK, Force)
+- `EdgeRoutingStrategyManager` - Manages edge routing strategies
+- `AnimationStrategyManager` - Manages animation strategies
+
+## Customization
+
+Nodes and edges can be customized through multiple 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 via CSS variables
+
+## Theming
+
+The Flow extension uses CSS variables for theming, integrated with the design system tokens:
+
+```tsx
+import { FlowStyleProvider } from '@fabio.caffarello/react-design-system/extensions/flow';
+
+<FlowStyleProvider initialTheme="dark">
+  {/* Your flow components */}
+</FlowStyleProvider>
+```
+
+## Performance
+
+The extension includes performance optimizations:
+
+- Memoization of components
+- Virtualization for large flows
+- Lazy loading of node/edge types
+- Performance monitoring hooks
+
+## Migration from Old Structure
+
+If you were using Flow components from the old structure:
+
+**Before:**
+```tsx
+import { FlowCanvas } from '@fabio.caffarello/react-design-system';
+```
+
+**After:**
+```tsx
+import { FlowCanvas } from '@fabio.caffarello/react-design-system/extensions/flow';
+```
+
+The old import path will still work but will show a deprecation warning.
+
+## Documentation
+
+For more detailed documentation, see:
+- [Flow.mdx](./organisms/Flow.mdx) - Complete component documentation
+- [FlowPlayground.mdx](./organisms/FlowPlayground.mdx) - Playground guide
+- Storybook stories in the `Extensions/Flow` section

package/src/ui/extensions/flow/atoms/FlowHandle.test.tsx

@@ -0,0 +1,43 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render } from '@testing-library/react';
+import { FlowProvider } from '../organisms/FlowProvider';
+import { FlowHandle } from './FlowHandle';
+import type { Node } from '@xyflow/react';
+
+describe('FlowHandle', () => {
+  const mockNodes: Node[] = [];
+  const mockEdges: any[] = [];
+  
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  
+  it('renders handle with default props', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowHandle type="source" position="bottom" />
+      </FlowProvider>
+    );
+    // Handle component renders (React Flow may not fully initialize in test environment)
+    // Just verify no errors occurred
+    expect(container).toBeTruthy();
+  });
+  
+  it('renders handle with variant', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowHandle type="source" position="bottom" variant="primary" />
+      </FlowProvider>
+    );
+    expect(container).toBeTruthy();
+  });
+  
+  it('renders handle with size', () => {
+    const { container } = render(
+      <FlowProvider nodes={mockNodes} edges={mockEdges}>
+        <FlowHandle type="source" position="bottom" size="lg" />
+      </FlowProvider>
+    );
+    expect(container).toBeTruthy();
+  });
+});