@polymorphism-tech/morph-spec 4.11.1 → 4.13.0

package/framework/standards/frontend/blazor/pitfalls.md

@@ -1,198 +0,0 @@
-# Blazor Common Pitfalls & Solutions
-
-> **Scope:** blazor-azure
-> **Layer:** 2 (on keyword)
-> **Keywords:** blazor, dbcontext, jsruntime, rendermode, pitfalls, errors
-> **Load When:** blazor work
-
-Production-tested pitfalls from real Blazor Server projects.
-
-> **Ref:** `blazor-lifecycle.md`, `blazor-state.md`, `html-to-blazor.md`
-
----
-
-## CRITICAL: DI Pattern (Component → API → Handler)
-
-| Wrong | Right |
-|-------|-------|
-| `[Inject] IProcessCommand Command` | `[Inject] HttpClient Http` |
-| Direct Application layer injection | HttpClient → Controller → MediatR → Handler |
-
-```csharp
-// Component
-[Inject] HttpClient Http { get; set; }
-[Inject] NavigationManager Nav { get; set; }
-
-private async Task HandleUpload()
-{
-    var uri = new Uri(new Uri(Nav.BaseUri), "/api/upload");
-    var response = await Http.PostAsync(uri, content);
-    if (response.IsSuccessStatusCode)
-        Nav.NavigateTo($"/processing/{await response.Content.ReadFromJsonAsync<UploadResponse>().JobId}");
-}
-
-// Program.cs
-builder.Services.AddHttpClient();
-builder.Services.AddHttpContextAccessor();
-builder.Services.AddScoped(sp => {
-    var client = sp.GetRequiredService<IHttpClientFactory>().CreateClient();
-    var req = sp.GetRequiredService<IHttpContextAccessor>().HttpContext?.Request;
-    if (req != null) client.BaseAddress = new Uri($"{req.Scheme}://{req.Host}");
-    return client;
-});
-```
-
----
-
-## Common Configuration Errors
-
-| Issue | Fix |
-|-------|-----|
-| CSS loads but doesn't apply | Add `app.UseStaticFiles()` BEFORE routing |
-| "Cannot pass Body parameter" | Remove `@rendermode` from layouts (only on pages) |
-| JSRuntime crashes | Use in `OnAfterRenderAsync(firstRender)`, NOT `OnInitializedAsync` |
-
-```csharp
-// Correct middleware order
-app.UseHttpsRedirection();
-app.UseStaticFiles();  // BEFORE routing
-app.UseAntiforgery();
-app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
-```
-
----
-
-## File Upload Patterns
-
-### IBrowserFile: Read Once, Store Bytes
-
-`IBrowserFile` loses reference after re-render. Always read immediately and store bytes.
-
-```csharp
-private byte[]? _fileBytes;
-private string? _previewUrl;
-
-private async Task HandleFile(InputFileChangeEventArgs e)
-{
-    var file = e.File;
-    var ext = Path.GetExtension(file.Name).ToLowerInvariant();
-    if (!new[] { ".jpg", ".png" }.Contains(ext)) return;
-    if (file.Size > 10_000_000) return; // 10MB
-
-    _fileBytes = new byte[file.Size];
-    await file.OpenReadStream(10_000_000).ReadExactlyAsync(_fileBytes);
-    _previewUrl = $"data:{file.ContentType};base64,{Convert.ToBase64String(_fileBytes)}";
-}
-
-private async Task Upload()
-{
-    using var stream = new MemoryStream(_fileBytes!);
-    var content = new StreamContent(stream);
-    await Http.PostAsync("/api/upload", content);
-}
-```
-
-**Critical:** Blazor default max = 512KB. Always specify `maxAllowedSize`.
-
-### Stream-based Contract (IBrowserFile ↔ IFormFile)
-
-```csharp
-// Universal contract
-public record UploadRequest(Stream Stream, string FileName, string ContentType);
-
-// Blazor: file.OpenReadStream(maxSize)
-// API: formFile.OpenReadStream()
-```
-
----
-
-## Razor Syntax Errors
-
-| Error | Wrong | Right |
-|-------|-------|-------|
-| RZ9986 | `Style="animation-delay: @(0.05 * i)s;"` | `Style="@($"animation-delay: {0.05 * i}s;")"` |
-| CS9034 | `required int Percent => ...` | `int Percent => ...` (no required on computed) |
-| CS0104 | Duplicate enums in Domain + Application | Single enum in Domain, `using` elsewhere |
-
----
-
-## JS Interop
-
-```razor
-<div @onclick="TriggerFileInput">Click to upload</div>
-<InputFile id="fileInput" style="display:none" OnChange="HandleFile" />
-
-@code {
-    [Inject] IJSRuntime JS { get; set; }
-    async Task TriggerFileInput() => await JS.InvokeVoidAsync("eval", "document.getElementById('fileInput').click()");
-}
-```
-
----
-
-## Quick Debugging
-
-| Symptom | Check |
-|---------|-------|
-| CSS not applying | `UseStaticFiles()` present? Hard refresh (Ctrl+Shift+R) |
-| Component not interactive | `@rendermode InteractiveServer` on page (NOT layout) |
-| JSRuntime crash | Called in `OnAfterRenderAsync(firstRender)` |
-| DI "cannot provide value" | HttpClient pattern configured? Service registered? |
-| State lost on navigation | `blazor-state.md` Persist+Reload pattern |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
-
----
-
-## Code Review Checklist
-
-Use this checklist during code review for common Blazor pitfalls:
-
-### Fluent UI / MudBlazor Components
-
-#### FluentDialog
-- [ ] **`Hidden="true"` explicitly set on FluentDialog?**
-- [ ] **Modal state controlled by bool variable, not just dialog ref?**
-
-#### Icons
-- [ ] **Icons use correct size classes? (Size20, Size24, Size28, Size32, Size48)**
-  - Size12, Size14, Size16 do NOT exist!
-- [ ] **Icon namespace alias used?** (`@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons`)
-- [ ] **Icon syntax is correct?** (`<FluentIcon Value="@(new Icons.Regular.Size24.Home())" />`)
-
-#### Toast Service
-- [ ] **Toast methods are synchronous (not async)?**
-  - ✅ `ToastService.ShowSuccess("Message")`
-  - ❌ `await ToastService.ShowSuccessAsync("Message")`
-
-### Razor Syntax
-
-#### String Interpolation
-- [ ] **Complex attribute interpolation uses `@($"...")`?**
-  - ✅ `<div style="@($"animation-delay: {delay}s;")">`
-  - ❌ `<div style="animation-delay: @(delay)s;">` (causes RZ9986)
-
-### Error Handling
-- [ ] **Try-catch around async operations with user feedback?**
-- [ ] **Loading state shown during async operations?**
-- [ ] **Error messages are user-friendly, not stack traces?**
-
-### Security
-- [ ] **Input validation on all user inputs?**
-- [ ] **No SQL injection vulnerabilities (using parameterized queries)?**
-
-### Quick Reference: Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| JSRuntime in OnInitializedAsync | Move to OnAfterRenderAsync |
-| Reading IBrowserFile twice | Store bytes on first read |
-| Scoped DbContext in Task.Run | Use IDbContextFactory |
-| forceLoad navigation | Use normal navigation + persist state |
-| ToastService.ShowSuccessAsync | Use synchronous ShowSuccess |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/blazor/state.md

