add full docs

Author: Pedroodelvalle

docs/.gitignore

@@ -0,0 +1,8 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor
+.bundle
+Gemfile.lock
+

docs/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "jekyll-theme-minimal"
+gem "webrick", "~> 1.8"
+
+group :jekyll_plugins do
+  gem "jekyll-relative-links"
+  gem "jekyll-optional-front-matter"
+end
+

docs/_config.yml

@@ -0,0 +1,52 @@
+title: JSON Canvas Viewer
+description: Documentação técnica completa do JSON Canvas Viewer
+theme: jekyll-theme-minimal
+markdown: kramdown
+kramdown:
+  input: GFM
+  syntax_highlighter: rouge
+  syntax_highlighter_opts:
+    default_lang: dart
+    css_class: 'highlight'
+
+plugins:
+  - jekyll-relative-links
+  - jekyll-optional-front-matter
+
+relative_links:
+  enabled: true
+  collections: false
+
+optional_front_matter:
+  remove_originals: true
+
+# Navigation
+nav_links:
+  - title: Home
+    url: /
+  - title: Arquitetura
+    url: /architecture
+  - title: Componentes
+    url: /components
+  - title: Especificação JSON
+    url: /json-spec
+  - title: Elementos
+    url: /elements
+  - title: Renderização
+    url: /rendering
+  - title: Interatividade
+    url: /interactivity
+  - title: Decisões Técnicas
+    url: /technical-decisions
+  - title: Instalação
+    url: /installation
+  - title: Contribuindo
+    url: /contributing
+
+# GitHub
+repository: conty/jsoncanvasviewer
+github_username: conty
+
+# Google Analytics (opcional)
+# google_analytics: UA-XXXXXXXX-X
+

docs/architecture.md

