# 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*
