npm package: @raintonic/formaui
Description: A modern Angular UI component library with theming support
Latest version: 0.2.1

# FormaUI

A modern, standalone Angular UI component library with built-in theming, CDK primitives, and tree-shakable imports.

[![npm version](https://img.shields.io/npm/v/formaui.svg)](https://www.npmjs.com/package/@raintonic/formaui)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Angular](https://img.shields.io/badge/Angular-21+-dd0031.svg)](https://angular.dev)

## Features

- **45 standalone components** — no NgModules, just import and use
- **Tree-shakable** — secondary entry points via ng-packagr, import only what you need
- **Theming system** — CSS custom properties with light/dark themes out of the box
- **CDK layer** — overlay/portal system, drag-drop, virtual-scroll, form-field primitives
- **Signals-first** — reactive state management with Angular signals
- **Accessible** — built-in a11y support with testing utilities (axe-core)
- **Form integration** — components implement `RtFormFieldControl` for seamless `fui-form-field` integration

## Installation

```bash
npm install @raintonic/formaui
```

### Peer Dependencies

```json
{
  "@angular/common": "^21.0.0",
  "@angular/core": "^21.0.0",
  "@angular/forms": "^21.0.0"
}
```

## Setup

Import the base styles in your `styles.scss`:

```scss
@use '@raintonic/formaui/styles' as fui;
```

## Usage

All imports use secondary entry points:

```typescript
import { ButtonDirective } from '@raintonic/formaui/components/button';
import { RtFormFieldComponent } from '@raintonic/formaui/components/form-field';
import { InputDirective } from '@raintonic/formaui/components/input';
import { ThemeService } from '@raintonic/formaui/services/theme';
```

### Button

```html
<button fui-button variant="primary">Save</button>
<button fui-button variant="outlined">Cancel</button>
```

### Form Field

```html
<fui-form-field>
  <fui-label>Email</fui-label>
  <input fuiInput type="email" />
</fui-form-field>
```

### Theme Switching

```typescript
import { ThemeService } from '@raintonic/formaui/services/theme';

export class AppComponent {
  private theme = inject(ThemeService);

  toggleDark() {
    this.theme.toggleTheme();
  }
}
```

## Components

All components use the `fui` prefix and are standalone.

| Category | Components |
|---|---|
| **Forms** | `autocomplete` `checkbox` `date-picker` `dynamic-form` `file-upload` `form-field` `input` `number-input` `password-input` `radio` `select` `slider` `time-picker` `toggle` `tree-select` |
| **Data** | `data-table` `list` `paginator` `tree` `tree-table` |
| **Layout** | `accordion` `card` `divider` `sidebar` `side-panel` `tab` `toolbar` |
| **Navigation** | `breadcrumb` `menu` `big-menu` `stepper` |
| **Feedback** | `alert` `badge` `empty-state` `progressbar` `skeleton` `spinner` `tag` `tooltip` |
| **Actions** | `button` `button-group` `drawer` `popover` |
| **Display** | `avatar` `icon` |

### Import Pattern

```typescript
import { <Component> } from '@raintonic/formaui/components/<name>';
```

## CDK

Low-level primitives for building custom components.

| Module | Description |
|---|---|
| `formaui/cdk/overlay` | Overlay and portal positioning system |
| `formaui/cdk/drag-drop` | Drag and drop functionality |
| `formaui/cdk/virtual-scroll` | Virtual scrolling for large lists |
| `formaui/cdk/form-field` | Form field infrastructure and control interface |

## Services

| Service | Import | Description |
|---|---|---|
| **Dialog** | `formaui/services/dialog` | Modal dialog management |
| **Notification** | `formaui/services/notification` | Toast notifications |
| **Theme** | `formaui/services/theme` | Runtime theme switching |

## Theming

FormaUI uses CSS custom properties (`--fui-*`) for all design tokens. Two themes are included:

- **Light** (default) — applied to `:root`
- **Dark** — toggled via `ThemeService`

Tokens cover spacing, typography, colors, motion, and elevation. Override any `--fui-*` variable to customize.

## Development

```bash
npm run build:lib       # Build the library
npm test                # Run tests (Jest)
npm run lint            # Lint
npm run serve:docs      # Serve docs app locally
```

Requires Node >= 22.16.0.

## License

[MIT](https://opensource.org/licenses/MIT)