# NeoUI -- Architecture

NeoUI is built on a two-layer architecture separating behavior from styling,
designed for .NET 10's InteractiveAuto rendering mode.

## Two-Layer Overview

### Layer 1: NeoUI.Blazor (Styled Components)
- 100+ production-ready components with shadcn/ui design
- Pre-built CSS included -- no Tailwind CSS setup required
- Full theme support via CSS custom properties
- Built on top of the Primitives layer

### Layer 2: NeoUI.Blazor.Primitives (Headless Layer)
- 15 headless, unstyled components providing behavior only
- WCAG 2.1 AA accessibility, keyboard navigation, ARIA attributes
- Bring your own styles -- or use NeoUI.Blazor on top
- Available primitives: Accordion, Checkbox, Collapsible, Dialog, Dropdown Menu,
  Hover Card, Label, Popover, Radio Group, Select, Sheet, Switch, Table, Tabs, Tooltip

Every styled component in NeoUI.Blazor is built on a matching primitive.

## Project Structure (InteractiveAuto -- recommended)

```
MyApp.sln
MyApp/  # ASP.NET Core host (Server + WASM server-side)
+-- MyApp.csproj
+-- Program.cs# Registers both Interactive Server + WebAssembly
\-- App.razor # Global render mode = InteractiveAuto

MyApp.Client/ # Blazor WebAssembly project
+-- MyApp.Client.csproj
+-- Program.cs# WASM entry point with NeoUI services
+-- Layout/
|+-- MainLayout.razor  # Sidebar + ThemeSwitcher + DarkModeToggle
|\-- NavMenu.razor
\-- Components/Pages/
```

## Render Modes

### InteractiveAuto (Recommended)
Starts with Server rendering, seamlessly transitions to WebAssembly after download.
```razor
<!-- App.razor -->
<HeadOutlet @rendermode="InteractiveAuto" />
<Routes @rendermode="InteractiveAuto" />
```

### InteractiveServer
All interaction handled server-side via SignalR.
```razor
<Routes @rendermode="InteractiveServer" />
```

### InteractiveWebAssembly
Pure client-side rendering.
```razor
<Routes @rendermode="InteractiveWebAssembly" />
```

## Service Registration

### Server host Program.cs
```csharp
builder.Services.AddRazorComponents()
 .AddInteractiveServerComponents()
 .AddInteractiveWebAssemblyComponents();

builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

### WASM client Program.cs
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

## Portal System

NeoUI uses four dedicated portal hosts to render overlays at the root DOM level, outside any
stacking context that could clip or obscure them. Place all four **inside** `AppProvider` in MainLayout.razor,
after `@Body` — this ensures overlays inherit the active style variant.

### Setup
```razor
@inherits LayoutComponentBase

@* AppProvider provides Theme v2 StyleVariant to all components, including portal overlays *@
<AppProvider>
    <div class="min-h-screen bg-background">
        @Body
    </div>

    @* Portal hosts inside AppProvider so overlays inherit the active style variant *@
    <ToastViewport />
    <DialogHost />
    <ContainerPortalHost />
    <OverlayPortalHost />
</AppProvider>
```

### What Each Host Does

| Host | Renders |
|------|---------|
| `ToastViewport` | Toast notification messages (position configurable) |
| `DialogHost` | Programmatic dialogs via `DialogService` |
| `ContainerPortalHost` | Inline overlays: Popover, Tooltip, DropdownMenu |
| `OverlayPortalHost` | Full-screen overlays: Dialog, Sheet, Drawer |

## Component Namespace Structure

```csharp
NeoUI.Blazor// All styled components (Button, Card, Input, etc.)
NeoUI.Blazor.Services// IThemeService, IDialogService, etc.
NeoUI.Blazor.Charts  // Chart components (separate namespace)
NeoUI.Blazor.Primitives // Headless primitives
NeoUI.Blazor.Primitives.Services  // IKeyboardShortcutService
NeoUI.Icons.Lucide// LucideIcon component
NeoUI.Icons.Heroicons// HeroIcon component
NeoUI.Icons.Feather  // FeatherIcon component
```

## Keyboard Shortcuts

```razor
@inject IKeyboardShortcutService KeyboardShortcuts

protected override async Task OnAfterRenderAsync(bool firstRender)
{
 if (firstRender)
  await KeyboardShortcuts.RegisterAsync("Ctrl+K", OpenCommandPalette);
}
```