@@ -0,0 +1,285 @@
+---
+layout: default
+title: Arquitetura
+---
+
+# Arquitetura Técnica
+
+## Visão Geral
+
+O JSON Canvas Viewer segue uma arquitetura modular com separação clara de responsabilidades, implementando o padrão de apresentação baseado em widgets do Flutter com gerenciamento de estado local usando StatefulWidget.
+
+## Estrutura do Projeto
+
+```
+jsoncanvasviewer/
+├── lib/
+│   ├── main.dart                          # Ponto de entrada
+│   └── src/
+│       ├── modules/
+│       │   └── home/
+│       │       └── ui/
+│       │           ├── home_page.dart             # Coordenador principal
+│       │           └── widgets/
+│       │               ├── canvas_viewer_widget.dart
+│       │               └── json_editor_widget.dart
+│       └── shared/
+│           ├── colors/
+│           │   ├── app_colors.dart
+│           │   └── editor_theme.dart
+│           └── jsonWidget/
+│               └── json_canvas_widget.dart       # Motor de renderização
+├── pubspec.yaml
+└── analysis_options.yaml
+```
+
+## Diagrama de Componentes
+
+```mermaid
+graph TB
+    subgraph "Camada de Apresentação"
+        MA[MyApp]
+        HP[HomePage]
+        JE[JsonEditorWidget]
+        CV[CanvasViewerWidget]
+    end
+    
+    subgraph "Camada de Renderização"
+        JCV[JsonCanvasViewer]
+        AR[ApplyRotation]
+    end
+    
+    subgraph "Camada de Dados"
+        JSON[JSON Data]
+        EL[Elements List]
+    end
+    
+    subgraph "Camada de Tema"
+        ET[EditorTheme]
+        AC[AppColors]
+    end
+    
+    MA --> HP
+    HP --> JE
+    HP --> CV
+    JE --> JSON
+    CV --> JCV
+    JCV --> JSON
+    JCV --> EL
+    JCV --> AR
+    JE --> ET
+    CV --> ET
+    JCV --> AC
+```
+
+## Camadas da Arquitetura
+
+### Camada de Apresentação
+
+Responsável pela interface do usuário e interação.
+
+**Componentes**:
+- `MyApp`: Configuração global da aplicação
+- `HomePage`: Coordenador principal, gerencia estado compartilhado
+- `JsonEditorWidget`: Editor de código JSON
+- `CanvasViewerWidget`: Visualizador do canvas
+
+### Camada de Renderização
+
+Processa JSON e renderiza elementos visuais.
+
+**Componentes**:
+- `JsonCanvasViewer`: Motor de renderização principal
+- `ApplyRotation`: Widget para aplicar transformações de rotação
+
+### Camada de Dados
+
+Gerencia estrutura de dados e parsing.
+
+**Componentes**:
+- JSON parseado como `Map<String, dynamic>`
+- Lista de elementos ordenados por z-index
+
+### Camada de Tema
+
+Define estilos visuais e cores.
+
+**Componentes**:
+- `EditorTheme`: Tema do editor de código
+- `AppColors`: Paleta de cores da aplicação
+
+## Fluxo de Comunicação
+
+### Fluxo de Edição (Editor → Canvas)
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant JE as JsonEditor
+    participant HP as HomePage
+    participant CV as CanvasViewer
+    participant JCV as JsonCanvasViewer
+
+    U->>JE: Digita no editor
+    JE->>JE: Inicia debounce (300ms)
+    Note over JE: Timer expira
+    JE->>JE: _validateJson()
+    JE->>HP: onJsonChanged(jsonString)
+    JE->>HP: onValidationChanged(isValid)
+    HP->>HP: setState(_jsonData, _isValid)
+    HP->>CV: Passa jsonData e isValid
+    CV->>CV: didUpdateWidget detecta mudança
+    CV->>JCV: Cria/atualiza JsonCanvasViewer
+    JCV->>JCV: _parseAndSetupJson()
+    JCV->>JCV: build() renderiza elementos
+    JCV->>U: Exibe canvas atualizado
+```
+
+### Fluxo de Interação (Canvas → Editor)
+
+```mermaid
+sequenceDiagram
+    participant U as Usuário
+    participant JCV as JsonCanvasViewer
+    participant CV as CanvasViewer
+    participant HP as HomePage
+    participant JE as JsonEditor
+
+    U->>JCV: onPanStart (inicia drag)
+    JCV->>JCV: setState(_draggedElementIndex)
+    U->>JCV: onPanUpdate (arrasta)
+    JCV->>JCV: Atualiza elemento local
+    JCV->>CV: onElementMoved(index, newX, newY)
+    CV->>CV: _updateJsonOnElementMove()
+    CV->>CV: Modifica Map decoded
+    CV->>HP: onJsonUpdated(updatedJson)
+    HP->>HP: _isUpdatingFromCanvas = true
+    HP->>HP: setState(_jsonData)
+    HP->>HP: _isUpdatingFromCanvas = false
+    HP->>JE: externalJsonData atualizado
+    JE->>JE: didUpdateWidget detecta mudança
+    JE->>JE: _isUpdatingFromExternal = true
+    JE->>JE: _codeController.text = externalJson
+    JE->>JE: _isUpdatingFromExternal = false
+    JE->>U: Editor exibe JSON atualizado
+    U->>JCV: onPanEnd (termina drag)
+    JCV->>JCV: setState(limpa flags)
+```
+
+## Gerenciamento de Estado
+
+### HomePage State
+
+```dart
+class _HomePageState extends State<HomePage> {
+  String _jsonData = '';
+  bool _isValid = false;
+  bool _isUpdatingFromCanvas = false;
+  
+  // Atualização do editor
+  void _onJsonChanged(String jsonData) {
+    if (_isUpdatingFromCanvas) return;  // Previne loop
+    Future.microtask(() {
+      if (mounted) setState(() => _jsonData = jsonData);
+    });
+  }
+  
+  // Atualização do canvas
+  void onCanvasUpdate(String updatedJson) {
+    _isUpdatingFromCanvas = true;
+    setState(() => _jsonData = updatedJson);
+    _isUpdatingFromCanvas = false;
+  }
+}
+```
+
+### Prevenção de Loop Infinito
+
+O sistema usa múltiplas flags para prevenir loops de atualização:
+
+1. **HomePage**: `_isUpdatingFromCanvas`
+   - Ativada quando Canvas atualiza JSON
+   - Previne HomePage de notificar Canvas novamente
+
+2. **JsonEditorWidget**: `_isUpdatingFromExternal`
+   - Ativada quando recebe dados externos
+   - Previne Editor de notificar HomePage novamente
+
+3. **JsonEditorWidget**: `_lastExternalData`
+   - Cache do último dado externo
+   - Previne atualizações redundantes
+
+## Responsabilidades por Módulo
+
+| Módulo | Responsabilidades | Dependências |
+|--------|------------------|--------------|
+| **main.dart** | Inicialização, tema global | MaterialApp, HomePage |
+| **HomePage** | Coordenação, estado compartilhado | JsonEditor, CanvasViewer |
+| **JsonEditorWidget** | Edição JSON, validação | CodeController, Debounce |
+| **CanvasViewerWidget** | Exibição canvas, detecção mudanças | JsonCanvasViewer |
+| **JsonCanvasViewer** | Parsing JSON, renderização elementos | Dart core, Flutter widgets |
+| **EditorTheme** | Estilos do editor | CodeThemeData |
+| **AppColors** | Cores da aplicação | Color constants |
+
+## Sistema de Escala
+
+O sistema implementa coordenadas de design fixo que escalam proporcionalmente:
+
+```dart
+// Dimensões de design (referência)
+designWidth = 1080
+designHeight = 1920
+
+// Fator de escala
+scaleFactor = min(canvasWidth / designWidth, canvasHeight / designHeight)
+
+// Aplicação
+finalX = originalX * scaleFactor
+finalFontSize = originalFontSize * scaleFactor
+```
+
+**Benefícios**:
+- Designers trabalham em resolução fixa
+- Canvas se adapta a qualquer tamanho
+- Coordenadas intuitivas e previsíveis
+
+## Padrões Utilizados
+
+### Observer Pattern
+- Callbacks para comunicação entre widgets
+- `onJsonChanged`, `onValidationChanged`, `onElementMoved`
+
+### State Management
+- Local state com `StatefulWidget`
+- Props drilling para estado compartilhado
+
+### Composition over Inheritance
+- Widgets compostos de outros widgets
+- Reutilização através de composição
+
+### Debouncing
+- Timer de 300ms para otimizar performance
+- Reduz chamadas desnecessárias ao parser
+
+## Performance
+
+### Otimizações Implementadas
+
+1. **Debouncing**: Timer de 300ms nas atualizações do editor
+2. **Microtasks**: `Future.microtask` para callbacks assíncronos
+3. **Conditional Rebuild**: Verificações em `didUpdateWidget`
+4. **Z-Index Sorting**: Ordenação única durante parse
+5. **Scale Factor Cache**: Cálculo único por build
+
+### Limitações de Performance
+
+- Não virtualizado: todos elementos renderizados sempre
+- Rebuild completo do Stack a cada mudança
+- Recomendado: máximo 50-100 elementos
+
+## Próximos Passos
+
+- Explore [Componentes](components.md) para detalhes de implementação
+- Veja [Renderização](rendering.md) para entender o pipeline
+- Confira [Decisões Técnicas](technical-decisions.md) para justificativas
+