npm package: @letsprogram/ng-oat
Description: Angular component library built on top of the Oat CSS framework — signals-first, lightweight, and accessible.
Author: SashiKumar Yadav
Latest version: 0.3.2

# @letsprogram/ng-oat

**Angular component library built on the [Oat CSS framework](https://oat.ink)** — signals-first, lightweight, and accessible.

[![npm version](https://img.shields.io/npm/v/@letsprogram/ng-oat.svg)](https://www.npmjs.com/package/@letsprogram/ng-oat)
[![license](https://img.shields.io/npm/l/@letsprogram/ng-oat.svg)](https://github.com/yshashi/ng-oat-workspace/blob/main/LICENSE)

---

## Why ng-oat?

Most Angular UI libraries ship massive bundles, override half your app's styles, and lock you into their design language. ng-oat takes a different approach:

- **Tiny footprint** — Oat CSS is just ~4 KB (gzipped). The Angular wrapper adds components, not weight expect less than 200kB packed.
- **Signals-first** — Every component is built with Angular Signals from day one. No RxJS subscriptions to manage.
- **Standalone everything** — Import only what you use. No `NgModule` ceremony.
- **Semantic HTML** — Components render clean, accessible markup. Oat CSS does the styling; Angular handles the behavior.
- **Signal Forms** — First-class form field components that plug into Angular's new `@angular/forms/signals` API.

This library started as a personal project to wrap [knadh's oat](https://github.com/knadh/oat) — a beautifully minimal classless CSS framework — into native Angular components. The Oat CSS framework did the heavy lifting on the design side, and this library adds the interactive Angular layer on top of it. Special thanks to [oat.ink](https://oat.ink) for making the foundation so solid.

---

## Quick Start

### 1. Install

```bash
npm install @letsprogram/ng-oat
```

That's it — the Oat CSS framework ships as a bundled asset inside the package.

### 2. Add Oat CSS to your project

Open `angular.json` and add the stylesheet and tokens:

```json
{
  "projects": {
    "my-app": {
      "architect": {
        "build": {
          "options": {
            "styles": ["node_modules/@letsprogram/ng-oat/assets/oat/oat.css", "node_modules/@letsprogram/ng-oat/src/lib/tokens/tokens.css", "src/styles.css"]
          }
        }
      }
    }
  }
}
```

| File         | Purpose                                                                   |
| ------------ | ------------------------------------------------------------------------- |
| `oat.css`    | Core Oat CSS framework (typography, colors, layout, all component styles) |
| `tokens.css` | `--oat-*` design token aliases for runtime theming                        |

> **No JavaScript required!** All interactive behavior (dropdowns, toasts, sidebars, tabs, tooltips) is handled natively by Angular components — no external JS file needed.

> **Alternative:** You can also import the CSS in your `styles.css` instead:
>
> ```css
> @import '@letsprogram/ng-oat/assets/oat/oat.css';
> @import '@letsprogram/ng-oat/src/lib/tokens/tokens.css';
> @import '@letsprogram/ng-oat/src/lib/styles/tooltip-positions.css';
> ```

### 3. Configure the provider

Add `provideNgOat()` to your application config. Since CSS is already loaded via `angular.json`, the provider only sets up internal injection tokens — no runtime asset loading occurs by default.

```typescript
// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideNgOat } from '@letsprogram/ng-oat';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [provideRouter(routes), provideNgOat()],
};
```

### 4. Use a component

Every component is standalone — just import and go:

```typescript
import { Component } from '@angular/core';
import { NgOatButton, NgOatBadge } from '@letsprogram/ng-oat';

@Component({
  selector: 'app-root',
  imports: [NgOatButton, NgOatBadge],
  template: `
    <ng-oat-button variant="primary">Click me</ng-oat-button>
    <ng-oat-badge variant="success">Online</ng-oat-badge>
  `,
})
export class App {}
```

---

## Available Components

### Components

| Component           | Selector                 | Description                                  |
| ------------------- | ------------------------ | -------------------------------------------- |
| `NgOatButton`       | `<ng-oat-button>`        | Button with variant, size, and style options |
| `NgOatSplitButton`  | `<ng-oat-split-button>`  | Split button with dropdown action            |
| `NgOatBadge`        | `<ng-oat-badge>`         | Inline badge / tag                           |
| `NgOatAlert`        | `<ng-oat-alert>`         | Dismissible alert box                        |
| `NgOatCard`         | `<ng-oat-card>`          | Card container                               |
| `NgOatCardHeader`   | `<ng-oat-card-header>`   | Card header slot                             |
| `NgOatCardFooter`   | `<ng-oat-card-footer>`   | Card footer slot                             |
| `NgOatAccordion`    | `<ng-oat-accordion>`     | Expandable accordion panels                  |
| `NgOatTable`        | `<ng-oat-table>`         | Data table with sorting and custom templates |
| `NgOatPagination`   | `<ng-oat-pagination>`    | Page navigation                              |
| `NgOatProgress`     | `<ng-oat-progress>`      | Progress bar                                 |
| `NgOatMeter`        | `<ng-oat-meter>`         | Meter / gauge                                |
| `NgOatSpinner`      | `<ng-oat-spinner>`       | Loading spinner                              |
| `NgOatSwitch`       | `<ng-oat-switch>`        | Toggle switch                                |
| `NgOatSkeleton`     | `<ng-oat-skeleton>`      | Skeleton loading placeholder                 |
| `NgOatBreadcrumb`   | `<ng-oat-breadcrumb>`    | Breadcrumb navigation                        |
| `NgOatAvatar`       | `<ng-oat-avatar>`        | User avatar with image/initials              |
| `NgOatFileUpload`   | `<ng-oat-file-upload>`   | Drag-and-drop file upload                    |
| `NgOatInputOtp`     | `<ng-oat-input-otp>`     | OTP / PIN code input                         |
| `NgOatSearchInput`  | `<ng-oat-search-input>`  | Search input with clear button               |
| `NgOatSeparator`    | `<ng-oat-separator>`     | Horizontal / vertical separator              |
| `NgOatToggle`       | `<ng-oat-toggle>`        | Toggle button                                |
| `NgOatToggleGroup`  | `<ng-oat-toggle-group>`  | Toggle button group                          |
| `NgOatChip`         | `<ng-oat-chip>`          | Chip / tag                                   |
| `NgOatChipGroup`    | `<ng-oat-chip-group>`    | Chip group container                         |
| `NgOatChipInput`    | `<ng-oat-chip-input>`    | Input with chip creation                     |
| `NgOatCarousel`     | `<ng-oat-carousel>`      | Image/content carousel                       |
| `NgOatCardCarousel` | `<ng-oat-card-carousel>` | Product card carousel                        |

### Component Wrappers (full Angular component versions of directives)

| Component                | Selector            | Description                     |
| ------------------------ | ------------------- | ------------------------------- |
| `NgOatDropdownComponent` | `<ng-oat-dropdown>` | Dropdown menu                   |
| `NgOatTooltipComponent`  | `<ng-oat-tooltip>`  | Tooltip with content projection |
| `NgOatSidebarComponent`  | `<ng-oat-sidebar>`  | Sidebar / drawer                |
| `NgOatTabsComponent`     | `<ng-oat-tabs>`     | Tab navigation                  |
| `NgOatDialogComponent`   | `<ng-oat-dialog>`   | Modal dialog                    |

### Directives (attribute-based, for existing markup)

| Directive       | Selector          | Description                             |
| --------------- | ----------------- | --------------------------------------- |
| `NgOatDropdown` | `[ngOatDropdown]` | Attach dropdown behavior to any element |
| `NgOatTooltip`  | `[ngOatTooltip]`  | Attach tooltip to any element           |
| `NgOatSidebar`  | `[ngOatSidebar]`  | Control sidebar open/close              |
| `NgOatTabs`     | `[ngOatTabs]`     | Attach tab switching behavior           |
| `NgOatDialog`   | `[ngOatDialog]`   | Control dialog open/close               |

### Signal Forms

| Component         | Selector               | Description                   |
| ----------------- | ---------------------- | ----------------------------- |
| `NgOatInput`      | `<ng-oat-input>`       | Text / email / number input   |
| `NgOatTextarea`   | `<ng-oat-textarea>`    | Multi-line textarea           |
| `NgOatSelect`     | `<ng-oat-select>`      | Select dropdown               |
| `NgOatCheckbox`   | `<ng-oat-checkbox>`    | Checkbox                      |
| `NgOatRadioGroup` | `<ng-oat-radio-group>` | Radio button group            |
| `NgOatFormError`  | `<ng-oat-form-error>`  | Form validation error display |

### Services & Providers

| Export                | Description                                         |
| --------------------- | --------------------------------------------------- |
| `provideNgOat()`      | Core provider — call in your `app.config.ts`        |
| `provideNgOatTheme()` | Optional theme provider for runtime token overrides |
| `NgOatThemeRef`       | Injectable ref for runtime theme switching          |
| `NgOatToast`          | Programmatic toast notification service             |
| `OAT_TOKEN_MAP`       | Map of all available CSS design tokens              |

---

## Theming

Override design tokens at runtime using the theme provider:

```typescript
provideNgOatTheme({
  tokens: {
    '--oat-primary': '#6366f1',
    '--oat-radius-medium': '8px',
  },
});
```

Or override tokens in plain CSS:

```css
:root {
  --primary: #6366f1;
  --radius-md: 8px;
}
```

---

## Compatibility

| ng-oat | Angular | Node.js |
| ------ | ------- | ------- |
| 0.1.x  | ^21.0.0 | >= 22   |

---

## Links

- **Documentation & Demos:** [ng-oat.letsprogram.in](https://ng-oat.letsprogram.in)
- **GitHub:** [yshashi/ng-oat-workspace](https://github.com/yshashi/ng-oat-workspace)
- **Oat CSS Framework:** [oat.ink](https://oat.ink) by [knadh](https://github.com/knadh/oat)
- **npm:** [@letsprogram/ng-oat](https://www.npmjs.com/package/@letsprogram/ng-oat)

---

## License

MIT — see [LICENSE](./LICENSE)