npm package: @ghp-libraries/breadcrumb
Description: <p align="center">   <img src="https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white" alt="Angular" />   <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" a
Latest version: 0.1.1

# 🧭 Angular Breadcrumb Library

<p align="center">
  <img src="https://img.shields.io/badge/Angular-DD0031?style=for-the-badge&logo=angular&logoColor=white" alt="Angular" />
  <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
  <!-- <img src="https://img.shields.io/npm/v/@ghp-libraries/breadcrumb?style=for-the-badge" alt="npm version" />
  <img src="https://img.shields.io/npm/l/@ghp-libraries/breadcrumb?style=for-the-badge" alt="license" /> -->
</p>

A lightweight, animated breadcrumb navigation for Angular applications. Built with standalone components and designed for smooth integration with Angular Router.

## 📚 Table of Contents

- [Features](#-features)
- [For Developers & Contributors](#-for-developers--contributors)
- [Installation](#-installation)
- [Usage](#-usage)
- [Customization](#-customization)
- [Icons & Interactive Features](#-icons--interactive-features)
- [Event Handling](#-event-handling)
- [SEO Benefits](#-seo-benefits)
- [API Reference](#-api-reference)

## ✨ Features

- 🚀 **Modern Architecture** - Built with Angular standalone components
- 🔄 **Reactive Design** - Automatically updates when routes change
- 🎨 **Minimalist Look** - Clean design with subtle animations
- 🔧 **Customizable** - Easily modify separators, icons, and styling
- 📱 **Responsive** - Adapts to different screen sizes
- 🎭 **Framework Agnostic Styling** - No external CSS dependencies
- 🔍 **SEO Friendly** - Built-in Schema.org markup for better search visibility
- ♿ **Accessible** - Follows ARIA best practices for navigation
- 🔄 **Broad Compatibility** - Works with Angular 14 through 19
- 🖼️ **Icon Support** - Display custom icons with your breadcrumbs
- 🖱️ **Interactive** - Custom click handling and event emission

## 🛠 For Developers & Contributors

### Architecture

The breadcrumb library consists of two main parts:

1. **BreadcrumbService** - A singleton service that:
   - Listens to router navigation events
   - Extracts breadcrumb data from route configurations
   - Provides an observable stream of breadcrumb items

2. **BreadcrumbComponent** - A standalone component that:
   - Consumes the breadcrumb service
   - Renders the breadcrumb trail with proper accessibility attributes
   - Provides smooth animations and hover effects
   - Includes Schema.org structured data for SEO

### Project Structure

## Installation

To install the library, run the following command in your Angular project:

```bash
npm install @ghp-library/breadcumb
```

## Usage

### Importing the Library

The breadcrumb library can be imported in different ways depending on your application setup:

#### For Standalone Components (Recommended)

```typescript
import { BreadcrumbComponent } from '@ghp-library/breadcumb';

@Component({
  // ...
  imports: [BreadcrumbComponent]
})
export class YourComponent {}
```

#### For Module-based Applications

```typescript
import { BreadcrumbModule } from '@ghp-library/breadcumb';

@NgModule({
  // other imports ...
  imports: [BreadcrumbModule],
  // ...
})
export class YourModule {}
```

### Using the Breadcrumb Service

Inject `BreadcrumbService` into your components to use its functionalities:

```typescript
import { Component, OnInit } from "@angular/core";
import { BreadcrumbService } from "@ghp-library/breadcumb";

@Component({
  selector: "app-example",
  templateUrl: "./example.component.html",
})
export class ExampleComponent implements OnInit {
  constructor(private breadcrumbService: BreadcrumbService) {}

  ngOnInit() {
    // Use breadcrumb service methods here
  }
}
```

### Displaying Breadcrumbs

You can display breadcrumbs in your template using one of these approaches:

#### Using the Pre-styled Component

```html
<lib-breadcrumb />
```

This approach uses the library's default styling and animations.

#### Custom Implementation

For complete control over the design, you can use the breadcrumb service directly:

```html
<nav aria-label="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList">
  <ol class="breadcrumb">
    <li *ngFor="let breadcrumb of breadcrumbService.breadcrumbs$ | async" 
        class="breadcrumb-item"
        [class.active]="breadcrumb.active"
        itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
      <a [routerLink]="breadcrumb.url" itemprop="item">
        <span itemprop="name">{{ breadcrumb.label }}</span>
      </a>
      <meta itemprop="position" content="{{ breadcrumb.position }}" />
    </li>
  </ol>
</nav>
```

This approach allows you to:

- Customize the HTML structure
- Apply your own CSS styles
- Add custom logic and behaviors

## 🔍 SEO Benefits

### Key Schema.org Properties Used

1. **itemscope**: Indicates that the element contains structured data
2. **itemtype**: Specifies the type of structured data (BreadcrumbList and ListItem)
3. **itemprop="itemListElement"**: Marks each breadcrumb as an item in the list
4. **itemprop="position"**: The position of the breadcrumb in the sequence
5. **itemprop="name"**: The text label of the breadcrumb
6. **itemprop="item"**: The URL of the page the breadcrumb points to

### Benefits for Your Library Users

1. **Better SEO**: Users of your breadcrumb component automatically get SEO benefits
2. **Zero configuration**: The schema.org markup is automatically applied
3. **Best practices**: Follows Google's recommendations for breadcrumb structured data

## 🎨 Customization

### Basic Options

```html
<!-- Basic usage with default separator (/) -->
<ghp-breadcrumb></ghp-breadcrumb>

<!-- With custom separator -->
<ghp-breadcrumb separator="›"></ghp-breadcrumb>

<!-- With base URL for SEO -->
<ghp-breadcrumb baseUrl="https://example.com"></ghp-breadcrumb>

<!-- Limit number of visible items -->
<ghp-breadcrumb [maxItems]="4" ellipsisLabel="..."></ghp-breadcrumb>

<!-- Highlight the last item -->
<ghp-breadcrumb lastItem="ItemName"></ghp-breadcrumb>

<!-- Apply custom color class -->
<ghp-breadcrumb colorClass="custom-color-class"></ghp-breadcrumb>
```

## 🖼️ Icons & Interactive Features

### Using Icons in Breadcrumbs

You can add icons to your breadcrumbs by including the icon information in your route data:

```typescript
const routes: Routes = [
  {
    path: 'dashboard',
    component: DashboardComponent,
    data: { 
      breadcrumb: {
        label: 'Dashboard',
        icon: 'fa fa-dashboard' // Using Font Awesome as an example
      }
    }
  }
];
```

To control icon display:

```html
<!-- Enable or disable icon display -->
<ghp-breadcrumb [showIcons]="true"></ghp-breadcrumb>
```

### Customizing Navigation

You can also disable the default Router navigation and implement custom behavior:

```html
<!-- Disable Router navigation and handle clicks manually -->
<ghp-breadcrumb 
  [disableRouterNavigation]="true"
  (breadcrumbClick)="handleBreadcrumbClick($event)">
</ghp-breadcrumb>
```

## 🎮 Event Handling

The breadcrumb component emits events that you can listen to for custom behavior:

### Breadcrumb Click Events

```html
<ghp-breadcrumb (breadcrumbClick)="onBreadcrumbClicked($event)"></ghp-breadcrumb>
```

```typescript
onBreadcrumbClicked(breadcrumb: Breadcrumb) {
  console.log('Breadcrumb clicked:', breadcrumb);
  // Custom navigation or other logic
}
```

### Breadcrumbs Change Events

```html
<ghp-breadcrumb (breadcrumbsChanged)="onBreadcrumbsChanged($event)"></ghp-breadcrumb>
```

```typescript
onBreadcrumbsChanged(breadcrumbs: Breadcrumb[]) {
  console.log('Breadcrumb trail updated:', breadcrumbs);
  // Update UI or analytics based on new breadcrumb path
}
```

## 🛠 Advanced Configuration

The breadcrumb component offers extensive configuration options for enhanced functionality and customization.

### 📊 Component API Reference

#### BreadcrumbComponent Inputs

| Input | Type | Default | Description |
|-------|------|---------|-------------|
| `separator` | `string` | `/` | Separator between breadcrumb items |
| `baseUrl` | `string` | `''` | Base URL for schema.org absolute URLs |
| `maxItems` | `number \| null` | `null` | Maximum visible breadcrumbs (null = unlimited) |
| `ellipsisLabel` | `string` | `...` | Label for collapsed breadcrumbs |
| `lastItem` | `string` | `''` | Custom label for the last breadcrumb item |
| `colorClass` | `string` | `'text-primary'` | Custom CSS class for breadcrumb items |
| `showIcons` | `boolean` | `true` | Whether to display icons in breadcrumb items |
| `disableRouterNavigation` | `boolean` | `false` | When true, prevents default router navigation |

#### BreadcrumbComponent Outputs

| Output | Type | Description |
|--------|------|-------------|
| `breadcrumbClick` | `EventEmitter<Breadcrumb>` | Emits when a breadcrumb item is clicked |
| `breadcrumbsChanged` | `EventEmitter<Breadcrumb[]>` | Emits when the breadcrumb trail changes |

#### BreadcrumbService

| Property | Type | Description |
|----------|------|-------------|
| `breadcrumbs$` | `Observable<Breadcrumb[]>` | Current breadcrumb trail stream |

#### Breadcrumb Interface

```typescript
interface Breadcrumb {
  label: string;       // The display text
  url: string;         // The navigation URL
  icon?: string;       // Optional CSS class for icon display
}
```

#### BreadcrumbConfig Interface

```typescript
interface BreadcrumbConfig {
  label: string | ((data: Data) => string);  // Static text or function returning text
  hidden?: boolean;                          // Whether to hide this breadcrumb
  icon?: string;                             // CSS class for icon (e.g., 'fa fa-home')
}
```

### Route Configuration Examples

```typescript
const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    data: { breadcrumb: { label: 'Home', icon: 'fa fa-home' } }
  },
  {
    path: 'products',
    component: ProductListComponent,
    data: { breadcrumb: 'Products' },
    children: [
      {
        path: ':id',
        component: ProductDetailComponent,
        // Dynamic label based on route data
        data: { 
          breadcrumb: (data: Data) => `Product ${data['product']?.name || 'Detail'}`,
          // You can include other data needed for the label function
          someKey: 'someValue'
        }
      },
      {
        path: ':id/edit',
        component: ProductEditComponent,
        // Hide this segment from breadcrumbs
        data: { breadcrumb: { label: 'Edit', hidden: true } }
      }
    ]
  }
];
```