@@ -1,191 +0,0 @@
-# Blazor Server: Session State Management
-
-> **Scope:** blazor-azure
-> **Layer:** 2 (on keyword)
-> **Keywords:** blazor, state, cascading, parameter, session, circuit
-> **Load When:** blazor work
-
-## The Problem
-
-In Blazor Server, `Scoped` services are tied to the **SignalR circuit**, NOT the user session. Circuit recreated on navigation/refresh = **state lost**.
-
-```csharp
-// WRONG: Assuming scoped = session
-SessionState.CurrentOrderId = orderId;
-NavigationManager.NavigateTo("/page2");
-// page2: SessionState.CurrentOrderId == null (new circuit)
-```
-
-**Solution:** Browser cookie (SessionId) → Middleware → DB lookup → `SessionState.LoadFrom(entity)` on each page init.
-
----
-
-## Implementation
-
-### SessionState Service
-
-```csharp
-public class SessionState
-{
-    public Guid? CurrentOrderId { get; set; }
-    public string? UserPreference { get; set; }
-    public Dictionary<string, object> CustomData { get; set; } = new();
-    public bool IsLoaded { get; private set; }
-    public string? SessionId { get; private set; }
-
-    public void LoadFrom(UserSession entity)
-    {
-        if (entity == null) return;
-        SessionId = entity.SessionId;
-        CurrentOrderId = entity.CurrentOrderId;
-        UserPreference = entity.UserPreference;
-        if (!string.IsNullOrEmpty(entity.CustomDataJson))
-            CustomData = JsonSerializer.Deserialize<Dictionary<string, object>>(entity.CustomDataJson) ?? new();
-        IsLoaded = true;
-    }
-
-    public UserSession ToEntity() => new()
-    {
-        SessionId = SessionId ?? Guid.NewGuid().ToString(),
-        CurrentOrderId = CurrentOrderId,
-        UserPreference = UserPreference,
-        CustomDataJson = JsonSerializer.Serialize(CustomData),
-        LastAccessedAt = DateTime.UtcNow
-    };
-}
-```
-
-### Repository
-
-```csharp
-public interface ISessionRepository
-{
-    Task<UserSession?> GetBySessionIdAsync(string sessionId);
-    Task SaveAsync(UserSession session);
-    Task DeleteAsync(string sessionId);
-    Task CleanupExpiredAsync(TimeSpan maxAge);
-}
-```
-
-### Session Middleware
-
-```csharp
-public class SessionMiddleware(RequestDelegate next)
-{
-    private const string CookieName = "X-Session-Id";
-    public async Task InvokeAsync(HttpContext context)
-    {
-        var sessionId = context.Request.Cookies[CookieName];
-        if (string.IsNullOrEmpty(sessionId))
-        {
-            sessionId = Guid.NewGuid().ToString();
-            context.Response.Cookies.Append(CookieName, sessionId, new CookieOptions
-            { HttpOnly = true, Secure = true, SameSite = SameSiteMode.Strict, Expires = DateTimeOffset.UtcNow.AddDays(30) });
-        }
-        context.Items["SessionId"] = sessionId;
-        await next(context);
-    }
-}
-```
-
-### Base Component (DRY Pattern)
-
-```csharp
-public abstract class SessionAwareComponent : ComponentBase
-{
-    [Inject] protected SessionState Session { get; set; } = default!;
-    [Inject] protected ISessionRepository SessionRepository { get; set; } = default!;
-    [Inject] protected IHttpContextAccessor HttpContextAccessor { get; set; } = default!;
-    protected string? SessionId => HttpContextAccessor.HttpContext?.Items["SessionId"] as string;
-
-    protected override async Task OnInitializedAsync()
-    {
-        await EnsureSessionLoadedAsync();
-        await OnSessionInitializedAsync();
-    }
-
-    protected async Task EnsureSessionLoadedAsync()
-    {
-        if (!Session.IsLoaded && !string.IsNullOrEmpty(SessionId))
-        {
-            var entity = await SessionRepository.GetBySessionIdAsync(SessionId);
-            if (entity != null) Session.LoadFrom(entity);
-        }
-    }
-
-    protected async Task SaveSessionAsync()
-    {
-        if (string.IsNullOrEmpty(SessionId)) return;
-        var entity = Session.ToEntity();
-        entity.SessionId = SessionId;
-        await SessionRepository.SaveAsync(entity);
-    }
-
-    protected virtual Task OnSessionInitializedAsync() => Task.CompletedTask;
-}
-```
-
-**Usage:** `@inherits SessionAwareComponent` → override `OnSessionInitializedAsync()`.
-
-### Registration
-
-```csharp
-// Program.cs
-builder.Services.AddScoped<SessionState>();
-builder.Services.AddScoped<ISessionRepository, SessionRepository>();
-app.UseMiddleware<SessionMiddleware>(); // BEFORE UseRouting
-```
-
----
-
-## Anti-Patterns
-
-| Wrong | Right |
-|-------|-------|
-| Trusting scoped state across pages | Always persist before navigating |
-| Not checking `IsLoaded` | Call `EnsureSessionLoadedAsync()` first |
-| Using `forceLoad: true` | Causes full page reload = new circuit = lost state |
-| Storing sensitive data | Never put passwords/tokens in session state |
-
----
-
-## Checklist
-
-- [ ] `SessionState` with `LoadFrom()`/`ToEntity()`/`IsLoaded`
-- [ ] `UserSession` entity + `ISessionRepository`
-- [ ] `SessionMiddleware` with HttpOnly + Secure + SameSite cookie
-- [ ] Middleware registered BEFORE routing in Program.cs
-- [ ] `SessionAwareComponent` base class for DRY
-- [ ] Session cleanup scheduled for expired sessions
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
-
----
-
-## Code Review Checklist
-
-Use this checklist during code review for Blazor state management:
-
-### Session State
-
-- [ ] **SessionState checked for `IsLoaded` before use?**
-- [ ] **SessionState has `LoadFrom()` method implemented?**
-- [ ] **Critical state is persisted to database on changes?**
-- [ ] **No reliance on scoped state surviving navigation?**
-
-### Navigation
-
-- [ ] **`forceLoad: true` is avoided unless absolutely necessary?**
-- [ ] **If `forceLoad` is used, state is persisted BEFORE navigation?**
-- [ ] **Deep links work correctly (state loaded from DB)?**
-
-### Security
-
-- [ ] **No sensitive data stored in SessionState (passwords, tokens)?**
-- [ ] **Session cookie is HttpOnly and Secure?**
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/design-system/aesthetic-direction.md

