@eagami/ui 0.2.0 → 0.3.0

package/README.md

@@ -1,388 +1,388 @@
-# @eagami/ui
-
-A lightweight, accessible Angular UI component library built on CSS custom properties. Zero runtime dependencies beyond Angular itself.
-
 <p align="center">
-  <img src="logo.svg" alt="eagami-ui logo" width="150" />
+  <img src="docs/images/header.png" alt="eagami design system — elegant web design." width="560" />
 </p>
 
+A lightweight, accessible Angular component library built on CSS custom properties. Ready to use out of the box — install, import, and start building.
+
+Every component is standalone, signal-based, and fully themed via design tokens. No wrapping modules, no complex setup, no runtime style conflicts. Designed to be AI-friendly with clear APIs, consistent patterns, and comprehensive documentation that makes it easy for both developers and AI assistants to work with.
+
 ## Why @eagami/ui?
 
-| | **@eagami/ui** | Angular Material | PrimeNG | ng-bootstrap | ng-zorro (Ant Design) |
+**Approx. component sizes (gzipped)¹**
+
+| Component | **@eagami/ui** | Angular Material | PrimeNG | ng-bootstrap | ng-zorro |
 |---|---|---|---|---|---|
-| Approx. bundle (Button + Input, gzipped)¹ | ~8 KB | ~60 KB | ~35 KB | ~55 KB | ~120 KB |
-| External CSS dependency | ❌ | ❌ | Optional | Bootstrap (~30 KB) | ❌ |
-| CSS custom property theming | ✅ | Partial (MDC) | ✅ | ❌ (Sass vars) | ❌ |
-| Signals-first API | ✅ | Partial | ❌ | ❌ | ❌ |
-| `OnPush` by default | ✅ | Partial | ❌ | ❌ | ❌ |
-| Runtime dependencies | 0 | CDK + animations | PrimeIcons² | Bootstrap CSS | CDK |
+| Button | ~2 KB | ~12 KB | ~8 KB | ~10 KB | ~18 KB |
+| Input | ~4 KB | ~25 KB | ~14 KB | ~20 KB | ~35 KB |
+| Checkbox | ~2 KB | ~15 KB | ~9 KB | ~12 KB | ~22 KB |
+| Dropdown / Select | ~4 KB | ~30 KB | ~20 KB | ~25 KB | ~40 KB |
+| Dialog / Modal | ~2 KB | ~20 KB | ~15 KB | ~18 KB | ~30 KB |
 
-> ¹ All numbers are approximate and depend on configuration, tree-shaking, and Angular version. Measured with production builds and `@angular/build`.
+> ¹ Approximate — depends on configuration, tree-shaking, and Angular version. @eagami/ui sizes measured from production build.
 
+| | **@eagami/ui** | Angular Material | PrimeNG | ng-bootstrap | ng-zorro |
+|---|---|---|---|---|---|
+| External CSS dependency | No | No | Optional | Bootstrap (~30 KB) | No |
+| CSS custom property theming | Yes | Partial (MDC) | Yes | No (Sass vars) | No |
+| Signals-first API | Yes | Partial | No | No | No |
+| `OnPush` by default | Yes | Partial | No | No | No |
+| Runtime dependencies | 0 | CDK + animations | PrimeIcons² | Bootstrap CSS | CDK |
 > ² PrimeNG components are tree-shakable but PrimeIcons font (~50 KB) is typically included globally.
 
-## Requirements
+## Features
 
-- Angular 21+
-- A CSS preprocessor that supports SCSS (standard with Angular CLI)
+- **Zero configuration** — works immediately after install with sensible defaults
+- **Standalone components** — no `NgModule` boilerplate, just import and use
+- **Signal-based** — built on Angular's modern reactivity primitives (`input()`, `model()`, `output()`)
+- **Full theming via CSS custom properties** — override any design token on `:root` or scope overrides to individual components
+- **Dark mode built in** — automatic via `prefers-color-scheme`, no extra setup
+- **Accessible** — ARIA attributes, keyboard navigation, focus management, and screen reader support throughout
+- **Form-ready** — `ControlValueAccessor` on all form components (Input, Textarea, Checkbox, Switch, Radio, Dropdown)
+- **Lightweight** — no third-party runtime dependencies beyond Angular and `tslib`
+- **Tree-shakeable** — only the components you import end up in your bundle
 
 ## Installation
 
-```sh
+```bash
 npm install @eagami/ui
