# NeoUI -- Getting Started

NeoUI is a production-ready Blazor component library inspired by shadcn/ui. It ships 100+ accessible,
customizable components built for .NET 10 with InteractiveAuto render mode support.

## Fastest Start -- Project Template

```bash
dotnet new install NeoUI.Blazor.Templates
dotnet new neoui -n MyApp
cd MyApp && dotnet run
```

Supports three interactivity modes via `-in` / `--interactivity`:
  -in Server -- Blazor Server (single project)
  -in WebAssembly  -- Blazor WASM (single project)
  -in Auto-- InteractiveAuto (two-project solution, default)

## Manual Setup in an Existing Project

### 1. Install the Package

```bash
dotnet add package NeoUI.Blazor --version 4.0.0
```

### 2. Add _Imports.razor Entries

```razor
@using NeoUI.Blazor
@using NeoUI.Blazor.Services
@using NeoUI.Icons.Lucide
```

### 3. Register Services

**Server / Auto host project (Program.cs):**
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

**WASM client project (Program.cs):**
```csharp
builder.Services.AddNeoUIPrimitives();
builder.Services.AddNeoUIComponents();
```

### 4. Add Theme CSS in App.razor

```html
<!-- Component styles (always required) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/components.css" />
<!-- Base color (choose one: zinc | slate | gray | neutral | stone) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/base/zinc.css" />
<!-- Primary accent (choose one: blue | green | red | violet | orange | ...) -->
<link rel="stylesheet" href="_content/NeoUI.Blazor/css/themes/primary/blue.css" />
<!-- Theme init script (prevents flash of unstyled content) -->
<script src="_content/NeoUI.Blazor/js/theme.js"></script>
```

### 5. Add Portal Hosts in MainLayout.razor

Place all four after `@Body`, outside any scrollable or clipping container:
```razor
<ToastViewport />
<DialogHost />
<ContainerPortalHost />
<OverlayPortalHost />
```

### 5.5. Wrap MainLayout in AppProvider

`AppProvider` must be the outermost wrapper in `MainLayout.razor`. It initializes ThemeService, restores the persisted theme from localStorage, and broadcasts StyleVariant as a CascadingValue to all child components:
```razor
@* MainLayout.razor *@
<AppProvider>
    @Body
    <ToastViewport />
    <SpotlightCommandPalette />
    <DialogHost />
</AppProvider>
```

Components rendered outside `AppProvider` will receive `StyleVariant.Default` permanently.

### 6. Enable InteractiveAuto Render Mode in App.razor

```razor
<HeadOutlet @rendermode="InteractiveAuto" />
<Routes @rendermode="InteractiveAuto" />
```

## Your First Component

```razor
@page "/demo"
@using NeoUI.Blazor

<Button OnClick="@(() => count++)" Variant="ButtonVariant.Default">
 Clicked @count times
</Button>

@code { int count; }
```

## Common Import Patterns

```razor
@* All styled components + services *@
@using NeoUI.Blazor
@using NeoUI.Blazor.Services

@* Charts (separate sub-namespace) *@
@using NeoUI.Blazor.Charts

@* Headless primitives only *@
@using NeoUI.Blazor.Primitives
@using NeoUI.Blazor.Primitives.Services

@* Icons *@
@using NeoUI.Icons.Lucide@* 1,640 icons *@
@using NeoUI.Icons.Heroicons@* 1,288 icons *@
@using NeoUI.Icons.Feather  @* 286 icons *@
```

## Render Mode Notes

- NeoUI is designed for InteractiveAuto (Server + WASM). Set the global render mode in App.razor.
- Interactive components (Tabs, NavigationMenu, etc.) require an interactive render mode.
- For Server-only apps use InteractiveServer; for pure WASM use InteractiveWebAssembly.