@polymorphism-tech/morph-spec 4.11.1 → 4.13.0

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

@@ -1,137 +0,0 @@
-# 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/framework/standards/frontend/blazor/html-conversion.md

@@ -1,184 +0,0 @@
-# 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/framework/standards/frontend/blazor/lifecycle.md

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