+# or
+pnpm add @eagami/ui
 ```
 
-## Setup
-
-### 1. Import the global stylesheet
+Add the global stylesheet to your `angular.json` (or import it in your root SCSS):
 
-In `angular.json`:
 ```json
 "styles": ["node_modules/@eagami/ui/src/styles/eagami-ui.scss"]
 ```
 
-Or in your root `styles.scss`:
-```scss
-@use '@eagami/ui/src/styles/eagami-ui';
-```
+Load the fonts in your `index.html`:
 
-### 2. Import components
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=Syne:wght@400;500;600;700&display=swap" />
+```
 
-Components are standalone — import only what you use:
+## Quick start
 
-```ts
-import { ButtonComponent, InputComponent, CheckboxComponent } from '@eagami/ui';
+```typescript
+import { ButtonComponent } from '@eagami/ui';
 
 @Component({
-  imports: [ButtonComponent, InputComponent, CheckboxComponent],
-  ...
+  imports: [ButtonComponent],
+  template: `<ea-button variant="primary" (clicked)="save()">Save</ea-button>`,
 })
+export class MyComponent {
+  save() { /* ... */ }
+}
 ```
 
-## Usage
+No modules to register, no providers to configure. Every component works the same way — import it, drop it in your template.
 
-### Button
+## Components
 
-```html
-<ea-button variant="primary" (clicked)="onSave($event)">Save</ea-button>
+### Button
 
-<ea-button variant="secondary" size="sm" [disabled]="true">Cancel</ea-button>
+Variants: `primary` | `secondary` | `ghost` | `danger`. Sizes: `sm` | `md` | `lg`. Supports `loading`, `disabled`, and `fullWidth` states.
 
-<ea-button variant="danger" [loading]="isDeleting()">Delete</ea-button>
+```html
+<ea-button variant="primary" size="md" [loading]="isSaving" (clicked)="save()">
+  Save changes
+</ea-button>
 ```
 
-**Inputs**
-
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `primary \| secondary \| ghost \| danger` | `primary` | Visual style |
-| `size` | `sm \| md \| lg` | `md` | Button size |
-| `type` | `button \| submit \| reset` | `button` | Native button type |
-| `disabled` | `boolean` | `false` | Disables the button |
-| `loading` | `boolean` | `false` | Shows a spinner, disables interaction |
-| `fullWidth` | `boolean` | `false` | Stretches to fill container |
-| `aria-label` | `string` | — | Accessible label for icon-only buttons |
-
-**Outputs**
-
-| Output | Type | Description |
-|---|---|---|
-| `clicked` | `MouseEvent` | Emitted on click (not emitted when disabled or loading) |
+<img src="docs/images/button.png" alt="Button component" width="560" />
 
 ---
 
 ### Input
 
+Full `ControlValueAccessor` support. Types: `text` | `email` | `password` | `number` | `search` | `tel` | `url`. Built-in password visibility toggle.
+
 ```html
 <ea-input
   label="Email"
   type="email"
   placeholder="you@example.com"
+  hint="We'll never share your email"
   [(value)]="email" />
-
-<ea-input
-  label="Password"
-  type="password"
-  hint="At least 8 characters"
-  [required]="true" />
-
-<ea-input
-  label="Username"
-  error="This username is already taken"
-  [(value)]="username" />
 ```
 
-Works with Angular reactive forms and template-driven forms via `ControlValueAccessor`:
+<img src="docs/images/input.png" alt="Input component" width="560" />
 
-```ts
-// Reactive
-this.form = this.fb.group({ email: ['', Validators.required] });
-```
-```html
-<ea-input label="Email" formControlName="email" />
-```
+---
 
-**Inputs**
+### Textarea
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `label` | `string` | — | Field label |
-| `type` | `text \| email \| password \| number \| search \| tel \| url` | `text` | Input type |
-| `placeholder` | `string` | `''` | Placeholder text |
-| `size` | `sm \| md \| lg` | `md` | Field size |
-| `status` | `default \| error \| success` | `default` | Visual validation state |
-| `hint` | `string` | — | Helper text below the input |
-| `error` | `string` | — | Error message (also sets status to `error`) |
-| `disabled` | `boolean` | `false` | Disables the input |
-| `readonly` | `boolean` | `false` | Makes the input read-only |
-| `required` | `boolean` | `false` | Marks as required |
+Mirrors the Input API with `ControlValueAccessor`. Configurable `rows`, `resize` (`none` | `vertical` | `horizontal` | `both`), and `maxlength`.
 
-**Two-way binding**
+```html
+<ea-textarea
+  label="Message"
+  placeholder="Enter your message…"
+  hint="Maximum 500 characters"
+  [rows]="4"
+  [(value)]="message" />
+```
 
