ng-hub-ui-breadcrumbs 1.0.2 → 21.0.0

package/README.md

@@ -1,489 +1,298 @@
-# Hub UI Breadcrumb
+# ng-hub-ui-breadcrumbs
 
-A flexible and reusable breadcrumb component for Angular applications that automatically generates breadcrumbs based on your routing configuration.
+![NPM Version](https://img.shields.io/npm/v/ng-hub-ui-breadcrumbs)
+![License](https://img.shields.io/npm/l/ng-hub-ui-breadcrumbs)
 
-## Installation
+A flexible and reusable breadcrumb component for Angular applications that automatically generates breadcrumbs entirely based on your routing configuration.
 
-```bash
-npm install ng-hub-ui-breadcrumbs
-```
+## 🧩 Library Family `ng-hub-ui`
 
-## Features
+This library is part of the **ng-hub-ui** ecosystem:
 
-- Automatic breadcrumb generation from route configuration
-- Customizable through CSS variables
-- RTL support
-- Templating support for custom breadcrumb items
-- Bootstrap-compatible styling
+- [**ng-hub-ui-accordion**](https://www.npmjs.com/package/ng-hub-ui-accordion)
+- [**ng-hub-ui-avatar**](https://www.npmjs.com/package/ng-hub-ui-avatar)
+- [**ng-hub-ui-board**](https://www.npmjs.com/package/ng-hub-ui-board)
+- [**ng-hub-ui-breadcrumbs**](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
+- [**ng-hub-ui-calendar**](https://www.npmjs.com/package/ng-hub-ui-calendar)
+- [**ng-hub-ui-modal**](https://www.npmjs.com/package/ng-hub-ui-modal)
+- [**ng-hub-ui-paginable**](https://www.npmjs.com/package/ng-hub-ui-paginable)
+- [**ng-hub-ui-portal**](https://www.npmjs.com/package/ng-hub-ui-portal)
+- [**ng-hub-ui-stepper**](https://www.npmjs.com/package/ng-hub-ui-stepper)
+- [**ng-hub-ui-utils**](https://www.npmjs.com/package/ng-hub-ui-utils)
 
-## Usage
+## Table of Contents
 
-## Basic Setup
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+- [Styling](#styling)
+- [Support & License](#support--license)
 
-You can use this component in two ways:
-
-### 1. Standalone Components
+## Features
 
-Import the required artifacts in your component:
+- **Automatic Breadcrumb Generation**: Automatically builds breadcrumbs from your Angular `Routes` configuration.
+- **Dynamic Labels**: Supports dynamic labels via functions or string interpolation using resolved data.
+- **Custom Templates**: Full control over how each breadcrumb item is rendered using directives.
+- **RTL Support**: Built-in support for Right-to-Left languages.
+- **Lazy Loading Compatible**: Works seamlessly with lazy-loaded modules.
 
-```typescript
-import { HubBreadcrumbComponent } from '@hub/breadcrumb';
-import { HubBreadcrumbItemDirective } from '@hub/breadcrumb';
+## Installation
 
-@Component({
-  // ...
-  imports: [HubBreadcrumbComponent, HubBreadcrumbItemDirective]
-})
+```bash
+npm install ng-hub-ui-breadcrumbs
 ```
 
-### 2. Module Import
+## Usage
+
+### 1. Import the Component
 
-If you prefer using NgModules, import the HubBreadcrumbModule:
+You can import the `HubBreadcrumbsComponent` directly in your standalone component or module.
 
 ```typescript
-import { HubBreadcrumbModule } from '@hub/breadcrumb';
+import { HubBreadcrumbsComponent } from 'ng-hub-ui-breadcrumbs';
 
-@NgModule({
-  imports: [HubBreadcrumbModule]
+@Component({
+	// ...
+	imports: [HubBreadcrumbsComponent]
 })
-export class AppModule { }
-```
-
-### Route Configuration
-
-Configure your routes with breadcrumb data:
-
-```typescript
-// app-routing.module.ts
-const routes: Routes = [
-  {
-	path: '',
-	data: { breadcrumb: 'Home' }
-  },
-  {
-	path: 'products',
-	data: { breadcrumb: 'Products' },
-	children: [
-	  {
-		path: ':id',
-		resolve: {
-		  resolvedData: ProductResolver
-		},
-		data: { 
-		  breadcrumb: '{name}' // Will use the product name from resolver
-		}
-	  }
-	]
-  }
-];
+export class AppComponent {}
 ```
 
-### Add to Template
+### 2. Add to Template
 
-Add the component to your template:
+Place the component in your application's main layout or wherever you want breadcrumbs to appear.
 
 ```html
 <hub-breadcrumbs></hub-breadcrumbs>
 ```
 
-<!-- ### Dynamic Labels
+### 3. Configure Routes
 
-You can use resolved data in your breadcrumb labels:
+The most critical part is adding `data: { breadcrumb: '...' }` to your routes.
 
+````typescript
 ```typescript
 const routes: Routes = [
-  {
-	path: 'product/:id',
-	resolve: {
-	  resolvedData: ProductResolver
+	{
+		path: '',
+		data: { breadcrumb: 'Home' } // Standard static label
 	},
-	data: { 
-	  breadcrumb: '{name}' // Will be replaced with resolvedData.name
+	{
+		path: 'products',
+		data: { breadcrumb: 'Products' },
+		children: [
+			// ... child routes
+		]
 	}
-  }
 ];
-``` -->
+````
 
-### Function Labels
-
-You can also use functions to generate dynamic labels:
-
-```typescript
-const routes: Routes = [
-  {
-	path: 'products',
-	resolve: { info: infoResolver },
-	data: { breadcrumb: (data: any) => `${data.info.title}` },
-  }
-];
-```
-
-### Component Features
-
-The breadcrumb component automatically:
-- Listens to route changes
-- Extracts breadcrumb data from route configuration
-- Builds the breadcrumb path
-- Handles template customization
-- Supports RTL languages
-
-### Working with Lazy Loading
+### 4. Working with Lazy Loading
 
 For lazy-loaded modules, configure the parent route with breadcrumb data:
 
 ```typescript
 // app-routing.module.ts
 const routes: Routes = [
-  {
-	path: 'admin',
-	data: { breadcrumb: 'Administration' },
-	loadChildren: () => import('./admin/admin.module').then(m => m.AdminModule)
-  }
+	{
+		path: 'admin',
+		data: { breadcrumb: 'Administration' },
+		loadChildren: () => import('./admin/admin.module').then((m) => m.AdminModule)
+	}
 ];
 
 // admin-routing.module.ts
 const adminRoutes: Routes = [
-  {
-	path: 'users',
-	data: { breadcrumb: 'Users' }
-  }
+	{
+		path: 'users',
+		data: { breadcrumb: 'Users' }
+	}
 ];
 ```
 
 This will generate breadcrumbs like: Home > Administration > Users
 
-## Custom Template
+## Examples
 
-You can customize how each breadcrumb item is rendered using a template.
+### Dynamic Labels with Functions
 
-### Basic Template
+You can use a function to generate the breadcrumb label dynamically based on route data.
 
-```html
-<hub-breadcrumbs>
-  <ng-template hubBreadcrumbItem let-item let-isLast="isLast">
-	@if (!isLast) {
-	  <a [routerLink]="item.url" class="hub-breadcrumb__link">
-		{{ item.label }}
-	  </a>
-	} @else {
-	  <span class="hub-breadcrumb__text">{{ item.label }}</span>
+```typescript
+const routes: Routes = [
+	{
+		path: 'dashboard',
+		resolve: { userInfo: UserResolver },
+		data: {
+			breadcrumb: (data: any) => `User: ${data.userInfo.name}` // Function creates label from resolved data
+		}
 	}
-  </ng-template>
-</hub-breadcrumbs>
+];
 ```
 
-### Template Context
+### Dynamic Labels with Interpolation
 
-The template context provides these properties:
+Alternatively, you can use string interpolation `{key}` if your data is under a `resolvedData` property.
 
 ```typescript
-interface BreadcrumbTemplateContext {
-  $implicit: BreadcrumbItem;  // The current breadcrumb item
-  isLast: boolean;           // Whether this is the last item
-}
-
-interface BreadcrumbItem {
-  label: string;    // The text to display
-  url: string;      // The route URL
-  data: any;        // Additional data from route configuration
-}
+const routes: Routes = [
+	{
+		path: 'product/:id',
+		resolve: {
+			resolvedData: ProductResolver // Must be named 'resolvedData' for interpolation
+		},
+		data: {
+			breadcrumb: 'Product: {name}' // Replaces {name} with resolvedData.name
+		}
+	}
+];
 ```
 
-### Examples
+### Custom Icons
 
-With icons:
-```html
-<hub-breadcrumbs>
-  <ng-template hubBreadcrumbItem let-item let-isLast="isLast">
-	@if (!isLast) {
-	  <a [routerLink]="item.url" class="hub-breadcrumb__link">
-		<i [class]="item.data?.icon"></i>
-		{{ item.label }}
-	  </a>
-	} @else {
-	  <span class="hub-breadcrumb__text">
-		<i [class]="item.data?.icon"></i>
-		{{ item.label }}
-	  </span>
-	}
-  </ng-template>
-</hub-breadcrumbs>
-```
+You can attach arbitrary data (like icons) to your route config and use it in a custom template.
 
-Route configuration for icons:
 ```typescript
-const routes: Routes = [
-  {
-	path: 'products',
-	data: {
-	  breadcrumb: 'Products',
-	  icon: 'fa fa-box'  // Will be available in template
-	}
+// Route Configuration
+{
+  path: 'settings',
+  data: {
+    breadcrumb: 'Settings',
+    icon: 'fa fa-cog' // Custom data property
   }
-];
+}
 ```
 
-With custom separators:
 ```html
+<!-- Custom Template Implementation -->
 <hub-breadcrumbs>
-  <ng-template hubBreadcrumbItem let-item let-isLast="isLast">
-	@if (!isLast) {
-	  <a [routerLink]="item.url" class="hub-breadcrumb__link">
-		{{ item.label }}
-	  </a>
-	  <span class="hub-breadcrumb__separator">→</span>
-	} @else {
-	  <span class="hub-breadcrumb__text">{{ item.label }}</span>
-	}
-  </ng-template>
+	<ng-template hubBreadcrumbItem let-item let-isLast="isLast">
+		<!-- 'item.data' contains the entire route data object -->
+		@if (item.data.icon) {
+		<i [class]="item.data.icon"></i>
+		}
+		<a [routerLink]="item.url">{{ item.label }}</a>
+	</ng-template>
 </hub-breadcrumbs>
 ```
 
-Note: When using a custom template, you're responsible for:
-- Handling the navigation with `routerLink`
-- Managing active/inactive states
-- Applying appropriate styles
-- Handling RTL if needed
-
-## Styling
-
-The breadcrumb component uses CSS variables for styling, making it highly customizable. It's designed to work with or without Bootstrap.
-
-### Default SCSS Variables
-
-These SCSS variables set the default values:
-
-```scss
-$border-radius-pill: 50rem !default;
-$secondary-color: black !default;
-$breadcrumb-font-size: null !default;
-$breadcrumb-padding-y: 0.25rem !default;
-$breadcrumb-padding-x: 1rem !default;
-$breadcrumb-item-padding-x: 0.5rem !default;
-$breadcrumb-margin-bottom: 0 !default;
-$breadcrumb-bg: white !default;
-$breadcrumb-divider-color: $secondary-color !default;
-$breadcrumb-active-color: $secondary-color !default;
-$breadcrumb-divider: quote('>') !default;
-$breadcrumb-divider-flipped: $breadcrumb-divider !default;
-$breadcrumb-border-radius: $border-radius-pill !default;
-```
-
-### CSS Variables
-
-These variables are exposed for runtime customization:
+### Custom Template & Separators
 
-```css
-.hub-breadcrumb__list {
-  --hub-breadcrumb-padding-x: 1rem;
-  --hub-breadcrumb-padding-y: 0.25rem;
-  --hub-breadcrumb-margin-bottom: 0;
-  --hub-breadcrumb-bg: white;
-  --hub-breadcrumb-border-radius: 50rem;
-  --hub-breadcrumb-divider-color: black;
-  --hub-breadcrumb-item-padding-x: 0.5rem;
-  --hub-breadcrumb-item-active-color: black;
-}
-```
+Fully customize the structure, including separators/dividers.
 
-### Customizing Styles
-
-1. Override SCSS variables (compile-time):
-```scss
-// your-styles.scss
-$breadcrumb-bg: #f8f9fa;
-$breadcrumb-divider: quote('→');
-$breadcrumb-active-color: #6c757d;
-```
-
-2. Override CSS variables (runtime):
-```css
-.hub-breadcrumb__list {
-  --hub-breadcrumb-bg: #f8f9fa;
-  --hub-breadcrumb-divider-color: #6c757d;
-}
-```
-
-3. Override classes directly:
-```scss
-.hub-breadcrumb__item {
-  &--active {
-	font-weight: bold;
-  }
-}
-```
-
-### RTL Support
-
-The component automatically handles RTL languages by flipping the divider. You can customize the flipped divider using:
-
-```scss
-$breadcrumb-divider-flipped: quote('<');
+```html
+<hub-breadcrumbs>
+	<ng-template hubBreadcrumbItem let-item let-isLast="isLast">
+		<span class="my-breadcrumb-item">
+			<a [routerLink]="item.url">{{ item.label }}</a>
+		</span>
+		<!-- Custom Separator -->
+		@if (!isLast) {
+		<span class="separator"> / </span>
+		}
+	</ng-template>
+</hub-breadcrumbs>
 ```
 
-### Class Structure
+## API Reference
 
-The component uses BEM methodology:
-- `.hub-breadcrumb` - Block (host component)
-- `.hub-breadcrumb__list` - Element (container)
-- `.hub-breadcrumb__item` - Element (each breadcrumb)
-- `.hub-breadcrumb__item--active` - Modifier (active state)
+### HubBreadcrumbsComponent
 
-### Integration with Bootstrap
+The main container component. It doesn't have any inputs as it reads directly from the Router.
 
-While the component works independently, it's designed to be compatible with Bootstrap's breadcrumb styles. If you're using Bootstrap, the styles will automatically align with your Bootstrap theme.
+| Selector          | Exported As      |
+| ----------------- | ---------------- |
+| `hub-breadcrumbs` | `hubBreadcrumbs` |
 
-### Inline Style Customization
+### HubBreadcrumbItemDirective
 
-You can customize the breadcrumb directly in your template using inline styles:
+A structural directive used to define a custom template for breadcrumb items.
 
-```html
-<hub-breadcrumbs style="
-  --hub-breadcrumb-divider: '🐸';
-  --hub-breadcrumb-bg: #e9ecef;
-  --hub-breadcrumb-item-active-color: #0d6efd;
-"></hub-breadcrumbs>
-```
+| Selector              | Context Type                |
+| --------------------- | --------------------------- |
+| `[hubBreadcrumbItem]` | `BreadcrumbTemplateContext` |
 
-Common use cases:
-
-1. Custom divider:
-```html
-<hub-breadcrumbs style="--hub-breadcrumb-divider: '→'"></hub-breadcrumbs>
-<hub-breadcrumbs style="--hub-breadcrumb-divider: '>'"></hub-breadcrumbs>
-<hub-breadcrumbs style="--hub-breadcrumb-divider: '/'"></hub-breadcrumbs>
-<hub-breadcrumbs style="--hub-breadcrumb-divider: '🐸'"></hub-breadcrumbs>
-```
+### Interfaces
 
-2. Custom colors:
-```html
-<hub-breadcrumbs style="
-  --hub-breadcrumb-bg: transparent;
-  --hub-breadcrumb-divider-color: #6c757d;
-  --hub-breadcrumb-item-active-color: #0d6efd;
-"></hub-breadcrumbs>
-```
+#### BreadcrumbItem
 
-3. Custom spacing:
-```html
-<hub-breadcrumbs style="
-  --hub-breadcrumb-padding-x: 0;
-  --hub-breadcrumb-padding-y: 0;
-  --hub-breadcrumb-item-padding-x: 1rem;
-"></hub-breadcrumbs>
-```
+| Property | Type     | Description                                             |
+| -------- | -------- | ------------------------------------------------------- |
+| `label`  | `string` | The resolved text to display for the breadcrumb.        |
+| `url`    | `string` | The full URL path to navigate to.                       |
+| `data`   | `any`    | The original route data object (useful for icons, etc). |
 
-Note: When using emojis or special characters as dividers, make sure to wrap them in quotes.
+#### BreadcrumbTemplateContext
 
-## API
+| Property    | Type             | Description                                                   |
+| ----------- | ---------------- | ------------------------------------------------------------- |
+| `$implicit` | `BreadcrumbItem` | The current breadcrumb item object.                           |
+| `isLast`    | `boolean`        | True if this item is the last one in the list (current page). |
 
-### Components
+## Styling
 
-#### HubBreadcrumbComponent
-```typescript
-@Component({
-  selector: 'hub-breadcrumb',
-  standalone: true
-})
-```
+`ng-hub-ui-breadcrumbs` is fully style-configurable through CSS custom properties.
 
-A standalone component that automatically generates breadcrumbs from route configuration.
+For a complete and up-to-date token catalog, see [CSS Variables Reference](./docs/css-variables-reference.md).
 
-### Directives
+### Import styles
 
-#### HubBreadcrumbItemDirective
-```typescript
-@Directive({
-  selector: '[hubBreadcrumbItem]',
-  standalone: true
-})
+```scss
+@use 'ng-hub-ui-breadcrumbs/src/lib/styles/breadcrumbs.scss';
 ```
 
-Template directive for customizing breadcrumb item rendering.
-
-### Interfaces
-
-#### BreadcrumbItem
-```typescript
-interface BreadcrumbItem {
-  label: string;    // Display text
-  url: string;      // Navigation URL
-  data: any;        // Additional data from route configuration
-}
-```
+### Quick customization example (framework-agnostic)
 
-#### BreadcrumbTemplateContext
-```typescript
-interface BreadcrumbTemplateContext {
-  $implicit: BreadcrumbItem;  // Current breadcrumb item
-  isLast: boolean;            // Whether this is the last item
+```scss
+.hub-breadcrumbs__list {
+	--hub-breadcrumb-bg: #f8f9fa;
+	--hub-breadcrumb-divider: '→';
+	--hub-breadcrumb-link-color: #0d6efd;
+	--hub-breadcrumb-item-active-color: #6c757d;
 }
 ```
 
-### Route Configuration
-
-The component reads breadcrumb configuration from route data:
+### Bootstrap integration (optional)
 
-```typescript
-interface BreadcrumbRouteData {
-  breadcrumb: string | ((data: any) => string);  // Static text or function
-  icon?: string;                                 // Optional icon class
-  [key: string]: any;                           // Additional custom data
+```scss
+.hub-breadcrumbs__list {
+	--hub-breadcrumb-bg: var(--bs-light);
+	--hub-breadcrumb-link-color: var(--bs-primary);
+	--hub-breadcrumb-link-hover-color: var(--bs-primary-text-emphasis);
+	--hub-breadcrumb-item-active-color: var(--bs-secondary-color);
 }
 ```
 
-### CSS Custom Properties
-
-| Property | Description | Default |
-|----------|-------------|---------|
-| `--hub-breadcrumb-padding-x` | Horizontal padding | `1rem` |
-| `--hub-breadcrumb-padding-y` | Vertical padding | `0.25rem` |
-| `--hub-breadcrumb-margin-bottom` | Bottom margin | `0` |
-| `--hub-breadcrumb-bg` | Background color | `white` |
-| `--hub-breadcrumb-border-radius` | Border radius | `50rem` |
-| `--hub-breadcrumb-divider-color` | Divider color | `black` |
-| `--hub-breadcrumb-item-padding-x` | Item spacing | `0.5rem` |
-| `--hub-breadcrumb-item-active-color` | Active item color | `black` |
-
-### SCSS Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `$breadcrumb-padding-y` | Vertical padding | `0.25rem` |
-| `$breadcrumb-padding-x` | Horizontal padding | `1rem` |
-| `$breadcrumb-margin-bottom` | Bottom margin | `0` |
-| `$breadcrumb-bg` | Background color | `white` |
-| `$breadcrumb-divider` | Divider character | `'>'` |
-| `$breadcrumb-divider-flipped` | RTL divider character | Same as `$breadcrumb-divider` |
-| `$breadcrumb-border-radius` | Border radius | `50rem` |
-| `$breadcrumb-active-color` | Active item color | `black` |
-
-
 ## Contributing
 
 We appreciate your interest in contributing to Hub Breadcrumb! Here's how you can help:
 
 ### Development Setup
 
-1. Clone the repository
-```bash
-git clone https://github.com/carlos-morcillo/ng-hub-ui-breadcrumbs.git
-cd ng-hub-ui-breadcrumbs
-```
+1.  **Clone the repository**
 
-2. Install dependencies
-```bash
-npm install
-```
+    ```bash
+    git clone https://github.com/carlos-morcillo/ng-hub-ui-breadcrumbs.git
+    cd ng-hub-ui-breadcrumbs
+    ```
 
-3. Start the development server
-```bash
-npm start
-```
+2.  **Install dependencies**
+
+    ```bash
+    npm install
+    ```
+
+3.  **Start the development server**
+    ```bash
+    npm start
+    ```
 
 ### Testing
 
 Run the test suite:
+
 ```bash
 # Unit tests
 npm run test
@@ -495,27 +304,6 @@ npm run e2e
 npm run test:coverage
 ```
 
-### Project Structure
-
-```
-ng-hub-ui-breadcrumbs/
-├── src/
-│   ├── lib/
-│   │   ├── components/
-│   │   │   ├── hub-breadcrumb.component.ts
-│   │   │   ├── hub-breadcrumb.component.spec.ts
-│   │   │   └── hub-breadcrumb.component.scss
-│   │   ├── directives/
-│   │   │   └── hub-breadcrumb-item.directive.ts
-│   │   ├── services/
-│   │   │   └── hub-breadcrumb.service.ts
-│   │   └── interfaces/
-│   │       └── breadcrumb-item.ts
-│   └── public-api.ts
-├── README.md
-└── package.json
-```
-
 ### Commit Guidelines
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/):
@@ -529,61 +317,21 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/):
 - `chore:` Maintenance tasks
 
 Example:
-```bash
-git commit -m "feat: add custom divider support"
-```
 
-### Pull Request Process
-
-1. Fork the repository
-2. Create a new branch:
 ```bash
-git checkout -b feat/my-new-feature
+git commit -m "feat: add custom divider support"
 ```
-3. Make your changes
-4. Add tests for any new functionality
-5. Update documentation if needed
-6. Submit a Pull Request
 
-### Development Guidelines
-
-- Write unit tests for new features
-- Follow Angular style guide
-- Update documentation for API changes
-- Maintain backward compatibility
-- Add comments for complex logic
-
-### Issues
-
-Before creating an issue, please:
-
-- Check existing issues
-- Use the issue template
-- Include reproduction steps
-- Specify your environment
-
-### Code Style
-
-We follow the [Angular Style Guide](https://angular.io/guide/styleguide):
-
-- Use TypeScript
-- Follow BEM for CSS
-- Maintain consistent naming
-- Add JSDoc comments
-
-## Support the Project
+## Support & License
 
 If you find this project helpful and would like to support its development, you can buy me a coffee:
 
-[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/carlosmorcillo)
+[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/carlosmorcillo)
 
 Your support is greatly appreciated and helps maintain and improve this project!
 
-## License
-
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ---
 
 Made with ❤️ by [Carlos Morcillo Fernández]
-