@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

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

@@ -1,276 +1,362 @@
-# UI Components - {{FEATURE_NAME_TITLE}}
-
-> Especificação dos componentes Fluent UI / MudBlazor utilizados nesta feature.
-> Mapeia cada elemento visual para um componente concreto da biblioteca escolhida.
-
----
-
-## Decisão de Biblioteca UI
-
-### Biblioteca Escolhida: {Fluent UI Blazor | MudBlazor | Híbrida}
-
-**Justificativa:**
-{Por que esta biblioteca foi escolhida para ESTA feature específica?}
-
-**Critérios de decisão:**
-- ✅ **{Critério 1}**: {Explicação}
-- ✅ **{Critério 2}**: {Explicação}
-- ⚠️ **{Trade-off}**: {O que foi sacrificado e por quê}
-
-**Referência ADR**: Ver `decisions.md` - ADR-{número}: {Título da decisão}
-
----
-
-## Componentes Mapeados
-
-### {Nome do Elemento Visual}
-
-**Biblioteca**: {Fluent UI | MudBlazor}
-**Componente**: `{ComponentName}`
-
-#### Props Principais
-```csharp
-<{ComponentName}
-    Prop1="{valor ou @binding}"
-    Prop2="{valor ou @binding}"
-    Prop3="{valor ou @binding}"
-    OnClick="@{Handler}" />
-```
-
-#### Propriedades Detalhadas
-| Prop | Tipo | Valor | Descrição |
-|------|------|-------|-----------|
-| `Prop1` | `string` | `"{valor}"` | {Para que serve} |
-| `Prop2` | `bool` | `true` | {Para que serve} |
-| `Prop3` | `EventCallback` | `@Handler` | {Quando dispara} |
-
-#### Estados
-
-**1. Default (Estado Inicial)**
-```razor
-<{ComponentName}
-    Appearance="Appearance.Neutral"
-    Disabled="false">
-    {Conteúdo padrão}
-</{ComponentName}>
-```
-
-**2. Loading**
-```razor
-@if (_isLoading)
-{
-    <FluentSkeleton Width="100%" Height="40px" />
-    <!-- OU -->
-    <FluentProgress />
-}
-else
-{
-    <{ComponentName} ... />
-}
-```
-
-**3. Error**
-```razor
-@if (!string.IsNullOrEmpty(_error))
-{
-    <FluentMessageBar Intent="MessageIntent.Error">
-        @_error
-    </FluentMessageBar>
-}
-<{ComponentName} ... />
-```
-
-**4. Empty (Sem Dados)**
-```razor
-@if (!_items.Any())
-{
-    <FluentStack Orientation="Orientation.Vertical" HorizontalAlignment="HorizontalAlignment.Center">
-        <FluentLabel>Nenhum item encontrado</FluentLabel>
-        <FluentButton Appearance="Appearance.Accent" OnClick="@Create">
-            Criar Novo
-        </FluentButton>
-    </FluentStack>
-}
-```
-
-**5. Success (Feedback Positivo)**
-```razor
-<FluentToast Intent="ToastIntent.Success" Timeout="3000">
-    Operação realizada com sucesso!
-</FluentToast>
-```
-
-#### Eventos
-
-| Evento | Handler | Ação |
-|--------|---------|------|
-| `OnClick` | `HandleClick` | {O que acontece ao clicar} |
-| `OnChange` | `HandleChange` | {O que acontece ao mudar valor} |
-| `OnSubmit` | `HandleSubmit` | {O que acontece ao submeter} |
-
-#### Exemplo de Código Completo
-
-```razor
-<!-- {Nome do Componente}.razor -->
-<{ComponentName}
-    Items="@_items"
-    Loading="@_isLoading"
-    OnClick="@HandleClick">
-
-    @if (_isLoading)
-    {
-        <FluentProgress />
-    }
-    else
-    {
-        @foreach (var item in _items)
-        {
-            <{ChildComponent} Data="@item" />
-        }
-    }
-</{ComponentName}>
-
-@code {
-    [Parameter] public List<ItemType> Items { get; set; } = new();
-
-    private bool _isLoading;
-    private string? _error;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await LoadDataAsync();
-    }
-
-    private async Task LoadDataAsync()
-    {
-        _isLoading = true;
-        try
-        {
-            _items = await _service.GetItemsAsync();
-        }
-        catch (Exception ex)
-        {
-            _error = ex.Message;
-        }
-        finally
-        {
-            _isLoading = false;
-        }
-    }
-
-    private async Task HandleClick(ItemType item)
-    {
-        // Ação ao clicar
-    }
-}
-```
-
-#### Acessibilidade
-
-**ARIA Attributes:**
-- `role="{role}"`: {Propósito}
-- `aria-label="{label}"`: {Descrição para screen readers}
-- `aria-describedby="{id}"`: {Descrição adicional}
-
-**Keyboard Navigation:**
-- `Tab`: {Foca no elemento}
-- `Enter/Space`: {Ativa o elemento}
-- `Escape`: {Cancela/fecha}
-- `Arrow Keys`: {Navega entre opções}
-
-**Focus Management:**
-- **Foco inicial**: {Onde o foco deve ir quando o componente aparece}
-- **Focus trap**: {Se aplicável, como manter o foco dentro do componente (modals)}
-
----
-
-## {Próximo Componente}
-
-{Repita a estrutura acima para cada componente}
-
----
-
-## Componentes Customizados
-
-### {Nome do Componente Custom}
-
-Se você precisar criar um componente que NÃO existe em Fluent UI ou MudBlazor:
-
-**Composição:**
-```razor
-<!-- Components/{ComponentName}.razor -->
-<div class="custom-component">
-    <FluentCard>
-        <FluentStack Orientation="Orientation.Vertical">
-            <!-- Composição de componentes existentes -->
-        </FluentStack>
-    </FluentCard>
-</div>
-
-@code {
-    // Lógica do componente
-}
-```
-
-**Quando usar:**
-- {Situação 1 que justifica componente custom}
-- {Situação 2}
-
----
-
-## Packages Necessários
-
-### Fluent UI Blazor
-```xml
-<PackageReference Include="Microsoft.FluentUI.AspNetCore.Components" Version="4.0.0" />
-```
-
-```csharp
-// Program.cs
-builder.Services.AddFluentUIComponents();
-```
-
-```razor
-// _Imports.razor
-@using Microsoft.FluentUI.AspNetCore.Components
-```
-
-### MudBlazor (se híbrido)
-```xml
-<PackageReference Include="MudBlazor" Version="6.11.0" />
-```
-
-```csharp
-// Program.cs
-builder.Services.AddMudServices();
-```
-
-```razor
-// _Imports.razor
-@using MudBlazor
-```
-
----
-
-## Mapa de Componentes
-
-Resumo visual de quais componentes são usados onde:
-
-| Tela/Feature | Componente | Biblioteca | Complexidade |
-|--------------|------------|------------|--------------|
-| {Tela 1} | FluentDataGrid | Fluent UI | Média |
-| {Tela 1} | FluentCard | Fluent UI | Baixa |
-| {Tela 2} | MudChart | MudBlazor | Alta |
-| {Tela 2} | FluentDialog | Fluent UI | Média |
-
----
-
-## Referências
-
-- [Fluent UI Components](https://www.fluentui-blazor.net/Components)
-- [MudBlazor Components](https://mudblazor.com/components/list)
-- [Guia Fluent UI Setup](../.morph/standards/fluent-ui-setup.md)
-
----
-
-*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*
+# UI Components - {{FEATURE_NAME_TITLE}}
+
+> Especificação dos componentes Fluent UI / MudBlazor utilizados nesta feature.
+> Mapeia cada elemento visual para um componente concreto da biblioteca escolhida.
+
+---
+
+## Decisão de Biblioteca UI
+
+### Biblioteca Escolhida: {Fluent UI Blazor | MudBlazor | Híbrida}
+
+**Justificativa:**
+{Por que esta biblioteca foi escolhida para ESTA feature específica?}
+
+**Critérios de decisão:**
+- ✅ **{Critério 1}**: {Explicação}
+- ✅ **{Critério 2}**: {Explicação}
+- ⚠️ **{Trade-off}**: {O que foi sacrificado e por quê}
+
+**Referência ADR**: Ver `decisions.md` - ADR-{número}: {Título da decisão}
+
+---
+
+## Componentes Mapeados
+
+### {Nome do Elemento Visual}
+
+**Biblioteca**: {Fluent UI | MudBlazor}
+**Componente**: `{ComponentName}`
+
+#### Props Principais
+```csharp
+<{ComponentName}
+    Prop1="{valor ou @binding}"
+    Prop2="{valor ou @binding}"
+    Prop3="{valor ou @binding}"
+    OnClick="@{Handler}" />
+```
+
+#### Propriedades Detalhadas
+| Prop | Tipo | Valor | Descrição |
+|------|------|-------|-----------|
+| `Prop1` | `string` | `"{valor}"` | {Para que serve} |
+| `Prop2` | `bool` | `true` | {Para que serve} |
+| `Prop3` | `EventCallback` | `@Handler` | {Quando dispara} |
+
+#### Estados
+
+**1. Default (Estado Inicial)**
+```razor
+<{ComponentName}
+    Appearance="Appearance.Neutral"
+    Disabled="false">
+    {Conteúdo padrão}
+</{ComponentName}>
+```
+
+**2. Loading**
+```razor
+@if (_isLoading)
+{
+    <FluentSkeleton Width="100%" Height="40px" />
+    <!-- OU -->
+    <FluentProgress />
+}
+else
+{
+    <{ComponentName} ... />
+}
+```
+
+**3. Error**
+```razor
+@if (!string.IsNullOrEmpty(_error))
+{
+    <FluentMessageBar Intent="MessageIntent.Error">
+        @_error
+    </FluentMessageBar>
+}
+<{ComponentName} ... />
+```
+
+**4. Empty (Sem Dados)**
+```razor
+@if (!_items.Any())
+{
+    <FluentStack Orientation="Orientation.Vertical" HorizontalAlignment="HorizontalAlignment.Center">
+        <FluentLabel>Nenhum item encontrado</FluentLabel>
+        <FluentButton Appearance="Appearance.Accent" OnClick="@Create">
+            Criar Novo
+        </FluentButton>
+    </FluentStack>
+}
+```
+
+**5. Success (Feedback Positivo)**
+```razor
+<FluentToast Intent="ToastIntent.Success" Timeout="3000">
+    Operação realizada com sucesso!
+</FluentToast>
+```
+
+#### Eventos
+
+| Evento | Handler | Ação |
+|--------|---------|------|
+| `OnClick` | `HandleClick` | {O que acontece ao clicar} |
+| `OnChange` | `HandleChange` | {O que acontece ao mudar valor} |
+| `OnSubmit` | `HandleSubmit` | {O que acontece ao submeter} |
+
+#### Exemplo de Código Completo
+
+```razor
+<!-- {Nome do Componente}.razor -->
+<{ComponentName}
+    Items="@_items"
+    Loading="@_isLoading"
+    OnClick="@HandleClick">
+
+    @if (_isLoading)
+    {
+        <FluentProgress />
+    }
+    else
+    {
+        @foreach (var item in _items)
+        {
+            <{ChildComponent} Data="@item" />
+        }
+    }
+</{ComponentName}>
+
+@code {
+    [Parameter] public List<ItemType> Items { get; set; } = new();
+
+    private bool _isLoading;
+    private string? _error;
+
+    protected override async Task OnInitializedAsync()
+    {
+        await LoadDataAsync();
+    }
+
+    private async Task LoadDataAsync()
+    {
+        _isLoading = true;
+        try
+        {
+            _items = await _service.GetItemsAsync();
+        }
+        catch (Exception ex)
+        {
+            _error = ex.Message;
+        }
+        finally
+        {
+            _isLoading = false;
+        }
+    }
+
+    private async Task HandleClick(ItemType item)
+    {
+        // Ação ao clicar
+    }
+}
+```
+
+#### Acessibilidade
+
+**ARIA Attributes:**
+- `role="{role}"`: {Propósito}
+- `aria-label="{label}"`: {Descrição para screen readers}
+- `aria-describedby="{id}"`: {Descrição adicional}
+
+**Keyboard Navigation:**
+- `Tab`: {Foca no elemento}
+- `Enter/Space`: {Ativa o elemento}
+- `Escape`: {Cancela/fecha}
+- `Arrow Keys`: {Navega entre opções}
+
+**Focus Management:**
+- **Foco inicial**: {Onde o foco deve ir quando o componente aparece}
+- **Focus trap**: {Se aplicável, como manter o foco dentro do componente (modals)}
+
+---
+
+## {Próximo Componente}
+
+{Repita a estrutura acima para cada componente}
+
+---
+
+## Componentes Customizados
+
+### {Nome do Componente Custom}
+
+Se você precisar criar um componente que NÃO existe em Fluent UI ou MudBlazor:
+
+**Composição:**
+```razor
+<!-- Components/{ComponentName}.razor -->
+<div class="custom-component">
+    <FluentCard>
+        <FluentStack Orientation="Orientation.Vertical">
+            <!-- Composição de componentes existentes -->
+        </FluentStack>
+    </FluentCard>
+</div>
+
+@code {
+    // Lógica do componente
+}
+```
+
+**Quando usar:**
+- {Situação 1 que justifica componente custom}
+- {Situação 2}
+
+---
+
+## Packages Necessários
+
+### Fluent UI Blazor
+```xml
+<PackageReference Include="Microsoft.FluentUI.AspNetCore.Components" Version="4.0.0" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddFluentUIComponents();
+```
+
+```razor
+// _Imports.razor
+@using Microsoft.FluentUI.AspNetCore.Components
+```
+
+### MudBlazor (se híbrido)
+```xml
+<PackageReference Include="MudBlazor" Version="6.11.0" />
+```
+
+```csharp
+// Program.cs
+builder.Services.AddMudServices();
+```
+
+```razor
+// _Imports.razor
+@using MudBlazor
+```
+
+---
+
+## Mapa de Componentes
+
+Resumo visual de quais componentes são usados onde:
+
+| Tela/Feature | Componente | Biblioteca | Complexidade |
+|--------------|------------|------------|--------------|
+| {Tela 1} | FluentDataGrid | Fluent UI | Média |
+| {Tela 1} | FluentCard | Fluent UI | Baixa |
+| {Tela 2} | MudChart | MudBlazor | Alta |
+| {Tela 2} | FluentDialog | Fluent UI | Média |
+
+---
+
+---
+
+## Checklist de Componentes CSS
+
+> **IMPORTANTE:** Liste TODOS os componentes CSS necessarios ANTES de implementar.
+> Use `morph-spec validate-css` para validar que todas as classes existem.
+
+### Componentes CSS Novos (a criar)
+
+Classes CSS customizadas que precisam ser criadas no `design-system.css`:
+
+- [ ] `.{page-prefix}-{component}` - {Descricao do componente}
+- [ ] `.{page-prefix}-{element}` - {Descricao do elemento}
+
+**Exemplo:**
+```markdown
+- [ ] `.home-hero` - Container do hero section da home
+- [ ] `.home-features` - Grid de features
+- [ ] `.checkout-form` - Container do formulario de checkout
+- [ ] `.checkout-summary` - Card de resumo do pedido
+- [ ] `.modal-overlay` - Overlay escuro para modais customizados
+- [ ] `.modal-container` - Container do modal com animacao
+- [ ] `.card-premium` - Card com glow e borda especial
+- [ ] `.button-shimmer` - Botao com efeito shimmer
+```
+
+### Componentes CSS Existentes (reutilizar)
+
+Classes que ja existem no projeto (design-system.css ou bibliotecas):
+
+- [x] `.{existing-class}` - {Onde esta definida}
+
+**Exemplo:**
+```markdown
+- [x] `.page-layout` - design-system.css (estrutura padrao)
+- [x] `.tip-box` - design-system.css (caixa de dica)
+- [x] `FluentCard` - Fluent UI Blazor (componente)
+```
+
+### Variaveis CSS Novas
+
+Variaveis CSS customizadas necessarias:
+
+- [ ] `--{project}-{variable-name}` - {Descricao e valor}
+
+**Exemplo:**
+```markdown
+- [ ] `--fishart-primary` - Cor primaria (#FF6B35)
+- [ ] `--fishart-shadow-glow` - Sombra com glow (0 0 20px rgba(255, 107, 53, 0.3))
+- [ ] `--fishart-gradient-hero` - Gradiente do hero (linear-gradient(...))
+- [ ] `--fishart-transition-bounce` - Transicao com bounce (cubic-bezier(...))
+```
+
+### Animacoes CSS Novas
+
+Keyframes e classes de animacao necessarias:
+
+- [ ] `@keyframes {animation-name}` - {Descricao}
+- [ ] `.animate-{name}` - Classe que aplica a animacao
+
+**Exemplo:**
+```markdown
+- [ ] `@keyframes slideInUp` - Entrada de baixo para cima
+- [ ] `.animate-slideInUp` - Aplica slideInUp com 0.5s ease
+- [ ] `@keyframes scaleIn` - Zoom in suave
+- [ ] `.animate-scaleIn` - Aplica scaleIn com 0.3s ease
+- [ ] `.stagger-1` a `.stagger-5` - Delays para animacoes em sequencia
+```
+
+### Validacao Pre-Implementacao
+
+Antes de iniciar FASE 5 (IMPLEMENT), validar:
+
+```bash
+# Criar todas as classes listadas acima no design-system.css
+
+# Validar que nenhuma classe esta faltando
+morph-spec validate-css src/MyApp.Web
+
+# Output esperado: "All CSS classes are properly defined!"
+```
+
+---
+
+## Referências
+
+- [Fluent UI Components](https://www.fluentui-blazor.net/Components)
+- [MudBlazor Components](https://mudblazor.com/components/list)
+- [Guia Fluent UI Blazor](../../framework/standards/fluent-ui-blazor.md)
+- [CSS Naming Convention](../../framework/standards/css-naming.md)
+- [CSS Animations](../../framework/standards/css-animations.md)
+
+---
+
+*Template MORPH-SPEC v2.2.0 by Polymorphism Tech*