-| Binding | Type | Description |
-|---|---|---|
-| `[(value)]` | `string` | Two-way signal-based value binding |
+<img src="docs/images/textarea.png" alt="Textarea component" width="560" />
 
 ---
 
 ### Checkbox
 
-```html
-<ea-checkbox label="Accept terms" [(checked)]="accepted" />
+`ControlValueAccessor` with `indeterminate` state support. Sizes: `sm` | `md` | `lg`.
 
-<ea-checkbox label="Select all" [indeterminate]="true" />
-
-<ea-checkbox label="Disabled" [disabled]="true" />
+```html
+<ea-checkbox label="Accept terms and conditions" [(checked)]="accepted" />
 ```
 
-Works with Angular forms via `ControlValueAccessor`.
-
-**Inputs**
+<img src="docs/images/checkbox.png" alt="Checkbox component" width="560" />
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `label` | `string` | — | Checkbox label |
-| `size` | `sm \| md \| lg` | `md` | Checkbox size |
-| `disabled` | `boolean` | `false` | Disables the checkbox |
-| `required` | `boolean` | `false` | Marks as required |
-| `indeterminate` | `boolean` | `false` | Shows indeterminate (minus) state |
+---
 
-**Two-way binding**
+### Switch
 
-| Binding | Type | Description |
-|---|---|---|
-| `[(checked)]` | `boolean` | Two-way checked state |
+Toggle switch with `ControlValueAccessor`. Sizes: `sm` | `md` | `lg`.
 
-**Outputs**
+```html
+<ea-switch label="Enable notifications" [(checked)]="notificationsOn" />
+```
 
-| Output | Type | Description |
-|---|---|---|
-| `changed` | `boolean` | Emitted when the checked state changes |
+<img src="docs/images/switch.png" alt="Switch component" width="560" />
 
 ---
 
-### Radio
+### Radio Group
 
-Radio buttons are composed of a `ea-radio-group` wrapper and `ea-radio` items:
+Composite pattern with `ControlValueAccessor`. Supports `vertical` and `horizontal` orientation.
 
 ```html
-<ea-radio-group [(value)]="colour">
-  <ea-radio value="red" label="Red" />
-  <ea-radio value="green" label="Green" />
-  <ea-radio value="blue" label="Blue" />
+<ea-radio-group [(value)]="plan">
+  <ea-radio value="free" label="Free" />
+  <ea-radio value="pro" label="Pro" />
+  <ea-radio value="enterprise" label="Enterprise" />
 </ea-radio-group>
 ```
 
-The group implements `ControlValueAccessor` for Angular forms integration.
-
-**RadioGroup Inputs**
+<img src="docs/images/radio.png" alt="Radio group component" width="560" />
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `name` | `string` | auto | Shared name for all radios |
-| `size` | `sm \| md \| lg` | `md` | Size of all radios |
-| `orientation` | `vertical \| horizontal` | `vertical` | Layout direction |
-| `disabled` | `boolean` | `false` | Disables all radios |
+---
 
-**RadioGroup Two-way binding**
+### Dropdown
 
-| Binding | Type | Description |
-|---|---|---|
-| `[(value)]` | `string` | Currently selected value |
+Select dropdown with `ControlValueAccessor` and keyboard navigation (Arrow keys, Enter/Space, Escape).
 
-**Radio Inputs**
+```html
+<ea-dropdown
+  label="Country"
+  placeholder="Select a country…"
+  [options]="countries"
+  [(value)]="selectedCountry" />
+```
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `value` | `string` | *required* | Option value |
-| `label` | `string` | — | Radio label |
-| `disabled` | `boolean` | `false` | Disables this radio |
+<img src="docs/images/dropdown.png" alt="Dropdown component" width="560" />
 
 ---
 
 ### Card
 
+Content container with variants: `elevated` | `outlined` | `filled`. Padding: `none` | `sm` | `md` | `lg` | `xl`. Customizable shadow via `--ea-card-shadow`.
+
 ```html
 <ea-card variant="elevated">
