@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/.morph/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/.morph/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/.morph/framework/standards/frontend/design-system/animations.md

@@ -1,151 +0,0 @@
-# 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/.morph/framework/standards/frontend/design-system/naming.md

@@ -1,64 +0,0 @@
-# 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*