# @sinequa/atomic-angular

[![npm version](https://img.shields.io/npm/v/@sinequa/atomic-angular.svg)](https://npm.sinequa.com/@sinequa/atomic-angular)
[![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/)

> A comprehensive Angular component library and design system for building modern Sinequa search applications.

## Overview

**@sinequa/atomic-angular** provides a complete set of UI components, features, and utilities for building enterprise-grade search applications powered by Sinequa. Built with Angular 20+ and modern web standards, it offers a consistent, accessible, and themeable framework with TypeScript-first development experience.

## Installation

```bash
npm install @sinequa/atomic-angular
```

### Peer Dependencies

```json
{
  "@angular/common": "^20.0.0",
  "@angular/core": "^20.0.0",
  "rxjs": "^7.8.0"
}
```

> ℹ️ The peer dependency above targets the **1.x** line (Angular 20). For the Angular 22
> line, see the compatibility table below.

## Versioning & Compatibility

`@sinequa/atomic-angular` is maintained across several **parallel version lines**, each
pinned to an Angular major and consumed by a specific product release. Pick the line that
matches the Angular version embedded in your product.

| Library line | Angular | Product release | Status | Install |
|---|---|---|---|---|
| **1.0.x** | 20 | 11.13.0 | 🩹 Maintenance — critical & bug fixes only | `npm i @sinequa/atomic-angular@~1.0` |
| **1.x** | 20 | 11.14.0 | ✅ Active — fixes + new features | `npm i @sinequa/atomic-angular@^1` |
| **2.x** | 22 | *future release* | 🚧 Upcoming — pre-release | `npm i @sinequa/atomic-angular@next` |

**How the lines work**

- **Each line is an independent version range.** A `1.0.x` patch and a `1.x` minor are
  unrelated number spaces — upgrading within a line never crosses an Angular major.
- **`~1.0`** keeps you on patch releases of the 11.13 line (no minor jumps).
  **`^1`** follows the active 1.x line (patches + minors, still Angular 20).
  **`@next` / `^2`** is the Angular 22 line, for the upcoming product release.
- A fix relevant to several lines is applied to each supported line independently, so you
  receive it on whichever line you track — without being forced onto a new Angular major.

> Maintainers: the branching and propagation process is documented in
> [`HOTFIX.md`](https://github.com/Product/sba-atomic-angular/blob/develop/HOTFIX.md).

## Features

### 🔐 Authentication & Authorization

- Complete authentication flows with SSO support
- Password management (expiry, forgotten, change)
- Route guards and access control
- Multi-language support (EN, FR, DE)

### 🔍 Advanced Search

- Powerful filter system with aggregations
- "Did You Mean" suggestions and autocomplete
- Recent and saved searches
- Bookmark and collection management
- Document preview and navigation
- Export functionality

### 🛠️ Developer Experience

- **TypeScript-first** with full type safety
- **Standalone components** (no NgModules required)
- **Signal-based reactivity** for better performance
- **Modern syntax**: @if, @for, @switch control flow
- **Tree-shakeable** for optimal bundle size

## Package Structure

### @sinequa/atomic-angular

```bash
components/       # Reusable UI components
  ├── backdrop/
  ├── document-locator/
  ├── navbar-tabs/
  ├── pagination/
  └── ...
  
features/         # Feature modules
  ├── auth/       # Authentication flows
  ├── filters/    # Filter system
  ├── bookmarks/  # Bookmark management
  ├── collections/
  └── ...
  
services/         # Business logic services
stores/           # State management
guards/           # Route guards
pipes/            # Custom pipes
utils/            # Utility functions
```

## Available Components

### Core Components

- `SearchInputComponent` - Advanced search input with autocomplete
- `FiltersComponent` - Dynamic filter system
- `PaginationComponent` - Result pagination
- `DocumentLocatorComponent` - Document navigation
- `PreviewComponent` - Document preview
- `BackdropComponent` - Backdrop overlay
- `NavbarTabsComponent` - Navigation tabs
- `NoResultComponent` - No results display
- `SortSelectorComponent` - Sort options selector

### Authentication

- `SignInFormComponent` - User sign-in
- `ChangePasswordFormComponent` - Password change
- `ForgotPasswordFormComponent` - Password recovery
- `AuthGuard` - Route protection
- `PasswordExpiryGuard` - Password expiry detection

### Features

- Alerts management
- Bookmarks system
- Collections management
- Advanced search drawer
- Export functionality
- Feedback system
- Labels management
- Recent searches
- Saved searches

## API Documentation

### Services

```typescript
// ApplicationService - Core application logic
import { ApplicationService } from '@sinequa/atomic-angular';

// AggregationsService - Filter management
import { AggregationsService } from '@sinequa/atomic-angular';

// AuthService - Authentication
import { AuthService } from '@sinequa/atomic-angular';
```

### Guards

```typescript
import { AuthGuard, PasswordExpiryGuard } from '@sinequa/atomic-angular';

const routes: Routes = [
  {
    path: 'search',
    canActivate: [AuthGuard],
    component: SearchComponent
  },
  {
    path: 'profile',
    canActivate: [AuthGuard, PasswordExpiryGuard],
    component: ProfileComponent
  }
];
```

## Changelog

### Recent Releases

**v0.3.8** (2025-12-18)

- Added chevron icon in document locator menu
- Improved component structure

**v0.3.7** (2025-12-17)  

- Fixed parent selection in filters with `linkChildren`
- Enhanced selection state management

**v0.3.6** (2025-12-17)

- Enhanced "Did You Mean" component styling
- Added text truncation for long filter names

**v0.3.4** (2025-12-15)

- Complete password management flows
- Added `PasswordExpiryGuard`

**v0.3.0** (2025-12-09) - Major Release

- New Chapsvision theme system
- Standardized icon components
- New `InputGroup` architecture
- Badge API changes

See [full changelog](https://github.com/Product/sba-atomic-angular/blob/develop/changelogs/CHANGELOG_0.2.10_to_0.3.8.md) for details.

## Migration Guide

### Migrating from 0.2.x to 0.3.0+

#### Authentication

```typescript
// Before
import { SignInComponent } from '@sinequa/atomic-angular';
// After
import { SignInFormComponent } from '@sinequa/atomic-angular';
```

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Requirements

- Angular 20+
- TypeScript 5.7+
- Node.js 18+

## 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)

**Built by the Sinequa Team**