-  <span slot="header">Card Title</span>
-  Body content goes here.
-  <span slot="footer">
-    <ea-button size="sm">Action</ea-button>
+  <span eaCardHeader>Card Title</span>
+  Card body content goes here.
+  <span eaCardFooter>
+    <ea-button variant="secondary" size="sm">Cancel</ea-button>
+    <ea-button size="sm">Save</ea-button>
   </span>
 </ea-card>
 ```
 
-**Inputs**
+<img src="docs/images/card.png" alt="Card component" width="560" />
+
+---
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `elevated \| outlined \| filled` | `elevated` | Visual style |
-| `padding` | `none \| sm \| md \| lg` | `md` | Inner padding |
-| `fullWidth` | `boolean` | `false` | Stretches to fill container |
+### Avatar
 
-**Content slots**
+Image with initials or icon fallback. Sizes: `xs` | `sm` | `md` | `lg` | `xl`. Shapes: `circle` | `square`.
 
-| Slot | Description |
-|---|---|
-| `[slot=header]` | Card header / title area |
-| *(default)* | Card body content |
-| `[slot=footer]` | Card footer / actions area |
+```html
+<ea-avatar src="/photo.jpg" alt="User" size="lg" />
+<ea-avatar initials="MW" shape="square" />
+<ea-avatar />  <!-- shows fallback user icon -->
+```
 
-Header and footer are hidden when empty.
+<img src="docs/images/avatar.png" alt="Avatar component" width="560" />
 
 ---
 
-### Dropdown
+### Avatar Editor
+
+Canvas-based image editor with drag-and-drop upload, pan, zoom (slider + scroll wheel), and crop export. Outputs a `Blob` and data URL for use with the Avatar component.
 
 ```html
-<ea-dropdown
-  label="Country"
-  placeholder="Select a country…"
-  [options]="countries"
-  [(value)]="selectedCountry" />
+<ea-avatar-editor
+  shape="circle"
+  [canvasSize]="200"
+  (cropped)="onCropped($event)" />
+```
+
+<img src="docs/images/avatar-editor.png" alt="Avatar editor component" width="560" />
+
+---
+
+### Badge
+
+Semantic status indicators. Variants: `default` | `success` | `warning` | `error` | `info`. Sizes: `sm` | `md` | `lg`.
+
+```html
+<ea-badge variant="success">Active</ea-badge>
+<ea-badge variant="error">Failed</ea-badge>
 ```
 
-Options are passed as an array of `{ value, label, disabled? }` objects. Supports keyboard navigation (arrow keys, Enter, Escape). Implements `ControlValueAccessor`.
+<img src="docs/images/badge.png" alt="Badge component" width="560" />
 
-**Inputs**
+---
+
+### Spinner
+
+SVG loading indicator with `role="status"` for accessibility. Sizes: `sm` | `md` | `lg`.
+
+```html
+<ea-spinner size="md" label="Loading data" />
+```
+
+<img src="docs/images/spinner.png" alt="Spinner component" width="560" />
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `label` | `string` | — | Field label |
-| `placeholder` | `string` | `'Select…'` | Placeholder text |
-| `options` | `DropdownOption[]` | `[]` | Array of `{ value, label, disabled? }` |
-| `size` | `sm \| md \| lg` | `md` | Trigger size |
-| `disabled` | `boolean` | `false` | Disables the dropdown |
-| `required` | `boolean` | `false` | Marks as required |
-| `hint` | `string` | — | Helper text |
-| `error` | `string` | — | Error message |
+---
 
-**Two-way binding**
+### Divider
 
-| Binding | Type | Description |
-|---|---|---|
-| `[(value)]` | `string` | Selected option value |
+Visual separator with optional label. Orientation: `horizontal` | `vertical`.
 
-**Outputs**
+```html
+<ea-divider />
+<ea-divider label="or" />
+<ea-divider orientation="vertical" />
+```
 
-| Output | Type | Description |
-|---|---|---|
-| `changed` | `string` | Emitted when selection changes |
+<img src="docs/images/divider.png" alt="Divider component" width="560" />
 
 ---
 
 ### Dialog
 
+Built on the native `<dialog>` element for built-in focus trapping. Sizes: `sm` | `md` | `lg` | `full`. Two-way `open` binding.
+
 ```html
-<ea-button (clicked)="isOpen = true">Open</ea-button>
+<ea-button (clicked)="dialogOpen.set(true)">Open</ea-button>
 
-<ea-dialog [(open)]="isOpen">
-  <span slot="header">Confirm Action</span>
-  <p>Are you sure you want to proceed?</p>
+<ea-dialog [(open)]="dialogOpen" size="md">
+  <span slot="header">Confirm</span>
+  <p>Are you sure?</p>
   <span slot="footer">
