# NeoUI -- Blocks

> **Status: Available — Foundation Released**
> Blocks are built on top of the existing NeoUI component library. The initial set of
> 6 blocks is live at `/blocks`. More blocks are added continuously.

---

## What Are Blocks?

Blocks are complete, production-ready UI sections composed from NeoUI components.
Each block is:
- **Self-contained** -- full Razor markup with `@code`, ready to drop in
- **Customizable** -- uses CSS variables and Tailwind so theming is automatic
- **Copy-paste ready** -- no wiring required beyond adding your data

Unlike individual components, blocks solve real layout problems (a full dashboard header,
an auth form, a product card grid) rather than providing a single interactive element.

---

## Block Registry Architecture

Blocks are registered in `BlockRegistry.cs` (mirrors `ComponentRegistry.cs`):

```csharp
// BlockRegistryEntry record -- metadata for each block
public sealed record BlockRegistryEntry(
    string Slug,             // URL slug, e.g. "dashboard-01"
    string Title,            // Display name
    string Description,      // One-line description
    string Icon,             // Lucide icon name
    BlockCategoryInfo Category,
    Type ComponentType,      // The actual Razor component type (for DynamicComponent)
    IReadOnlyList<string> NeoUiComponents,  // Component pills shown in the card
    bool Featured = false,
    bool IsNew = false,
    int PreviewHeight = 600); // Ideal height for the live preview

// BlockCategoryInfo record
public sealed record BlockCategoryInfo(string Slug, string DisplayName, string Icon);
```

All blocks are registered in `BlockRegistry.BuildAll()`:

```csharp
// Example entry
new(
    Slug:            "auth-01",
    Title:           "Sign In Form",
    Description:     "Email and password sign-in card with remember me checkbox.",
    Icon:            "lock",
    Category:        BlockCategories.Authentication,
    ComponentType:   typeof(AuthSignIn01),
    NeoUiComponents: ["Card", "Input", "Checkbox", "Button", "Label"],
    Featured:        true,
    IsNew:           true,
    PreviewHeight:   480)
```

---

## Block Categories

| Slug | Display Name |
|------|-------------|
| `dashboard` | Dashboard |
| `auth` | Authentication |
| `marketing` | Marketing |
| `forms` | Forms |
| `navigation` | Navigation |
| `ecommerce` | E-Commerce |
| `settings` | Settings |
| `data-tables` | Data & Tables |

---

## Available Blocks

### Dashboard

| Slug | Title | Description |
|------|-------|-------------|
| `dashboard-01` | Analytics Dashboard | KPI cards row with icons, values, and delta indicators |
| `dashboard-02` | Dashboard Shell | Full sidebar and main content area shell with header and navigation |

### Authentication

| Slug | Title | Description |
|------|-------|-------------|
| `auth-01` | Sign In Form | Email and password sign-in card with remember me checkbox |
| `auth-02` | Sign Up Form | Registration form with name, email, password and terms acceptance |

### Marketing

| Slug | Title | Description |
|------|-------|-------------|
| `hero-01` | Centered Hero | Full-width centered hero with headline, subheadline, and CTA buttons |
| `feature-01` | Feature Grid | 3-column feature cards with icons, titles, and descriptions |

---

## Block URL Pattern

- **Catalogue**: `/blocks` -- category filter pills + CSS-scaled live preview cards
- **Detail**: `/blocks/{slug}` -- full-size live preview with viewport switcher (Desktop / Tablet / Mobile)

---

## File Structure

```
NeoUI.Web.Shared/
├── BlockRegistry.cs                 -- central registry (mirroring ComponentRegistry.cs)
├── Components/Blocks/
│   └── BlockCard.razor              -- catalogue thumbnail card with CSS-scaled DynamicComponent
└── Pages/Blocks/
    ├── Index.razor                  -- /blocks catalogue page
    ├── BlockDetail.razor            -- /blocks/{slug} detail page
    ├── Dashboard/
    │   ├── DashboardStats01.razor
    │   └── DashboardShell01.razor
    ├── Auth/
    │   ├── AuthSignIn01.razor
    │   └── AuthSignUp01.razor
    └── Marketing/
        ├── HeroCentered01.razor
        └── FeatureGrid01.razor
```

---

## Adding a New Block

1. Create `Pages/Blocks/{Category}/MyBlock01.razor` with `@namespace NeoUI.Web.Shared.Pages.Blocks.{Category}`
2. Add an entry to `BlockRegistry.BuildAll()` in `BlockRegistry.cs`
3. The block automatically appears on `/blocks` and gets its own `/blocks/{slug}` detail page