@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/content/.morph/templates/ui-flows.md

@@ -1,336 +1,336 @@
-# UI Flows - {{FEATURE_NAME_TITLE}}
-
-> Fluxos de usuário completos mostrando navegação, decisões e edge cases.
-> Documenta COMO o usuário se move pela feature do início ao fim.
-
----
-
-## Fluxo 1: {Nome do Fluxo Principal}
-
-### Contexto
-
-**Trigger (Gatilho):**
-{O que inicia este fluxo? Ex: "Usuário clica em [+ Novo Pedido]"}
-
-**Pré-condições:**
-- {Condição 1 que deve ser verdadeira para iniciar o fluxo}
-- {Condição 2}
-
-**Objetivo:**
-{O que o usuário quer alcançar ao final deste fluxo?}
-
----
-
-### Happy Path (Caminho Ideal)
-
-#### Passos
-
-**1. {Tela/Componente Inicial}**: {Ação do usuário}
-   - Sistema: {Resposta do sistema}
-   - UI: {Mudança visual}
-   - Navegação: {Para onde vai}
-
-**2. {Próxima Tela/Componente}**: {Próxima ação}
-   - Sistema: {Processamento backend}
-   - UI: {Feedback visual}
-   - Validação: {Regras aplicadas}
-
-**3. {Tela/Componente Final}**: {Ação de conclusão}
-   - Sistema: {Persistência/salvamento}
-   - UI: {Mensagem de sucesso}
-   - Navegação: {Retorna para onde}
-
-**Tempo estimado:** {X segundos/minutos para usuário completar}
-
----
-
-### Diagrama de Fluxo (Happy Path)
-
-```
-┌─────────────────┐
-│  Tela Inicial   │
-│  [Dashboard]    │
-└────────┬────────┘
-         │
-         │ Clica [+ Novo Pedido]
-         ▼
-┌─────────────────┐
-│   Modal/Wizard  │
-│   Aberto        │
-└────────┬────────┘
-         │
-         │ ⟨Step 1⟩ Seleciona Cliente
-         ▼
-┌─────────────────┐
-│  Cliente        │
-│  Selecionado    │
-└────────┬────────┘
-         │
-         │ Clica [Próximo]
-         ▼
-┌─────────────────┐
-│  ⟨Step 2⟩       │
-│  Produtos       │
-└────────┬────────┘
-         │
-         │ Adiciona Produtos
-         │ Total Calculado
-         ▼
-┌─────────────────┐
-│  Lista de       │
-│  Produtos OK    │
-└────────┬────────┘
-         │
-         │ Clica [Próximo]
-         ▼
-┌─────────────────┐
-│  ⟨Step 3⟩       │
-│  Revisão        │
-└────────┬────────┘
-         │
-         │ Clica [Confirmar]
-         ▼
-┌─────────────────┐
-│  ✅ Pedido      │
-│  Criado!        │
-└────────┬────────┘
-         │
-         │ Toast "Sucesso!"
-         │ Navega para Detalhes
-         ▼
-┌─────────────────┐
-│  Tela Detalhes  │
-│  Pedido #12345  │
-└─────────────────┘
-```
-
----
-
-### Edge Cases (Casos de Exceção)
-
-#### 1. {Nome do Edge Case}
-
-**Cenário:**
-{Descrição da situação excepcional}
-
-**Como o sistema lida:**
-```
-┌─────────────────┐
-│  Passo Normal   │
-└────────┬────────┘
-         │
-         │ ❌ {Erro/Condição}
-         ▼
-┌─────────────────┐
-│  Mensagem Erro  │
-│  FluentDialog   │
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    │         │
-    ▼         ▼
-[Tentar]  [Cancelar]
-Novamente
-    │         │
-    │         └──▶ [Volta Dashboard]
-    │
-    └──▶ [Repete Passo]
-```
-
-**UI:**
-- Componente: {FluentDialog, FluentMessageBar, etc}
-- Mensagem: "{Texto exato da mensagem}"
-- Ações disponíveis: {Botões/links}
-
-**Exemplo de código:**
-```razor
-@if (!string.IsNullOrEmpty(_error))
-{
-    <FluentMessageBar Intent="MessageIntent.Error">
-        @_error
-        <FluentButton OnClick="@Retry">Tentar Novamente</FluentButton>
-    </FluentMessageBar>
-}
-```
-
----
-
-#### 2. {Outro Edge Case}
-
-{Repita a estrutura acima}
-
----
-
-### Fluxos Alternativos
-
-#### Alt 1: {Nome do Fluxo Alternativo}
-
-**Diverge em:** {Em qual passo do happy path este fluxo se ramifica}
-
-**Condição:** {O que causa a divergência}
-
-**Passos:**
-1. {Passo alternativo 1}
-2. {Passo alternativo 2}
-3. {Convergência de volta ao happy path OU conclusão diferente}
-
-**Diagrama:**
-```
-[Happy Path]
-     │
-     ├─{Condição}──▶ [Fluxo Alt]
-     │                    │
-     │                    └──▶ [Converge]
-     ▼
-[Continua...]
-```
-
----
-
-## Fluxo 2: {Segundo Fluxo Importante}
-
-{Repita toda a estrutura acima para cada fluxo principal}
-
----
-
-## Interações Comuns (Micro-Fluxos)
-
-### {Ação Rápida - Ex: "Buscar Item"}
-
-**Trigger:** {Usuário digita na search bar}
-
-**Fluxo:**
-```
-[Input vazio] ──▶ [Usuário digita] ──▶ [Debounce 300ms] ──▶ [API Call]
-                                                                  │
-                                                                  ▼
-                                                            [Resultados]
-                                                                  │
-                                                    ┌─────────────┴──────────┐
-                                                    ▼                        ▼
-                                             [Tem Resultados]         [Vazio]
-                                                    │                        │
-                                                    ▼                        ▼
-                                             [Mostra Lista]    [Mostra "Não encontrado"]
-```
-
-**Componente:** `FluentAutocomplete`
-
-**Código:**
-```razor
-<FluentAutocomplete TItem="Item"
-                   SearchAsync="@SearchItemsAsync"
-                   Placeholder="Buscar item..."
-                   MinLength="2"
-                   Debounce="300">
-    <ItemTemplate Context="item">
-        @item.Name
-    </ItemTemplate>
-</FluentAutocomplete>
-```
-
----
-
-## Mapa de Navegação Completo
-
-Visão geral de TODAS as telas e como se conectam:
-
-```
-                    ┌──────────────┐
-                    │  Dashboard   │
-                    └──────┬───────┘
-                           │
-         ┌─────────────────┼─────────────────┐
-         │                 │                 │
-         ▼                 ▼                 ▼
-   ┌─────────┐      ┌──────────┐      ┌─────────┐
-   │ Pedidos │      │ Clientes │      │Produtos │
-   └────┬────┘      └────┬─────┘      └────┬────┘
-        │                │                   │
-        ▼                ▼                   ▼
-   [+ Novo]         [+ Novo]           [+ Novo]
-        │                │                   │
-        └────────────────┴──────────────────┬┘
-                                            │
-                                            ▼
-                                    ┌───────────────┐
-                                    │ Modal Wizard  │
-                                    │ (3 steps)     │
-                                    └───────┬───────┘
-                                            │
-                                            ▼
-                                      [Confirmar]
-                                            │
-                                            ▼
-                                    ┌───────────────┐
-                                    │ Tela Detalhes │
-                                    └───────┬───────┘
-                                            │
-                                    ┌───────┴───────┐
-                                    │               │
-                                    ▼               ▼
-                              [Editar]        [Voltar]
-                                    │               │
-                                    └───────┬───────┘
-                                            │
-                                            ▼
-                                    [Dashboard]
-```
-
----
-
-## Estados de Loading
-
-### {Onde há loading na feature}
-
-**1. Carregamento Inicial:**
-- **Onde:** {Primeira tela ao abrir}
-- **Componente:** `FluentSkeleton` ou `FluentProgress`
-- **Duração esperada:** {X ms}
-
-**2. Carregamento de Ação:**
-- **Onde:** {Ao submeter form, por exemplo}
-- **Componente:** `FluentButton` com `Loading="true"`
-- **Duração esperada:** {X ms}
-
-**3. Carregamento Incremental:**
-- **Onde:** {Infinite scroll, paginação}
-- **Componente:** `FluentProgress` no rodapé
-- **Duração esperada:** {X ms}
-
----
-
-## Validações e Feedback
-
-### Validações Client-Side
-
-| Campo | Validação | Mensagem de Erro | Componente |
-|-------|-----------|------------------|------------|
-| {Nome} | Required | "Campo obrigatório" | FluentTextField |
-| {Email} | Email format | "Email inválido" | FluentTextField |
-| {CPF} | CPF válido | "CPF inválido" | FluentTextField |
-
-### Validações Server-Side
-
-| Ação | Validação | Erro Possível | Como Mostra |
-|------|-----------|---------------|-------------|
-| Criar Pedido | Cliente ativo | "Cliente inativo" | FluentMessageBar |
-| Adicionar Produto | Estoque > 0 | "Sem estoque" | FluentDialog |
-
----
-
-## Checklist de Fluxos
-
-- [ ] Happy path documentado com todos os passos
-- [ ] Diagramas ASCII de cada fluxo
-- [ ] Edge cases identificados (erro, vazio, retry)
-- [ ] Fluxos alternativos mapeados
-- [ ] Loading states especificados
-- [ ] Validações client-side e server-side listadas
-- [ ] Mensagens de erro/sucesso definidas
-- [ ] Navegação entre telas clara
-- [ ] Tempo estimado de cada fluxo
-
----
-
-*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*
+# UI Flows - {{FEATURE_NAME_TITLE}}
+
+> Fluxos de usuário completos mostrando navegação, decisões e edge cases.
+> Documenta COMO o usuário se move pela feature do início ao fim.
+
+---
+
+## Fluxo 1: {Nome do Fluxo Principal}
+
+### Contexto
+
+**Trigger (Gatilho):**
+{O que inicia este fluxo? Ex: "Usuário clica em [+ Novo Pedido]"}
+
+**Pré-condições:**
+- {Condição 1 que deve ser verdadeira para iniciar o fluxo}
+- {Condição 2}
+
+**Objetivo:**
+{O que o usuário quer alcançar ao final deste fluxo?}
+
+---
+
+### Happy Path (Caminho Ideal)
+
+#### Passos
+
+**1. {Tela/Componente Inicial}**: {Ação do usuário}
+   - Sistema: {Resposta do sistema}
+   - UI: {Mudança visual}
+   - Navegação: {Para onde vai}
+
+**2. {Próxima Tela/Componente}**: {Próxima ação}
+   - Sistema: {Processamento backend}
+   - UI: {Feedback visual}
+   - Validação: {Regras aplicadas}
+
+**3. {Tela/Componente Final}**: {Ação de conclusão}
+   - Sistema: {Persistência/salvamento}
+   - UI: {Mensagem de sucesso}
+   - Navegação: {Retorna para onde}
+
+**Tempo estimado:** {X segundos/minutos para usuário completar}
+
+---
+
+### Diagrama de Fluxo (Happy Path)
+
+```
+┌─────────────────┐
+│  Tela Inicial   │
+│  [Dashboard]    │
+└────────┬────────┘
+         │
+         │ Clica [+ Novo Pedido]
+         ▼
+┌─────────────────┐
+│   Modal/Wizard  │
+│   Aberto        │
+└────────┬────────┘
+         │
+         │ ⟨Step 1⟩ Seleciona Cliente
+         ▼
+┌─────────────────┐
+│  Cliente        │
+│  Selecionado    │
+└────────┬────────┘
+         │
+         │ Clica [Próximo]
+         ▼
+┌─────────────────┐
+│  ⟨Step 2⟩       │
+│  Produtos       │
+└────────┬────────┘
+         │
+         │ Adiciona Produtos
+         │ Total Calculado
+         ▼
+┌─────────────────┐
+│  Lista de       │
+│  Produtos OK    │
+└────────┬────────┘
+         │
+         │ Clica [Próximo]
+         ▼
+┌─────────────────┐
+│  ⟨Step 3⟩       │
+│  Revisão        │
+└────────┬────────┘
+         │
+         │ Clica [Confirmar]
+         ▼
+┌─────────────────┐
+│  ✅ Pedido      │
+│  Criado!        │
+└────────┬────────┘
+         │
+         │ Toast "Sucesso!"
+         │ Navega para Detalhes
+         ▼
+┌─────────────────┐
+│  Tela Detalhes  │
+│  Pedido #12345  │
+└─────────────────┘
+```
+
+---
+
+### Edge Cases (Casos de Exceção)
+
+#### 1. {Nome do Edge Case}
+
+**Cenário:**
+{Descrição da situação excepcional}
+
+**Como o sistema lida:**
+```
+┌─────────────────┐
+│  Passo Normal   │
+└────────┬────────┘
+         │
+         │ ❌ {Erro/Condição}
+         ▼
+┌─────────────────┐
+│  Mensagem Erro  │
+│  FluentDialog   │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+[Tentar]  [Cancelar]
+Novamente
+    │         │
+    │         └──▶ [Volta Dashboard]
+    │
+    └──▶ [Repete Passo]
+```
+
+**UI:**
+- Componente: {FluentDialog, FluentMessageBar, etc}
+- Mensagem: "{Texto exato da mensagem}"
+- Ações disponíveis: {Botões/links}
+
+**Exemplo de código:**
+```razor
+@if (!string.IsNullOrEmpty(_error))
+{
+    <FluentMessageBar Intent="MessageIntent.Error">
+        @_error
+        <FluentButton OnClick="@Retry">Tentar Novamente</FluentButton>
+    </FluentMessageBar>
+}
+```
+
+---
+
+#### 2. {Outro Edge Case}
+
+{Repita a estrutura acima}
+
+---
+
+### Fluxos Alternativos
+
+#### Alt 1: {Nome do Fluxo Alternativo}
+
+**Diverge em:** {Em qual passo do happy path este fluxo se ramifica}
+
+**Condição:** {O que causa a divergência}
+
+**Passos:**
+1. {Passo alternativo 1}
+2. {Passo alternativo 2}
+3. {Convergência de volta ao happy path OU conclusão diferente}
+
+**Diagrama:**
+```
+[Happy Path]
+     │
+     ├─{Condição}──▶ [Fluxo Alt]
+     │                    │
+     │                    └──▶ [Converge]
+     ▼
+[Continua...]
+```
+
+---
+
+## Fluxo 2: {Segundo Fluxo Importante}
+
+{Repita toda a estrutura acima para cada fluxo principal}
+
+---
+
+## Interações Comuns (Micro-Fluxos)
+
+### {Ação Rápida - Ex: "Buscar Item"}
+
+**Trigger:** {Usuário digita na search bar}
+
+**Fluxo:**
+```
+[Input vazio] ──▶ [Usuário digita] ──▶ [Debounce 300ms] ──▶ [API Call]
+                                                                  │
+                                                                  ▼
+                                                            [Resultados]
+                                                                  │
+                                                    ┌─────────────┴──────────┐
+                                                    ▼                        ▼
+                                             [Tem Resultados]         [Vazio]
+                                                    │                        │
+                                                    ▼                        ▼
+                                             [Mostra Lista]    [Mostra "Não encontrado"]
+```
+
+**Componente:** `FluentAutocomplete`
+
+**Código:**
+```razor
+<FluentAutocomplete TItem="Item"
+                   SearchAsync="@SearchItemsAsync"
+                   Placeholder="Buscar item..."
+                   MinLength="2"
+                   Debounce="300">
+    <ItemTemplate Context="item">
+        @item.Name
+    </ItemTemplate>
+</FluentAutocomplete>
+```
+
+---
+
+## Mapa de Navegação Completo
+
+Visão geral de TODAS as telas e como se conectam:
+
+```
+                    ┌──────────────┐
+                    │  Dashboard   │
+                    └──────┬───────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+         ▼                 ▼                 ▼
+   ┌─────────┐      ┌──────────┐      ┌─────────┐
+   │ Pedidos │      │ Clientes │      │Produtos │
+   └────┬────┘      └────┬─────┘      └────┬────┘
+        │                │                   │
+        ▼                ▼                   ▼
+   [+ Novo]         [+ Novo]           [+ Novo]
+        │                │                   │
+        └────────────────┴──────────────────┬┘
+                                            │
+                                            ▼
+                                    ┌───────────────┐
+                                    │ Modal Wizard  │
+                                    │ (3 steps)     │
+                                    └───────┬───────┘
+                                            │
+                                            ▼
+                                      [Confirmar]
+                                            │
+                                            ▼
+                                    ┌───────────────┐
+                                    │ Tela Detalhes │
+                                    └───────┬───────┘
+                                            │
+                                    ┌───────┴───────┐
+                                    │               │
+                                    ▼               ▼
+                              [Editar]        [Voltar]
+                                    │               │
+                                    └───────┬───────┘
+                                            │
+                                            ▼
+                                    [Dashboard]
+```
+
+---
+
+## Estados de Loading
+
+### {Onde há loading na feature}
+
+**1. Carregamento Inicial:**
+- **Onde:** {Primeira tela ao abrir}
+- **Componente:** `FluentSkeleton` ou `FluentProgress`
+- **Duração esperada:** {X ms}
+
+**2. Carregamento de Ação:**
+- **Onde:** {Ao submeter form, por exemplo}
+- **Componente:** `FluentButton` com `Loading="true"`
+- **Duração esperada:** {X ms}
+
+**3. Carregamento Incremental:**
+- **Onde:** {Infinite scroll, paginação}
+- **Componente:** `FluentProgress` no rodapé
+- **Duração esperada:** {X ms}
+
+---
+
+## Validações e Feedback
+
+### Validações Client-Side
+
+| Campo | Validação | Mensagem de Erro | Componente |
+|-------|-----------|------------------|------------|
+| {Nome} | Required | "Campo obrigatório" | FluentTextField |
+| {Email} | Email format | "Email inválido" | FluentTextField |
+| {CPF} | CPF válido | "CPF inválido" | FluentTextField |
+
+### Validações Server-Side
+
+| Ação | Validação | Erro Possível | Como Mostra |
+|------|-----------|---------------|-------------|
+| Criar Pedido | Cliente ativo | "Cliente inativo" | FluentMessageBar |
+| Adicionar Produto | Estoque > 0 | "Sem estoque" | FluentDialog |
+
+---
+
+## Checklist de Fluxos
+
+- [ ] Happy path documentado com todos os passos
+- [ ] Diagramas ASCII de cada fluxo
+- [ ] Edge cases identificados (erro, vazio, retry)
+- [ ] Fluxos alternativos mapeados
+- [ ] Loading states especificados
+- [ ] Validações client-side e server-side listadas
+- [ ] Mensagens de erro/sucesso definidas
+- [ ] Navegação entre telas clara
+- [ ] Tempo estimado de cada fluxo
+
+---
+
+*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*