# ng-blatui

[![npm](https://img.shields.io/npm/v/ng-blatui.svg)](https://www.npmjs.com/package/ng-blatui)
[![license](https://img.shields.io/npm/l/ng-blatui.svg)](./LICENSE)
[![Angular](https://img.shields.io/badge/Angular-21%20%26%2022-dd0031.svg)](https://angular.dev)

Accessible **Angular UI library** — a faithful port of [BlatUI](https://ngblatui.remix-it.com)'s visual system to Angular. Built on the official Angular headless stack (Angular Aria + CDK), styled with Tailwind CSS v4 + oklch design tokens.

**157 components · 16 blocks · 70 charts · 35 page templates** — all standalone, signal-based, zoneless and SSR-safe.

🔗 **[Docs & live demo →](https://ngblatui.remix-it.com)** · 📦 **[npm](https://www.npmjs.com/package/ng-blatui)** · 🤖 **[Using with AI →](./USING-WITH-AI.md)**

---

## Highlights

- **Angular 21 & 22** — standalone components, **signals** (`input()`/`model()`/`output()`), **zoneless** change detection, `OnPush` by default.
- **SSR-ready** — every component renders correctly under server-side rendering (the docs site prerenders 280+ static routes).
- **Accessible** — behavior built on `@angular/aria` + `@angular/cdk`; passes AXE / WCAG AA.
- **Forms-native** — every form control implements `ControlValueAccessor`, so the same component works with Reactive, Template-driven and Signal forms.
- **Themeable** — Tailwind v4 utilities + CSS variables (oklch tokens); light/dark out of the box.
- **AI-ready** — ships an MCP server, an `llms.txt` index and a machine-readable registry (see below).

## Installation

```bash
npm i ng-blatui
```

Peer dependencies (Angular **21 or 22**): `@angular/core`, `@angular/common`, `@angular/forms`, `@angular/cdk`, `@angular/aria`.

### Tailwind CSS setup

Styling is **Tailwind CSS v4**. In your app's global stylesheet (e.g. `src/styles.css`) add three lines:

```css
@import 'tailwindcss';
@import 'ng-blatui/foundations/blatui.css'; /* design tokens + dark theme */
@source '../node_modules/ng-blatui'; /* ← generate the utilities the lib's classes use */
```

The **`@source`** line is the easy one to miss: without it Tailwind never scans ng-blatui's
compiled templates, so the components render **unstyled**. Point it at wherever `ng-blatui` lives
relative to the stylesheet (adjust the `../` depth). Dark mode is a `dark` class on a parent
(`<html class="dark">`); override any oklch token in `:root` / `.dark` to re-theme. Full guide:
**https://ngblatui.remix-it.com/docs/installation**.

### Icons

ng-blatui ships no icon set — wire your own (e.g. [`@ng-icons`](https://ng-icons.github.io/ng-icons/))
with `provideIcons(...)` and register each icon you use. Components that take an icon accept an SVG
path `d` string, so any icon source works.

## Usage

Import the component class from the `ng-blatui` barrel and add it to a standalone component's `imports[]` — no NgModule. Selectors are prefixed **`bui`**.

```ts
import { Component } from '@angular/core';
import { BuiButton, BuiBadge, BuiInput } from 'ng-blatui';

@Component({
  selector: 'app-demo',
  imports: [BuiButton, BuiBadge, BuiInput],
  template: `
    <label>
      Email
      <input buiInput type="email" placeholder="you@example.com" />
    </label>
    <button buiButton>Save <span buiBadge tone="success">New</span></button>
  `,
})
export class Demo {}
```

- **Element selectors**: `<bui-avatar>`, `<bui-rating>`, …
- **Attribute/directive selectors**: `<button buiButton>`, `<input buiInput>`, `<span buiBadge tone="success">`, …
- **Signals**: bind `[checked]` / `(checkedChange)` etc.; works under zoneless CD and SSR with no extra setup.
- **Forms**: `formControlName`, `[(ngModel)]` or `[formControl]` all work — every control is a `ControlValueAccessor`.

### Form fields: two levels

- **Batteries-included** components wire label + hint + error + ARIA for you: `BuiInputField`,
  `BuiMoneyInput` (localized currency; `symbol="DH"` overrides the ISO code), `BuiDateRangePicker`
  (start→end with presets), plus `BuiSelect`, `BuiCombobox`, `BuiAutocomplete`, `BuiPhoneInput`.
- **Composition primitives** for custom layouts: `buiField` + `buiFieldLabel` / `buiFieldDescription`
  / `buiFieldError` wrap a bare `buiInput` / `.blat-*` control and manage the a11y relationships.

Reach for a bare control (`buiInput`) only when you also add the `buiField` scaffolding yourself.
Other easy-to-miss building blocks: `buiEmpty` (empty states), `bui-stat` (stat cards),
`buiFieldSet` / `buiFieldLegend` (grouped fields).

## Theming

Styling is Tailwind v4 + CSS variables. Override the oklch design tokens (`--background`, `--foreground`, `--primary`, `--border`, `--muted`, `--radius`, …) to restyle everything globally; toggle a `dark` class for dark mode. See **https://ngblatui.remix-it.com/docs/theming**.

## Localization

Two providers cover the whole library, both set once in your app config:

```ts
import { provideBuiLabels, provideBuiLocale } from 'ng-blatui';

providers: [
  provideBuiLocale('fr-BE'), // dates, times, numbers, week start, weekend, week numbering
  provideBuiLabels({ fileUploadRemove: 'Supprimer le fichier' }), // built-in strings
];
```

**Set neither and everything formats as `en-US`** — that is Angular's own `LOCALE_ID` default, and
the usual reason pickers stay American in an app that is not. Resolution runs most-specific first:
a component's `[locale]` input → `provideBuiLocale()` → the app's `LOCALE_ID` → `en-US`. You never
need `registerLocaleData()` here; ng-blatui formats through `Intl`.

Both providers also take a **signal**, or a factory run in an injection context — which is what
keeps them open to any translation library (Transloco, ngx-translate, a signal store of your own)
without ng-blatui depending on one, or knowing any translation format. Full guide, with a Transloco
example: **https://ngblatui.remix-it.com/docs/localization**.

## What's inside

| Category       | Count | Browse                                   |
| -------------- | ----- | ---------------------------------------- |
| **Components** | 157   | https://ngblatui.remix-it.com/components |
| **Blocks**     | 16    | https://ngblatui.remix-it.com/blocks     |
| **Charts**     | 70    | https://ngblatui.remix-it.com/charts     |
| **Templates**  | 35    | https://ngblatui.remix-it.com/templates  |

Templates are full, production-style pages (dashboard, pricing, auth, store, CRM, blog, docs, e-commerce product, plus 20 art-directed landing pages) — faithful 1:1 reproductions of the BlatUI originals.

## Using with AI agents

ng-blatui is built to be consumed by AI coding assistants so they discover and use the catalog correctly instead of guessing — via three layers:

| Layer             | What                                                        | Where                                       |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------- |
| **MCP server**    | Tools to list/search the catalog and fetch full docs + code | `npx ng-blatui-mcp`                         |
| **llms.txt**      | The [llms.txt](https://llmstxt.org) standard index          | https://ngblatui.remix-it.com/llms.txt      |
| **registry.json** | Machine-readable catalog                                    | https://ngblatui.remix-it.com/registry.json |

Quick start (works in Claude, Cursor, Windsurf, Cline, Zed, VS Code…):

```bash
claude mcp add ng-blatui -- npx -y ng-blatui-mcp
# or add to any MCP client:
# { "mcpServers": { "ng-blatui": { "command": "npx", "args": ["-y", "ng-blatui-mcp"] } } }
```

The MCP server exposes `list_components` (optional `category`), `list_blocks`, `list_charts`, `list_templates`, `search({ query })` and `get_docs({ name })`. Full guide with per-client config and copy-paste editor rules: **[USING-WITH-AI.md](./USING-WITH-AI.md)**.

---

## Development

This is an Angular workspace with two projects: the library (`projects/ng-blatui`) and the docs/demo app (`projects/demo`).

```bash
git clone https://github.com/anousss007/ng-blatui.git
cd ng-blatui
npm install
npm start          # serve the docs/demo app at http://localhost:4200
```

### Scripts

| Command                    | What it does                                             |
| -------------------------- | -------------------------------------------------------- |
| `npm start`                | Serve the demo app (`ng serve demo`)                     |
| `npm run build:lib`        | Build the publishable library (`ng build ng-blatui`)     |
| `npm run build`            | Build the demo site                                      |
| `npm test`                 | Unit tests (Vitest)                                      |
| `npm run lint`             | ESLint (type-aware, strict) + template a11y              |
| `npm run format`           | Prettier (with Tailwind class sorting)                   |
| `npm run build:registry`   | Regenerate `registry.json` + `llms.txt` from the catalog |
| `npm run capture:previews` | Capture template preview images (Playwright)             |
| `npm run deploy:site`      | Build + deploy the docs site to the VPS                  |

### Project structure

```
projects/
  ng-blatui/        # the published library (src/lib/* = 157 component dirs, public-api.ts)
  demo/             # docs + live demo site (components/blocks/charts/templates galleries)
    src/app/pages/templates/   # the 35 page templates
    public/         # static assets incl. generated llms.txt + registry.json
scripts/
  build-registry.mjs   # generates registry.json + llms.txt + mcp/registry.json
  capture-previews.mjs # template preview screenshots
  deploy-site.sh       # build + rsync to VPS
mcp/                # the ng-blatui-mcp MCP server package (published separately)
.claude/skills/     # angular-best-practices (contributing) + ng-blatui (consuming)
AGENTS.md           # guide for AI agents working IN this repo
USING-WITH-AI.md    # guide for consuming ng-blatui WITH an AI agent
```

### Conventions

Angular **v22**, zoneless, standalone (defaults — never set explicitly). Signals everywhere; native control flow (`@if`/`@for`/`@switch`); no `*ngIf`/`ngClass`. Library selector prefix `bui`, demo prefix `app`. See **[AGENTS.md](./AGENTS.md)** and **[CONTRIBUTING.md](./CONTRIBUTING.md)** for the full ruleset.

## Releasing

- **Library** (`ng-blatui`) — the **Release** GitHub Actions workflow (manual dispatch) runs `semantic-release`: it analyzes Conventional Commits, bumps the version, tags, creates a GitHub release and publishes to npm with provenance.
- **MCP server** (`ng-blatui-mcp`) — bump `mcp/package.json`, then run the **Release MCP** workflow (manual dispatch) to publish it.

## Credits

Angular port of [**BlatUI**](https://ngblatui.remix-it.com) (Blade/Laravel + Tailwind component system). Behavior on Angular Aria + CDK.

## License

[MIT](./LICENSE)