@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

package/.morph/framework/standards/frontend/blazor/fluent-ui.md

@@ -0,0 +1,137 @@
+# Fluent UI Blazor - Reference Guide
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** blazor, fluent, fluentui, components, datagrid, dialog
+> **Load When:** fluent ui keywords detected
+
+## Quick Reference
+
+| Topic | Correct | Incorrect |
+|-------|---------|-----------|
+| **Icon Sizes** | Size20, Size24, Size28, Size32, Size48 | Size12, Size14, Size16 (don't exist) |
+| **Icon Namespace** | `@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons` | `@using ...Icons` (without alias) |
+| **Toast Methods** | `ToastService.ShowSuccess("msg")` | `await ToastService.ShowSuccessAsync("msg")` |
+| **Dialog Open** | `_dialog.Show()` | `await _dialog.ShowAsync()` |
+| **Dialog Close** | `await _dialog.CloseAsync()` | `await _dialog.HideAsync()` |
+| **Dialog Visibility** | `Hidden="true"` (default hidden) | Without Hidden (visible on load!) |
+
+## Setup
+
+```razor
+@* _Imports.razor *@
+@using Microsoft.FluentUI.AspNetCore.Components
+@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons
+```
+
+```csharp
+// Program.cs
+builder.Services.AddFluentUIComponents();
+```
+
+```razor
+@* MainLayout.razor *@
+<FluentToastProvider />
+<FluentDialogProvider />
+<main>@Body</main>
+```
+
+## Icons
+
+| Size | Use For |
+|------|---------|
+| Size20 | Inputs, badges, inline |
+| Size24 | Buttons, lists, menus |
+| Size28 | Medium-large elements |
+| Size32 | Headers, cards |
+| Size48 | Illustrations, empty states |
+
+```razor
+<FluentIcon Value="@(new Icons.Regular.Size24.Home())" />
+<FluentIcon Value="@(new Icons.Filled.Size20.CheckmarkCircle())" Color="Color.Accent" />
+
+<!-- For sizes < 20, use CSS -->
+<FluentIcon Value="@(new Icons.Filled.Size20.Star())" Style="width: 14px; height: 14px;" />
+```
+
+**Missing Icons — Alternatives:**
+
+| Missing | Use Instead |
+|---------|-------------|
+| Compass | CompassNorthwest |
+| Instagram | Camera |
+| WhatsApp | Chat |
+| Facebook/Twitter/LinkedIn | Share / Person |
+
+## Toast Service (Synchronous!)
+
+```csharp
+@inject IToastService ToastService
+
+// Methods are SYNC, not async
+ToastService.ShowSuccess("Saved!");
+ToastService.ShowError("Error: " + ex.Message);
+ToastService.ShowWarning("Warning");
+ToastService.ShowInfo("Processing...");
+```
+
+## FluentDialog
+
+```razor
+<FluentButton OnClick="() => _dialog.Show()">Open</FluentButton>
+
+<FluentDialog @ref="_dialog" Hidden="true" Modal="true" PreventDismissOnOverlayClick="true">
+    <FluentDialogHeader>
+        <FluentLabel Typo="Typography.H4">Confirm</FluentLabel>
+    </FluentDialogHeader>
+    <FluentDialogBody><p>Continue?</p></FluentDialogBody>
+    <FluentDialogFooter>
+        <FluentButton Appearance="Appearance.Neutral" OnClick="() => _dialog.CloseAsync()">Cancel</FluentButton>
+        <FluentButton Appearance="Appearance.Accent" OnClick="Confirm">OK</FluentButton>
+    </FluentDialogFooter>
+</FluentDialog>
+
+@code {
+    private FluentDialog _dialog = default!;
+    private async Task Confirm() { /* logic */ await _dialog.CloseAsync(); }
+}
+```
+
+> **Custom modals:** See `html-to-blazor.md` for custom modal pattern when design doesn't follow Fluent.
+
+## FluentDataGrid
+
+```razor
+<FluentDataGrid Items="@_orders" Virtualize="true" ItemSize="50">
+    <PropertyColumn Property="@(o => o.OrderNumber)" Title="Order" Sortable="true" />
+    <PropertyColumn Property="@(o => o.Total)" Title="Total" Format="C" />
+    <TemplateColumn Title="Status">
+        <FluentBadge Appearance="@GetBadge(context.Status)">@context.Status</FluentBadge>
+    </TemplateColumn>
+    <TemplateColumn Title="Actions">
+        <FluentButton Appearance="Appearance.Lightweight" OnClick="@(() => View(context))">View</FluentButton>
+    </TemplateColumn>
+</FluentDataGrid>
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Size16 does not exist" | Invalid icon size | Use Size20, 24, 28, 32, 48 |
+| "'Regular' not in context" | Missing icon alias | `@using Icons = ...Icons` |
+| Dialog visible on page load | Missing `Hidden="true"` | Add `Hidden="true"` |
+| "ShowSuccessAsync not found" | Async method doesn't exist | Use sync `ShowSuccess()` |
+
+## Checklist
+
+- [ ] `AddFluentUIComponents()` in Program.cs
+- [ ] `FluentToastProvider` + `FluentDialogProvider` in layout
+- [ ] Icons use alias `Icons =` and valid sizes (20-48)
+- [ ] Toast methods are synchronous
+- [ ] Dialogs have `Hidden="true"`
+- [ ] DataGrid uses `Virtualize` for large lists
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/frontend/blazor/html-conversion.md

@@ -0,0 +1,184 @@
+# Guia de Conversao HTML para Blazor
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** blazor, html, conversion, prototype, migrate
+> **Load When:** html conversion keywords detected
+
+## Element Mapping
+
+### Basic Elements
+
+| HTML | Blazor (Fluent UI) |
+|------|---------------------|
+| `<button class="btn-primary">` | `<FluentButton Appearance="Appearance.Accent">` |
+| `<button class="btn-secondary">` | `<FluentButton Appearance="Appearance.Neutral">` |
+| `<input type="text">` | `<FluentTextField @bind-Value="Model.Field">` |
+| `<input type="email">` | `<FluentTextField Type="TextFieldType.Email">` |
+| `<input type="password">` | `<FluentTextField Type="TextFieldType.Password">` |
+| `<textarea>` | `<FluentTextArea @bind-Value="Model.Field">` |
+| `<select>` | `<FluentSelect @bind-Value="Model.Field">` |
+| `<input type="checkbox">` | `<FluentCheckbox @bind-Value="Model.Flag">` |
+| `<input type="radio">` | `<FluentRadioGroup @bind-Value="Model.Option">` |
+
+### Containers & Layout
+
+| HTML | Blazor |
+|------|--------|
+| `<div class="card">` | `<FluentCard>` |
+| `<div class="flex">` | `<FluentStack Orientation="Horizontal">` |
+| `<div class="flex-col">` | `<FluentStack Orientation="Vertical">` |
+| `<div class="grid">` | `<FluentGrid>` |
+| `<div class="modal">` | Custom HTML or `<FluentDialog>` |
+
+### Feedback & Data
+
+| HTML | Blazor |
+|------|--------|
+| `<div class="alert-success">` | `<FluentMessageBar Intent="MessageIntent.Success">` |
+| `<div class="alert-error">` | `<FluentMessageBar Intent="MessageIntent.Error">` |
+| `<div class="toast">` | `ToastService.ShowSuccess("msg")` |
+| `<div class="spinner">` | `<FluentProgress />` |
+| `<table>` | `<FluentDataGrid Items="@items">` |
+| `<th>` | `<PropertyColumn Property="@(x => x.Prop)">` |
+| `<td>` with actions | `<TemplateColumn>` |
+
+---
+
+## Page Structure
+
+```razor
+@page "/pagename"
+@rendermode InteractiveServer
+@inject IMyService _service
+
+<PageTitle>App - Pagina</PageTitle>
+
+<div class="page-layout">
+    <header class="page-header-nav"><!-- Nav --></header>
+    <div class="page-content container">
+        <h1>Titulo</h1>
+        <!-- Content -->
+    </div>
+</div>
+
+@code {
+    private bool _isLoading;
+    private string? _error;
+    protected override async Task OnInitializedAsync() => await LoadDataAsync();
+    private async Task HandleClick() { }
+    private string FormatValue(decimal value) => value.ToString("C");
+}
+```
+
+---
+
+## Event Conversion
+
+| HTML Event | Blazor Pattern |
+|------------|---------------|
+| `onclick="fn()"` | `@onclick="HandleClick"` (sync) or `@onclick="HandleClickAsync"` (async) |
+| `onchange="fn(val)"` | `@bind-Value="_val"` (two-way) or `@onchange="HandleChange"` (one-way) |
+| `<form onsubmit>` | `<EditForm Model="@_model" OnValidSubmit="HandleSubmit">` with `<DataAnnotationsValidator />` |
+
+### Form Example
+
+```razor
+<EditForm Model="@_model" OnValidSubmit="HandleSubmit">
+    <DataAnnotationsValidator />
+    <FluentTextField @bind-Value="_model.Email" Label="Email" Required />
+    <FluentButton Type="ButtonType.Submit" Appearance="Appearance.Accent">Enviar</FluentButton>
+</EditForm>
+
+@code {
+    private MyModel _model = new();
+    private async Task HandleSubmit() => await _service.SaveAsync(_model);
+    public class MyModel { [Required][EmailAddress] public string Email { get; set; } = ""; }
+}
+```
+
+---
+
+## Modal Conversion
+
+**Use custom HTML** when: custom design, backdrop blur, complex animations.
+**Use `<FluentDialog>`** for simple confirmations.
+
+### Custom Modal
+
+```razor
+@if (!_modalHidden)
+{
+    <div class="modal-overlay" @onclick="CloseModal">
+        <div class="modal-container animate-scaleIn" @onclick:stopPropagation="true">
+            <div class="modal-header">
+                <h3>Titulo</h3>
+                <button class="modal-close" @onclick="CloseModal">
+                    <FluentIcon Value="@(new Icons.Regular.Size20.Dismiss())" />
+                </button>
+            </div>
+            <div class="modal-body">Conteudo...</div>
+            <div class="modal-footer">
+                <FluentButton Appearance="Appearance.Neutral" @onclick="CloseModal">Cancelar</FluentButton>
+                <FluentButton Appearance="Appearance.Accent" @onclick="Confirm">Confirmar</FluentButton>
+            </div>
+        </div>
+    </div>
+}
+@code {
+    private bool _modalHidden = true;
+    private void OpenModal() => _modalHidden = false;
+    private void CloseModal() => _modalHidden = true;
+    private async Task Confirm() { /* logic */ CloseModal(); }
+}
+```
+
+---
+
+## Style Interpolation
+
+```razor
+<!-- Static: same as HTML -->
+<div style="color: red; margin-top: 20px;">
+
+<!-- Dynamic: ALWAYS use @($"...") -->
+<div style="@($"color: {_color}; margin-top: {_margin}px;")">
+
+<!-- WRONG: causes RZ9986 -->
+<FluentStack Style="animation-delay: @(0.05 * index)s;">
+<!-- CORRECT -->
+<FluentStack Style="@($"animation-delay: {0.05 * index}s;")">
+```
+
+## Loops & Conditionals
+
+```razor
+<!-- Loop -->
+@foreach (var item in _items) { <li>@item.Name</li> }
+
+<!-- Loop with stagger animation -->
+@for (int i = 0; i < _items.Count; i++)
+{
+    var index = i; // capture for closure
+    <li class="animate-slideInUp" style="@($"animation-delay: {0.05 * index}s;")">@_items[index].Name</li>
+}
+
+<!-- Conditional rendering (replaces display:none toggle) -->
+@if (_isLoading) { <FluentProgress /> }
+else if (_error != null) { <FluentMessageBar Intent="MessageIntent.Error">@_error</FluentMessageBar> }
+else { <FluentDataGrid Items="@_items"><!-- columns --></FluentDataGrid> }
+```
+
+## Checklist
+
+- [ ] Page structure: `@page`, `@rendermode`, `@inject`
+- [ ] HTML elements mapped to Fluent UI components
+- [ ] Events: `onclick` → `@onclick`, forms → `EditForm`
+- [ ] Modals: custom vs `FluentDialog` decided
+- [ ] Style interpolation uses `@($"...")`
+- [ ] Loops use `var index = i` for closures
+- [ ] CSS classes validated with `morph-spec validate-css`
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/frontend/blazor/lifecycle.md

@@ -0,0 +1,195 @@
+# Blazor Lifecycle: Pitfalls & Solutions
+
+> **Scope:** blazor-azure
+> **Layer:** 2 (on keyword)
+> **Keywords:** blazor, lifecycle, oninit, onafter, onparametersset, dispose
+> **Load When:** blazor work
+
+## Lifecycle Flow
+
+```
+1. SetParametersAsync
+2. OnInitialized(Async)       ← No JS available (prerendering)
+3. OnParametersSet(Async)
+4. BuildRenderTree (Render)
+5. OnAfterRender(Async)       ← JS available (firstRender=true)
+6. [User Interaction] → 3→4→5 (firstRender=false)
+7. Dispose (component removed)
+```
+
+## Decision Matrix
+
+| Need to... | Use Method | Note |
+|------------|------------|------|
+| Load data from API/DB | `OnInitializedAsync` | No JS available |
+| Call JavaScript / DOM | `OnAfterRenderAsync(firstRender)` | firstRender guard |
+| React to parameter changes | `OnParametersSetAsync` | Called on every change |
+| Clean up resources | `Dispose` | Timers, subscriptions |
+| Update UI after async op | `StateHasChanged()` | Manual re-render |
+
+## Common Pitfalls
+
+| Problem | Error | Solution |
+|---------|-------|----------|
+| JSRuntime in OnInitialized | "statically rendered" | Move to `OnAfterRenderAsync(firstRender)` |
+| Layout with @rendermode | "Cannot pass Body with rendermode" | Remove `@rendermode` from layouts |
+| HttpClient no BaseAddress | "Invalid request URI" | Use `NavigationManager.BaseUri` |
+| UI not updating after await | Stale UI | Call `StateHasChanged()` after async |
+| File upload > 512KB | "exceeds maximum size" | `OpenReadStream(maxAllowedSize: size)` |
+| Dispose not called | Memory leaks | Implement `IDisposable` |
+| Cascading param null | NullRef during init | Check null in `OnParametersSet()` |
+| Infinite render loop | Browser freezes | Never `StateHasChanged()` in property setters |
+
+---
+
+## Essential Patterns
+
+### JSRuntime (OnAfterRender only)
+
+```csharp
+@inject IJSRuntime JSRuntime
+@code {
+    private bool _initialized;
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (firstRender && !_initialized)
+        {
+            await JSRuntime.InvokeVoidAsync("initializeChart", "myChart");
+            _initialized = true;
+            StateHasChanged();
+        }
+    }
+}
+```
+
+### Data Loading
+
+```csharp
+@code {
+    private List<Item> Items { get; set; } = new();
+    private bool Loading = true;
+    private string? Error;
+
+    protected override async Task OnInitializedAsync()
+    {
+        try { Items = await HttpClient.GetFromJsonAsync<List<Item>>("/api/items"); }
+        catch (Exception ex) { Error = ex.Message; }
+        finally { Loading = false; }
+    }
+}
+```
+
+### Parameter Change
+
+```csharp
+@code {
+    [Parameter] public int ProductId { get; set; }
+    private Product? Product;
+
+    protected override async Task OnParametersSetAsync()
+    {
+        if (ProductId > 0)
+            Product = await HttpClient.GetFromJsonAsync<Product>($"/api/products/{ProductId}");
+    }
+}
+```
+
+### Dispose Pattern
+
+```csharp
+@implements IDisposable
+@code {
+    private System.Timers.Timer? _timer;
+    protected override void OnInitialized()
+    {
+        _timer = new System.Timers.Timer(1000);
+        _timer.Elapsed += (s, e) => InvokeAsync(StateHasChanged);
+        _timer.Start();
+    }
+    public void Dispose() { _timer?.Stop(); _timer?.Dispose(); }
+}
+```
+
+### File Upload
+
+```csharp
+@code {
+    private const long MaxFileSize = 10 * 1024 * 1024;
+    private async Task HandleFile(InputFileChangeEventArgs e)
+    {
+        if (e.File.Size > MaxFileSize) { Error = "File > 10MB"; return; }
+        using var stream = e.File.OpenReadStream(maxAllowedSize: MaxFileSize);
+        var buffer = new byte[e.File.Size];
+        await stream.ReadAsync(buffer);
+    }
+}
+```
+
+### Infinite Render Loop
+
+```csharp
+// WRONG - StateHasChanged in property setter = infinite loop
+private int Counter { get => _c; set { _c = value; StateHasChanged(); } }
+
+// CORRECT - StateHasChanged only in event handlers
+private int _c;
+private void Increment() { _c++; StateHasChanged(); }
+```
+
+---
+
+## Performance
+
+| Pattern | Code |
+|---------|------|
+| Prevent unnecessary renders | `protected override bool ShouldRender() => _dataChanged;` |
+| List items with key | `@foreach (var item in Items) { <ItemComponent @key="item.Id" Item="@item" /> }` |
+| Debounce input | `_debounce = new Timer(500); _debounce.Elapsed += async (s, a) => await Search(value);` |
+
+---
+
+## Checklist
+
+- [ ] No JSRuntime in `OnInitializedAsync`
+- [ ] `StateHasChanged()` after async operations
+- [ ] File uploads specify `maxAllowedSize`
+- [ ] Dispose pattern for subscriptions/timers
+- [ ] No `@rendermode` on layouts
+- [ ] Cascading parameters null-checked
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+
+---
+
+## Code Review Checklist
+
+Use this checklist during code review for Blazor component lifecycle:
+
+### OnInitializedAsync vs OnAfterRenderAsync
+
+- [ ] **JSRuntime calls are in `OnAfterRenderAsync`, not `OnInitializedAsync`?**
+- [ ] **Database/API calls are in `OnInitializedAsync`, not `OnAfterRenderAsync`?**
+- [ ] **`firstRender` check is used to prevent duplicate JS calls?**
+
+### StateHasChanged
+
+- [ ] **`StateHasChanged()` called after async operations that update UI?**
+- [ ] **No excessive `StateHasChanged()` calls in loops?**
+
+### IDisposable / IAsyncDisposable
+
+- [ ] **Component implements `IDisposable` if it has timers, event handlers, or CTS?**
+- [ ] **`CancellationTokenSource` is cancelled and disposed?**
+- [ ] **Event handlers are unsubscribed in `Dispose`?**
+- [ ] **Timers are stopped and disposed?**
+
+### RenderMode
+
+- [ ] **`@rendermode InteractiveServer` is on pages, NOT on layouts?**
+- [ ] **Layout components have NO `@rendermode` directive?**
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*