@polymorphism-tech/morph-spec 4.3.1 → 4.3.3

package/stacks/nextjs-supabase/.morph/standards/frontend/blazor/pitfalls.md

@@ -0,0 +1,198 @@
+# 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/stacks/nextjs-supabase/.morph/standards/frontend/blazor/state.md

@@ -0,0 +1,191 @@
+# 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/stacks/nextjs-supabase/.morph/standards/frontend/design-system/animations.md

@@ -0,0 +1,151 @@
+# CSS Animation Patterns
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** css, animation, keyframe, transition, stagger, shimmer
+> **Load When:** always
+
+## Keyframes Library
+
+```css
+@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+@keyframes fadeOut { from { opacity: 1; } to { opacity: 0; } }
+@keyframes slideInUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes slideInDown { from { opacity: 0; transform: translateY(-20px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes slideInLeft { from { opacity: 0; transform: translateX(-20px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes slideInRight { from { opacity: 0; transform: translateX(20px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes scaleIn { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } }
+@keyframes bounce { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-10px); } }
+@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
+@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+@keyframes shimmer { 0% { background-position: -200% 0; } 100% { background-position: 200% 0; } }
+```
+
+## Animation Classes
+
+| Class | Animation | Duration | Iteration |
+|-------|-----------|----------|-----------|
+| `.animate-fadeIn` | fadeIn | 0.3s | once |
+| `.animate-fadeOut` | fadeOut | 0.3s | once |
+| `.animate-slideInUp` | slideInUp | 0.5s | once |
+| `.animate-slideInDown` | slideInDown | 0.5s | once |
+| `.animate-slideInLeft` | slideInLeft | 0.5s | once |
+| `.animate-slideInRight` | slideInRight | 0.5s | once |
+| `.animate-scaleIn` | scaleIn | 0.3s | once |
+| `.animate-bounce` | bounce | 1s | infinite |
+| `.animate-pulse` | pulse | 2s | infinite |
+| `.animate-spin` | spin | 1s | infinite |
+
+```css
+.animate-fadeIn { animation: fadeIn 0.3s ease forwards; }
+.animate-slideInUp { animation: slideInUp 0.5s ease forwards; }
+.animate-bounce { animation: bounce 1s ease infinite; }
+```
+
+## Stagger & Timing
+
+```css
+/* Stagger delays (0.1s - 1.0s) */
+.stagger-1 { animation-delay: 0.1s; } .stagger-2 { animation-delay: 0.2s; }
+.stagger-3 { animation-delay: 0.3s; } /* ... up to .stagger-10 */
+
+/* Durations */
+.duration-fast { animation-duration: 150ms; }
+.duration-normal { animation-duration: 300ms; }
+.duration-slow { animation-duration: 500ms; }
+
+/* Easing */
+.ease-bounce { animation-timing-function: cubic-bezier(0.68, -0.55, 0.265, 1.55); }
+```
+
+## Shimmer (Skeleton Loading)
+
+```css
+.shimmer {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+```
+
+---
+
+## Blazor Usage
+
+### Stagger Pattern
+
+```razor
+@for (int i = 0; i < _items.Count; i++)
+{
+    var index = i;
+    <div class="card animate-slideInUp"
+         style="@($"animation-delay: {0.05 * index}s; animation-fill-mode: backwards;")">
+        @_items[index].Name
+    </div>
+}
+```
+
+**CRITICAL:** Use `animation-fill-mode: backwards` to avoid flash before delay.
+
+### Conditional Enter/Exit
+
+```razor
+@if (_showMessage)
+{
+    <div class="@(_isEntering ? "animate-slideInUp" : "animate-fadeOut")">Msg</div>
+}
+@code {
+    private async Task HideMessage() {
+        _isEntering = false;
+        await Task.Delay(300); // wait for exit animation
+        _showMessage = false;
+    }
+}
+```
+
+### Skeleton Loading
+
+```razor
+@if (_isLoading)
+{
+    <div class="shimmer" style="width: 200px; height: 24px; border-radius: 4px;"></div>
+}
+else { <h2>@_title</h2> }
+```
+
+## Transitions (Hover/Focus)
+
+```css
+.card { transition: transform 0.2s ease, box-shadow 0.2s ease; }
+.card:hover { transform: translateY(-4px); box-shadow: var(--shadow-lg); }
+
+.button { transition: background-color 0.15s ease, transform 0.15s ease; }
+.button:active { transform: scale(0.98); }
+
+.link::after { content: ''; position: absolute; width: 0; height: 2px; background: var(--primary); transition: width 0.3s ease; }
+.link:hover::after { width: 100%; }
+```
+
+## Accessibility
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Checklist
+
+- [ ] Keyframes in design-system.css
+- [ ] `.animate-*` classes created
+- [ ] `animation-fill-mode: backwards` for stagger
+- [ ] `@media (prefers-reduced-motion)` implemented
+- [ ] Shimmer for loading states
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/stacks/nextjs-supabase/.morph/standards/frontend/design-system/naming.md

@@ -0,0 +1,64 @@
+# CSS Naming Convention
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** css, bem, naming, class names, conventions
+> **Load When:** always
+
+## Principles
+
+1. **Page prefix** — Prevents conflicts
+2. **BEM for components** — Clear hierarchy
+3. **Namespaced variables** — No library collisions
+4. **State suffixes** — Consistent modifiers
+
+---
+
+## Page Prefixes
+
+| Page | Example |
+|------|---------|
+| Home | `.home-hero`, `.home-features` |
+| Checkout | `.checkout-form`, `.checkout-summary` |
+| Dashboard | `.dashboard-stats`, `.dashboard-chart` |
+| Auth | `.auth-form`, `.auth-social-buttons` |
+
+## BEM for Reusable Components
+
+```css
+.card { }              /* Block */
+.card__header { }      /* Element */
+.card__body { }
+.card--featured { }    /* Modifier */
+```
+
+**Rule:** BEM for reusable components. Page prefix for page-specific elements.
+
+## CSS Variables with Namespace
+
+```css
+:root {
+  --app-primary: #007bff;
+  --app-spacing-md: 1rem;
+  --app-font-heading: 'Segoe UI', sans-serif;
+}
+```
+
+## State Suffixes
+
+| State | Suffix |
+|-------|--------|
+| Active | `--active` |
+| Disabled | `--disabled` |
+| Loading | `--loading` |
+| Error | `--error` |
+
+```css
+.button { }
+.button--active { }
+.button--disabled { }
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*