ng-hub-ui-breadcrumbs 1.0.0 → 1.0.2

package/README.md

@@ -1,24 +1,589 @@
-# NgHubUiBreadcrumb
+# Hub UI Breadcrumb
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.3.0.
+A flexible and reusable breadcrumb component for Angular applications that automatically generates breadcrumbs based on your routing configuration.
 
-## Code scaffolding
+## Installation
 
-Run `ng generate component component-name --project breadcrumbs` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project breadcrumbs`.
-> Note: Don't forget to add `--project breadcrumbs` or else it will be added to the default project in your `angular.json` file. 
+```bash
+npm install ng-hub-ui-breadcrumbs
+```
 
-## Build
+## Features
 
-Run `ng build breadcrumbs` to build the project. The build artifacts will be stored in the `dist/` directory.
+- Automatic breadcrumb generation from route configuration
+- Customizable through CSS variables
+- RTL support
+- Templating support for custom breadcrumb items
+- Bootstrap-compatible styling
 
-## Publishing
+## Usage
 
-After building your library with `ng build breadcrumbs`, go to the dist folder `cd dist/breadcrumbs` and run `npm publish`.
+## Basic Setup
 
-## Running unit tests
+You can use this component in two ways:
 
-Run `ng test breadcrumbs` to execute the unit tests via [Karma](https://karma-runner.github.io).
+### 1. Standalone Components
 
-## Further help
+Import the required artifacts in your component:
+
+```typescript
+import { HubBreadcrumbComponent } from '@hub/breadcrumb';
+import { HubBreadcrumbItemDirective } from '@hub/breadcrumb';
+
+@Component({
+  // ...
+  imports: [HubBreadcrumbComponent, HubBreadcrumbItemDirective]
+})
+```
+
+### 2. Module Import
+
+If you prefer using NgModules, import the HubBreadcrumbModule:
+
+```typescript
+import { HubBreadcrumbModule } from '@hub/breadcrumb';
+
+@NgModule({
+  imports: [HubBreadcrumbModule]
+})
+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
+		}
+	  }
+	]
+  }
+];
+```
+
+### Add to Template
+
+Add the component to your template:
+
+```html
+<hub-breadcrumbs></hub-breadcrumbs>
+```
+
+<!-- ### Dynamic Labels
+
+You can use resolved data in your breadcrumb labels:
+
+```typescript
+const routes: Routes = [
+  {
+	path: 'product/:id',
+	resolve: {
+	  resolvedData: ProductResolver
+	},
+	data: { 
+	  breadcrumb: '{name}' // Will be replaced with resolvedData.name
+	}
+  }
+];
+``` -->
+
+### 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
+
+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)
+  }
+];
+
+// admin-routing.module.ts
+const adminRoutes: Routes = [
+  {
+	path: 'users',
+	data: { breadcrumb: 'Users' }
+  }
+];
+```
+
+This will generate breadcrumbs like: Home > Administration > Users
+
+## Custom Template
+
+You can customize how each breadcrumb item is rendered using a template.
+
+### Basic Template
+
+```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>
+	}
+  </ng-template>
+</hub-breadcrumbs>
+```
+
+### Template Context
+
+The template context provides these properties:
+
+```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
+}
+```
+
+### Examples
+
+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>
+```
+
+Route configuration for icons:
+```typescript
+const routes: Routes = [
+  {
+	path: 'products',
+	data: {
+	  breadcrumb: 'Products',
+	  icon: 'fa fa-box'  // Will be available in template
+	}
+  }
+];
+```
+
+With custom separators:
+```html
+<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>
+</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:
+
+```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;
+}
+```
+
+### 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('<');
+```
+
+### Class Structure
+
+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)
+
+### Integration with Bootstrap
+
+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.
+
+### Inline Style Customization
+
+You can customize the breadcrumb directly in your template using inline styles:
+
+```html
+<hub-breadcrumbs style="
+  --hub-breadcrumb-divider: '🐸';
+  --hub-breadcrumb-bg: #e9ecef;
+  --hub-breadcrumb-item-active-color: #0d6efd;
+"></hub-breadcrumbs>
+```
+
+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>
+```
+
+2. Custom colors:
+```html
+<hub-breadcrumbs style="
+  --hub-breadcrumb-bg: transparent;
+  --hub-breadcrumb-divider-color: #6c757d;
+  --hub-breadcrumb-item-active-color: #0d6efd;
+"></hub-breadcrumbs>
+```
+
+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>
+```
+
+Note: When using emojis or special characters as dividers, make sure to wrap them in quotes.
+
+## API
+
+### Components
+
+#### HubBreadcrumbComponent
+```typescript
+@Component({
+  selector: 'hub-breadcrumb',
+  standalone: true
+})
+```
+
+A standalone component that automatically generates breadcrumbs from route configuration.
+
+### Directives
+
+#### HubBreadcrumbItemDirective
+```typescript
+@Directive({
+  selector: '[hubBreadcrumbItem]',
+  standalone: true
+})
+```
+
+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
+}
+```
+
+#### BreadcrumbTemplateContext
+```typescript
+interface BreadcrumbTemplateContext {
+  $implicit: BreadcrumbItem;  // Current breadcrumb item
+  isLast: boolean;            // Whether this is the last item
+}
+```
+
+### Route Configuration
+
+The component reads breadcrumb configuration from route data:
+
+```typescript
+interface BreadcrumbRouteData {
+  breadcrumb: string | ((data: any) => string);  // Static text or function
+  icon?: string;                                 // Optional icon class
+  [key: string]: any;                           // Additional custom data
+}
+```
+
+### 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
+```
+
+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
+
+# E2E tests
+npm run e2e
+
+# Test coverage
+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/):
+
+- `feat:` New features
+- `fix:` Bug fixes
+- `docs:` Documentation changes
+- `style:` Code style changes (formatting, etc)
+- `refactor:` Code refactors
+- `test:` Adding or updating tests
+- `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
+```
+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
+
+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)
+
+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]
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-hub-ui-breadcrumbs",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "A flexible and reusable breadcrumb component for Angular applications that automatically generates breadcrumbs based on routing configuration",
   "keywords": [
     "angular",