npm package: @sinequa/ui
Description: [![npm version](https://img.shields.io/npm/v/@sinequa/ui.svg)](https://npm.sinequa.com/@sinequa/ui) [![Angular](https://img.shields.io/badge/Angular-v20-red.svg)](https://angular.dev) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)]
Latest version: 0.2.19

# @sinequa/ui

[![npm version](https://img.shields.io/npm/v/@sinequa/ui.svg)](https://npm.sinequa.com/@sinequa/ui)
[![Angular](https://img.shields.io/badge/Angular-v20-red.svg)](https://angular.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)

> Modern, accessible Angular UI components and design system primitives for building beautiful applications.

## Overview

**@sinequa/ui** is a comprehensive design system and UI component library built for Angular 20+. It provides a complete set of primitives and components including buttons, cards, dialogs, forms, navigation, and more. All components are standalone, fully typed, and follow modern Angular best practices.

### Key Features

- 🎨 **Modern Design System** - Complete set of UI primitives with consistent styling
- ♿ **Accessible** - WCAG 2.1 AA compliant with proper ARIA attributes
- 🎭 **Themeable** - Built-in theme support with dark mode
- 📦 **Tree-Shakeable** - Optimized bundle size with standalone components
- 🔷 **TypeScript-First** - Full type safety and IntelliSense support
- 🚀 **Modern Angular** - Uses signals, standalone components, and modern control flow

## Installation

```bash
npm install @sinequa/ui
```

### Peer Dependencies

```json
{
  "@angular/common": "^20.0.0",
  "@angular/core": "^20.0.0",
  "rxjs": "^7.8.0"
}
```

## Quick Start

### Basic Usage

```typescript
import { Component } from '@angular/core';
import { ButtonComponent } from '@sinequa/ui';
import { CardComponent, CardHeaderComponent, CardContentComponent } from '@sinequa/ui';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [ButtonComponent, CardComponent, CardHeaderComponent, CardContentComponent],
  template: `
    <card>
      <card-header>
        <h2>Welcome</h2>
      </card-header>
      <card-content>
        <p>Build beautiful UIs with @sinequa/ui</p>
        <button variant="default">Get Started</button>
      </card-content>
    </card>
  `
})
export class ExampleComponent {}
```

### With Theme

```typescript
import { provideTheme } from '@sinequa/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideTheme({
      theme: 'chapsvision',
      darkMode: 'auto'
    })
  ]
};
```

## Component Library

### Form Controls

#### Button

Versatile button component with multiple variants, sizes, and icon support.

```typescript
import { ButtonComponent } from '@sinequa/ui';

// In template
<button variant="default">Default</button>
<button variant="outline">Outline</button>
<button variant="ghost">Ghost</button>
<button size="sm">Small Button</button>
<button size="icon"><svg>...</svg></button>
```

**Variants:** `default`, `outline`, `ghost`, `destructive`, `link`  
**Sizes:** `default`, `sm`, `lg`, `icon`, `icon-sm`, `icon-xs`

#### Input

Styled input components with validation support.

```typescript
import { InputComponent, InputGroupComponent } from '@sinequa/ui';

// Basic input
<input type="text" placeholder="Enter text..." />

// Input group with addon
<input-group>
  <input-group-addon><svg>...</svg></input-group-addon>
  <input type="search" />
</input-group>
```

#### Search Input

Advanced search input with icon and clear button.

```typescript
import { SearchInputComponent } from '@sinequa/ui';

<search-input 
  placeholder="Search..." 
  [(value)]="searchQuery"
  (search)="onSearch($event)" />
```

#### Switch

Toggle switch component for boolean values.

```typescript
import { SwitchComponent } from '@sinequa/ui';

<switch [(checked)]="isEnabled" />
```

### Layout Components

#### Card

Container component for content grouping.

```typescript
import { 
  CardComponent, 
  CardHeaderComponent, 
  CardContentComponent,
  CardFooterComponent 
} from '@sinequa/ui';

<card>
  <card-header>
    <h3>Card Title</h3>
  </card-header>
  <card-content>
    Card content goes here
  </card-content>
  <card-footer>
    <button>Action</button>
  </card-footer>
</card>
```

#### Divider

Horizontal and vertical dividers for content separation.

```typescript
import { Separator } from '@sinequa/ui';

<separator />
<separator orientation="vertical" />
```

#### Page Header

Styled header component for page titles.

```typescript
import { PageHeaderComponent } from '@sinequa/ui';

<page-header>
  <h1>Page Title</h1>
</page-header>
```

### Navigation Components

#### Tabs

Tab navigation with multiple variants.

```typescript
import { TabsComponent, TabsListComponent, TabComponent, TabContent } from '@sinequa/ui';

<tabs>
  <tabs-list>
    <tab value="tab1" [active]="true">Tab 1</tab>
    <tab value="tab2">Tab 2</tab>
    <tab value="tab3">Tab 3</tab>
  </tabs-list>
  <tab-content value="tab1" />
  <tab-content value="tab2" />
  <tab-content value="tab3" />
</tabs>
```

#### Sidebar

Flexible sidebar navigation component.

```typescript
import { 
  SidebarComponent, 
  SidebarItemComponent,
  SidebarInsetComponent 
} from '@sinequa/ui';

<sidebar>
  <sidebar-item [active]="true">Dashboard</sidebar-item>
  <sidebar-item>Settings</sidebar-item>
</sidebar>
```

#### Menu

Dropdown menu with keyboard navigation.

```typescript
import { 
  MenuComponent, 
  MenuContentComponent, 
  MenuItemComponent 
} from '@sinequa/ui';

<menu>
  <button>Menu</button>
  <menu-content>
    <menu-item>Action 1</menu-item>
    <menu-item>Action 2</menu-item>
  </menu-content>
</menu>
```

### Overlay Components

#### Dialog

Modal dialog component.

```typescript
import { 
  DialogComponent, 
  DialogHeaderComponent,
  DialogContentComponent,
  DialogFooterComponent 
} from '@sinequa/ui';

<dialog>
  <dialog-header>
    <h2>Dialog Title</h2>
  </dialog-header>
  <dialog-content>
    Dialog content
  </dialog-content>
  <dialog-footer>
    <button>Close</button>
  </dialog-footer>
</dialog>
```

#### Dropdown

Flexible dropdown component.

```typescript
import { DropdownDirective } from '@sinequa/ui';

<button popovertarget="mydropdown">Toggle</button>
<div dropdown id="mydropdown">
  Dropdown content
</div>
```

#### Popover

Popover component for contextual information.

```typescript
import { PopoverDirective } from '@sinequa/ui';

<button popovertarget="mypopover">Hover me</button>
<div popover id="mypopover">
  Popover content
</div>
```

### Display Components

#### Badge

Small status/label component.

```typescript
import { BadgeComponent } from '@sinequa/ui';

<badge>New</badge>
<badge variant="secondary">Beta</badge>
<badge variant="destructive">Error</badge>
```

**Variants:** `default`, `secondary`, `accent`, `destructive`, `outline`

#### Avatar

User avatar with fallback support.

```typescript
import { 
  AvatarComponent, 
  AvatarImageComponent, 
  AvatarFallbackComponent 
} from '@sinequa/ui/avatar';

<avatar>
  <avatar-image src="avatar.jpg" alt="User" />
  <avatar-fallback>JD</avatar-fallback>
</avatar>
```

### Icon Components

Comprehensive SVG icon library:

```typescript
import { 
  ChevronRightIcon,
  ChevronLeftIcon,
  SearchIcon,
  FilterIcon,
  BookmarkIcon,
  XMarkIcon,
  // ... and many more
} from '@sinequa/ui';

<chevron-right-icon />
<search-icon />
```

**Available Icons:** ArrowLeft, Bookmark, ChevronRight, Ellipsis, Envelope, Files, Filter, Folder, Link, Star, Trash, User, XMark, and more.

## Theming

### Available Themes

- `chapsvision` - Modern professional theme (default)
- `orange` - Vibrant orange accent
- `violet` - Purple-based theme
- `yellow` - Warm yellow theme
- `green` - Nature-inspired green

### Custom Theme

Create your own theme by overriding CSS custom properties:

```css
:root {
  /* Colors (HSL format) */
  --primary: 220 90% 56%;
  --secondary: 220 14% 96%;
  --accent: 24 80% 58%;
  --background: 0 0% 100%;
  --foreground: 222 47% 11%;
  --muted: 220 14% 96%;
  --muted-foreground: 220 9% 46%;
  
  /* Borders */
  --border: 220 13% 91%;
  --ring: 220 90% 56%;
  
  /* Radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-button: 100vw;
}

/* Dark mode */
.dark {
  --background: 222 47% 11%;
  --foreground: 210 40% 98%;
  /* ... other dark mode values */
}
```

## Styling & Customization

### Tailwind CSS Integration

@sinequa/ui is built with Tailwind CSS. Extend or customize using Tailwind classes:

```html
<button class="w-full justify-start">
  Full Width Button
</button>

<card class="max-w-md mx-auto shadow-lg">
  Custom styled card
</card>
```

### Component Variants

Most components support variants for different styles:

```typescript
// Button variants
<button variant="default">Default</button>
<button variant="destructive">Delete</button>

// Badge variants
<badge variant="secondary">Label</badge>
<badge variant="outline">Outlined</badge>
```

## Accessibility

All components follow WCAG 2.1 AA guidelines:

- ✅ Proper ARIA attributes
- ✅ Keyboard navigation support
- ✅ Focus management
- ✅ Screen reader compatibility
- ✅ Color contrast compliance

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Requirements

- Angular 20+
- TypeScript 5.7+
- Node.js 18+

## Package Structure

```bash
@sinequa/ui/
├── button/              # Button components
├── badge/               # Badge component
├── card/                # Card components
├── dialog/              # Dialog components
├── dropdown/            # Dropdown components
├── input/               # Input components
├── input-group/         # Input group components
├── menu/                # Menu components
├── popover/             # Popover components
├── search/              # Search components
├── sidebar/             # Sidebar components
├── switch/              # Switch component
├── tabs/                # Tab components
├── avatar/              # Avatar components
├── divider/             # Divider components
├── page-header/         # Page header component
├── icons/               # Icon library
└── theme/               # Theme utilities
```

## License

Proprietary - Copyright © 2025 Sinequa. All rights reserved.

## Support

- 📧 Email: [support@sinequa.com](mailto:support@sinequa.com)
- 📚 Documentation: [sinequa.com/docs](https://sinequa.com/docs)
- 🌐 Website: [www.sinequa.com](https://www.sinequa.com)

---

**Part of the Sinequa Atomic Design System**