-    <ea-button variant="secondary" (clicked)="isOpen = false">Cancel</ea-button>
-    <ea-button (clicked)="onConfirm()">Confirm</ea-button>
+    <ea-button variant="secondary" (clicked)="dialogOpen.set(false)">Cancel</ea-button>
+    <ea-button (clicked)="confirm()">Confirm</ea-button>
   </span>
 </ea-dialog>
 ```
 
-Uses the native `<dialog>` element with `showModal()` for proper focus trapping, backdrop, and accessibility.
+---
 
-**Inputs**
+### Tooltip
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `size` | `sm \| md \| lg \| full` | `md` | Dialog panel width |
-| `closeOnBackdrop` | `boolean` | `true` | Close on backdrop click |
-| `closeOnEscape` | `boolean` | `true` | Close on Escape key |
-| `showClose` | `boolean` | `true` | Show the close (×) button |
-| `aria-label` | `string` | — | Accessible label for the dialog |
+Directive that shows a positioned tooltip on hover and focus. Positions: `top` | `bottom` | `left` | `right`.
 
-**Two-way binding**
+```html
+<ea-button eaTooltip="Save your changes" tooltipPosition="top">Save</ea-button>
+```
 
-| Binding | Type | Description |
-|---|---|---|
-| `[(open)]` | `boolean` | Controls dialog visibility |
+---
 
-**Outputs**
+### Toast
 
-| Output | Type | Description |
-|---|---|---|
-| `opened` | `void` | Emitted when the dialog opens |
-| `closed` | `void` | Emitted when the dialog closes |
+Notification system via injectable `ToastService`. Variants: `default` | `success` | `warning` | `error` | `info`. Auto-dismiss with configurable duration. Full-width on mobile, independent widths on desktop.
 
-**Content slots**
+```typescript
+import { ToastService } from '@eagami/ui';
 
-| Slot | Description |
-|---|---|
-| `[slot=header]` | Dialog title |
-| *(default)* | Dialog body |
-| `[slot=footer]` | Dialog actions |
+export class MyComponent {
+  private toast = inject(ToastService);
 
----
+  save() {
+    this.toast.success('Changes saved');
+  }
+
+  handleError() {
+    this.toast.error('Something went wrong');
+  }
+}
+```
+
+Add the toast outlet once in your root template:
+
+```html
+<ea-toast />
+```
+
+<img src="docs/images/toast.png" alt="Toast component" width="560" />
+
+## Icons
+
+Built-in SVG icon components following the Feather icon style (24x24 viewBox, stroke-based, inherits `currentColor`):
+
+`ea-icon-check` | `ea-icon-x` | `ea-icon-user` | `ea-icon-info` | `ea-icon-loader` | `ea-icon-alert-circle` | `ea-icon-eye` | `ea-icon-eye-off` | `ea-icon-google`
+
+```html
+<ea-icon-check />
+<ea-icon-info />
+```
 
 ## Theming
 
-All components use CSS custom properties. Override them after importing the stylesheet:
+All visual properties are controlled through CSS custom properties defined on `:root`. Override any token to customize the entire library:
 
 ```css
 :root {
-  /* Brand colour — affects primary buttons, focus rings, etc. */
-  --color-brand-default: #7c3aed;
-  --color-brand-hover:   #6d28d9;
-  --color-brand-active:  #5b21b6;
-  --color-brand-subtle:  #f5f3ff;
-  --color-brand-muted:   #ede9fe;
+  --color-primary-600: #2563eb;
+  --font-family-sans: 'Inter', sans-serif;
+  --radius-md: 0.5rem;
 }
 ```
 
-See [`src/styles/tokens/`](src/styles/tokens/) for the full token reference.
+Component-level overrides are available where useful:
 
----
-
-## Development
+```css
+.my-card {
+  --ea-card-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
+  --ea-button-font-weight: 600;
+}
+```
 
-```sh
-# Install dependencies
-pnpm install
+See [`src/styles/tokens/`](src/styles/tokens/) for the full token reference.
 
-# Run the sandbox dev app
-pnpm sandbox
+## Peer dependencies
 
-# Run Storybook (component explorer)
-pnpm storybook
+| Package | Version |
+|---------|---------|
+| `@angular/common` | `^21.0.0` |
+| `@angular/core` | `^21.0.0` |
+| `@angular/forms` | `^21.0.0` |
+| `rxjs` | `^7.0.0` |
 
-# Run tests
-pnpm test
+## Development
 
-# Build the library
-pnpm build
+```bash
+pnpm install       # Install dependencies
+pnpm start         # Run sandbox dev app
+pnpm storybook     # Run Storybook
+pnpm test          # Run tests
+pnpm build         # Build the library
+pnpm lint          # Lint
 ```
 
-## Contributing
-
-Issues and PRs are welcome. Please open an issue before submitting large changes.
-
 ## License
 
 MIT