@@ -1,213 +0,0 @@
-# Aesthetic Direction
-
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** design, aesthetic, typography, color, motion, identity, visual
-> **Load When:** phase-uiux
-
-## Design Thinking Methodology
-
-Antes de qualquer especificação técnica, responder 4 perguntas para definir direção estética:
-
-1. **Purpose** — Que problema resolve? Quem usa? Qual o contexto profissional?
-2. **Tone** — Qual direção? (ver tabela Aesthetic Directions abaixo)
-3. **Differentiation** — Qual o 1 elemento memorável desta interface?
-4. **Constraints** — Framework, performance budget, brand guidelines existentes
-
-**CRITICAL:** Commitar à direção ANTES das specs técnicas. Documentar em `ui-design-system.md`
-na seção `## Aesthetic Direction` usando o template no final deste standard.
-
----
-
-## Aesthetic Directions (Enterprise-Adapted)
-
-| Direction | Feel | Typography | Color | Motion |
-|-----------|------|-----------|-------|--------|
-| **Minimal Refined** | Luxuoso, silencioso, preciso | Serif elegante + sans leve | Monocromático + 1 accent sharp | Transitions suaves, sem floreios |
-| **Editorial** | Magazine profissional, opinionado | Display forte + body serifado | Contrastes altos, tipo tipográfico | Reveals dramáticos, scroll-driven |
-| **Soft Professional** | Acolhedor, confiável, humano | Sans rounded + body neutro | Pastéis quentes + accent vibrante | Entrada gentil, micro-interações sutis |
-| **Industrial** | Técnico, funcional, direto | Mono/condensed + utility sans | Neutros + accent de alerta | Sem animação ou movimento mínimo |
-| **Modern Luxury** | Exclusivo, refinado, material | Display itálico + sans premium | Escuro profundo + gold/copper accent | Parallax sutil, hover lift, shine effect |
-
-> **Nota:** Sem "brutalist chaos" — este guia é adaptado para contexto enterprise.
-
----
-
-## Typography
-
-### Princípios
-
-- **Display font DISTINTIVA**: define o caráter da interface — evitar fontes genéricas como display
-- **Body font LEGÍVEL**: otimizada para leitura de conteúdo, densidade de informação
-- **Contraste de peso**: heading e body devem ter pesos visivelmente diferentes
-
-### Font Pairs por Direção
-
-| Direction | Display | Body | Fonte |
-|-----------|---------|------|-------|
-| Minimal Refined | Cormorant Garamond | DM Sans | Google Fonts |
-| Editorial | Playfair Display | Source Sans 3 | Google Fonts |
-| Soft Professional | Nunito | Inter | Google Fonts |
-| Industrial | JetBrains Mono | IBM Plex Sans | Google Fonts |
-| Modern Luxury | Bodoni Moda | Sora | Google Fonts |
-
-### Anti-padrões
-
-- ❌ Inter ou Roboto como fonte de display (genérico, sem caráter)
-- ❌ System fonts sem razão arquitetural explícita
-- ❌ Mesmo peso para heading e body (sem hierarquia)
-- ❌ Mais de 2 famílias de fontes sem justificativa visual clara
-
----
-
-## Color Philosophy
-
-### Estrutura
-
-```
-1 dominant (60%) + 1 sharp accent (10%) + semantic colors (30%)
-```
-
-- **Dominant**: define o mood — não precisa ser "segura", precisa ser intencional
-- **Sharp accent**: cria tensão e foco — deve contrastar com dominant
-- **Semantic**: success, warning, error, info — seguir WCAG AA (4.5:1 mínimo)
-
-### Template CSS Variables
-
-```css
-:root {
-  /* Dominant palette */
-  --color-primary: #1a1a2e;
-  --color-primary-light: #16213e;
-  --color-primary-dark: #0f3460;
-
-  /* Sharp accent */
-  --color-accent: #e94560;
-  --color-accent-hover: #c73652;
-
-  /* Surface */
-  --color-surface: #ffffff;
-  --color-surface-alt: #f8f9fa;
-  --color-border: rgba(0,0,0,0.08);
-
-  /* Semantic */
-  --color-success: #22c55e;
-  --color-warning: #f59e0b;
-  --color-error: #ef4444;
-  --color-info: #3b82f6;
-
-  /* Text */
-  --color-text-primary: #1a1a1a;
-  --color-text-secondary: #6b7280;
-  --color-text-muted: #9ca3af;
-}
-```
-
-### Anti-padrões
-
-- ❌ Gradiente roxo em fundo branco (AI cliché #1)
-- ❌ Paleta de 5 cores de peso igual (sem dominant + accent)
-- ❌ Cinza neutro como "cor segura" sem intenção estética
-- ❌ Accent color igual ao primary (sem tensão visual)
-
----
-
-## Motion Principles
-
-### Filosofia
-
-> 1 page-load bem orquestrado > micro-interações espalhadas por todo lado
-
-Criar delight através de momentos específicos, não movimento constante.
-
-### High-Impact Patterns
-
-| Pattern | Implementação | Quando usar |
-|---------|--------------|-------------|
-| **Entry stagger** | `animation-delay: 0.05s * index`, `animation-fill-mode: backwards` | Listas, cards, grids |
-| **Hover lift** | `transform: translateY(-4px)`, `box-shadow: var(--shadow-lg)` | Cards interativos, CTAs |
-| **Success bounce** | `@keyframes bounce` com `cubic-bezier(0.68, -0.55, 0.265, 1.55)` | Confirmações, saves |
-| **Data reveal** | `clip-path: inset(0 100% 0 0)` → `inset(0 0% 0 0)` | Métricas, progressos |
-
-### Acessibilidade (obrigatório)
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-> **Ref:** `framework/standards/frontend/design-system/animations.md` para keyframes e patterns completos.
-
-### Anti-padrões
-
-- ❌ Animação em absolutamente tudo (motion fatigue)
-- ❌ Transitions > 500ms para interações de UI comuns
-- ❌ Sem `prefers-reduced-motion` (acessibilidade obrigatória)
-- ❌ `animation-fill-mode` ausente em stagger (causa flash)
-
----
-
-## Spatial Composition
-
-### Padrões por Tipo de Página
-
-**Feature Hero** — Produto, landing, showcase:
-- Elemento central oversized (tipografia ou visual)
-- Generous negative space ao redor
-- 1 elemento grid-breaking (overlap, diagonal, fora do ritmo)
-
-**Dashboard** — Métricas, dados, monitoramento:
-- Controlled density — cada cm² carrega informação
-- Hierarquia clara: KPIs > charts > tabelas
-- Micro-grid consistente (8px ou 4px base)
-
-**Form Pages** — Input, configuração, onboarding:
-- Campo único em foco (single-column preferred)
-- Progress visual explícito
-- Espaço generoso entre grupos de campos
-
-### Princípio Fundamental
-
-> Generous negative space OU controlled density — nunca o "meio-termo confortável"
-
-Interfaces no meio-termo parecem vazias E confusas ao mesmo tempo.
-
----
-
-## Visual Atmosphere
-
-Técnicas por direção para criar profundidade e caráter:
-
-| Direction | Técnica Principal | Detalhe |
-|-----------|-----------------|---------|
-| Minimal Refined | Subtle noise texture | `filter: url(#noise)` SVG ou `backdrop-filter` |
-| Editorial | Dramatic type shadows | `text-shadow` em display com offset grande |
-| Soft Professional | Frosted glass cards | `backdrop-filter: blur(12px)`, `background: rgba(...)` |
-| Industrial | Hard borders + grid lines | `border: 1px solid`, sem arredondamento, monospace |
-| Modern Luxury | Gradient mesh background | Multi-stop radial gradients sobrepostos |
-
----
-
-## Template de Documentação
-
-Usar no `ui-design-system.md` de cada feature (seção `## Aesthetic Direction`):
-
-```markdown
-## Aesthetic Direction
-
-- **Direction**: [Minimal Refined / Editorial / Soft Professional / Industrial / Modern Luxury]
-- **Tone**: [1-2 frases sobre o feel — ex: "Sóbrio e confiante, como um produto B2B premium"]
-- **Differentiator**: [O que torna memorável — ex: "Entrada staggered dos cards + tipografia editorial forte"]
-- **Font Pair**: [Display font] + [Body font]
-- **Color Philosophy**: [Dominant] + [Accent] — [rationale de 1 frase]
-- **Motion Intent**: [Padrão de entrada + interações-chave]
-- **Composition**: [Abordagem de layout — ex: "Dashboard controlled density, 8px grid"]
-```
-
----
-
-*MORPH-SPEC by Polymorphism Tech*