ngx-opalbytes-components 1.28.0 → 1.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-opalbytes-components",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",

package/src/lib/shared/components/avatar/avatar.constants.ts

@@ -0,0 +1,17 @@
+const DEFAULT_AVATAR_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">' +
+  '<rect width="64" height="64" fill="#e5e7eb"/>' +
+  '<circle cx="32" cy="25" r="11" fill="#9ca3af"/>' +
+  '<path d="M10 64c0-13 10-22 22-22s22 9 22 22z" fill="#9ca3af"/>' +
+  '</svg>';
+
+/** Imagem padrão (silhueta) usada quando nenhuma fonte é informada ou a imagem falha ao carregar. */
+export const CAO_AVATAR_DEFAULT_SRC = `data:image/svg+xml;utf8,${encodeURIComponent(DEFAULT_AVATAR_SVG)}`;
+
+/** Tamanhos predefinidos, em px. */
+export const CAO_AVATAR_SIZES = {
+  small: 24,
+  normal: 32,
+  large: 48,
+  xlarge: 64,
+} as const;

package/src/lib/shared/components/avatar/avatar.css

@@ -0,0 +1,44 @@
+:host {
+  display: inline-block;
+  line-height: 0;
+}
+
+.cao-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  overflow: hidden;
+  background-color: var(--cao-avatar-bg, #e5e7eb);
+  color: var(--cao-avatar-text, #374151);
+  font-weight: 600;
+  line-height: 1;
+  user-select: none;
+}
+
+.cao-avatar--circle {
+  border-radius: 50%;
+}
+
+.cao-avatar--rounded {
+  border-radius: var(--cao-avatar-radius, 25%);
+}
+
+.cao-avatar--square {
+  border-radius: 0;
+}
+
+.cao-avatar__image {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.cao-avatar__label {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: clip;
+  white-space: nowrap;
+}

package/src/lib/shared/components/avatar/avatar.html

@@ -0,0 +1,27 @@
+<div
+  class="cao-avatar"
+  role="img"
+  [class.cao-avatar--circle]="shape() === 'circle'"
+  [class.cao-avatar--rounded]="shape() === 'rounded'"
+  [class.cao-avatar--square]="shape() === 'square'"
+  [attr.aria-label]="accessibleName()"
+  [attr.data-cy]="dataCy() || null"
+  [style.width.px]="sizePx()"
+  [style.height.px]="sizePx()"
+  [style.border-width]="strokeWidthCss()"
+  [style.border-style]="strokeStyle()"
+  [style.border-color]="strokeColor()"
+  [style.background-color]="bgColor() || null"
+  [style.color]="textColor() || null">
+  @switch (mode()) {
+    @case ('image') {
+      <img class="cao-avatar__image" alt="" aria-hidden="true" [src]="src()" (error)="onImageError()" />
+    }
+    @case ('label') {
+      <span class="cao-avatar__label" [style.font-size.px]="fontSizePx()">{{ label() }}</span>
+    }
+    @default {
+      <img class="cao-avatar__image" alt="" aria-hidden="true" [src]="defaultImage()" />
+    }
+  }
+</div>

package/src/lib/shared/components/avatar/avatar.model.ts

@@ -0,0 +1,3 @@
+export type CaoAvatarShape = 'circle' | 'rounded' | 'square';
+export type CaoAvatarPresetSize = 'small' | 'normal' | 'large' | 'xlarge';
+export type CaoAvatarStrokeStyle = 'solid' | 'dashed' | 'dotted' | 'double';

package/src/lib/shared/components/avatar/avatar.spec.ts

@@ -0,0 +1,88 @@
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { CaoAvatarComponent } from './avatar';
+
+describe('CaoAvatarComponent', () => {
+  let fixture: ComponentFixture<CaoAvatarComponent>;
+  let el: HTMLElement;
+
+  const avatar = () => el.querySelector<HTMLElement>('.cao-avatar') as HTMLElement;
+  const image = () => el.querySelector<HTMLImageElement>('img');
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({ imports: [CaoAvatarComponent] }).compileComponents();
+    fixture = TestBed.createComponent(CaoAvatarComponent);
+    el = fixture.nativeElement;
+    fixture.detectChanges();
+  });
+
+  it('exibe a imagem padrão quando nada é informado', () => {
+    expect(image()).not.toBeNull();
+    expect(image()?.getAttribute('src')).toContain('data:image/svg+xml');
+  });
+
+  it('exibe a imagem informada em src', () => {
+    fixture.componentRef.setInput('src', 'https://example.com/a.png');
+    fixture.detectChanges();
+    expect(image()?.getAttribute('src')).toBe('https://example.com/a.png');
+  });
+
+  it('exibe o label quando não há imagem', () => {
+    fixture.componentRef.setInput('label', 'MB');
+    fixture.detectChanges();
+    expect(el.querySelector('.cao-avatar__label')?.textContent?.trim()).toBe('MB');
+    expect(image()).toBeNull();
+  });
+
+  it('volta para a imagem padrão quando src falha e não há label/ícone', () => {
+    fixture.componentRef.setInput('src', 'https://example.com/quebrada.png');
+    fixture.detectChanges();
+    image()?.dispatchEvent(new Event('error'));
+    fixture.detectChanges();
+    expect(image()?.getAttribute('src')).toContain('data:image/svg+xml');
+  });
+
+  it('volta para o label quando src falha', () => {
+    fixture.componentRef.setInput('src', 'https://example.com/quebrada.png');
+    fixture.componentRef.setInput('label', 'AB');
+    fixture.detectChanges();
+    image()?.dispatchEvent(new Event('error'));
+    fixture.detectChanges();
+    expect(el.querySelector('.cao-avatar__label')?.textContent?.trim()).toBe('AB');
+  });
+
+  it('usa defaultSrc customizado', () => {
+    fixture.componentRef.setInput('defaultSrc', 'https://example.com/padrao.png');
+    fixture.detectChanges();
+    expect(image()?.getAttribute('src')).toBe('https://example.com/padrao.png');
+  });
+
+  it('aplica tamanhos predefinidos, numéricos e em rem', () => {
+    fixture.componentRef.setInput('size', 'xlarge');
+    fixture.detectChanges();
+    expect(avatar().style.width).toBe('64px');
+
+    fixture.componentRef.setInput('size', 100);
+    fixture.detectChanges();
+    expect(avatar().style.width).toBe('100px');
+
+    fixture.componentRef.setInput('size', '3rem');
+    fixture.detectChanges();
+    expect(avatar().style.width).toBe('48px');
+  });
+
+  it('aplica o formato', () => {
+    expect(avatar().classList).toContain('cao-avatar--circle');
+    fixture.componentRef.setInput('shape', 'square');
+    fixture.detectChanges();
+    expect(avatar().classList).toContain('cao-avatar--square');
+  });
+
+  it('aplica o stroke', () => {
+    fixture.componentRef.setInput('strokeWidth', 3);
+    fixture.componentRef.setInput('strokeColor', '#4f46e5');
+    fixture.detectChanges();
+    expect(avatar().style.borderWidth).toBe('3px');
+    expect(avatar().style.borderStyle).toBe('solid');
+  });
+});

package/src/lib/shared/components/avatar/avatar.stories.ts

@@ -0,0 +1,85 @@
+import { LucideUser, provideLucideIcons } from '@lucide/angular';
+import { applicationConfig, argsToTemplate, Meta, StoryObj } from '@storybook/angular-vite';
+
+import { CaoAvatarComponent } from './avatar';
+
+/* eslint-disable @typescript-eslint/naming-convention */
+const STORY_ICONS = { LucideUser };
+/* eslint-enable @typescript-eslint/naming-convention */
+
+const PHOTO = 'https://i.pravatar.cc/200?img=12';
+const ROW = 'display:flex;gap:16px;align-items:center;flex-wrap:wrap';
+
+const meta: Meta<CaoAvatarComponent> = {
+    title: 'Componentes/Avatar',
+    component: CaoAvatarComponent,
+    tags: ['autodocs'],
+    decorators: [applicationConfig({ providers: [provideLucideIcons(STORY_ICONS as never)] })],
+    render: (args) => ({ props: args, template: `<cao-avatar ${argsToTemplate(args)} />` }),
+    argTypes: {
+        src: { control: 'text', description: 'URL da imagem. Vazia → ícone, label ou imagem padrão.' },
+        defaultSrc: { control: 'text', description: 'Imagem padrão customizada.' },
+        label: { control: 'text' },
+        isLucideIcon: { control: 'boolean' },
+        iconColor: { control: 'color' },
+        size: { control: 'text', description: "'small' | 'normal' | 'large' | 'xlarge' | número (px) | '4rem'" },
+        shape: { control: 'inline-radio', options: ['circle', 'rounded', 'square'] },
+        strokeWidth: { control: 'text' },
+        strokeColor: { control: 'color' },
+        strokeStyle: { control: 'inline-radio', options: ['solid', 'dashed', 'dotted', 'double'] },
+        bgColor: { control: 'color' },
+        textColor: { control: 'color' },
+    },
+    args: { size: 'large', shape: 'circle', strokeWidth: 0, strokeColor: '#ffffff', strokeStyle: 'solid' },
+};
+export default meta;
+
+type Story = StoryObj<CaoAvatarComponent>;
+
+export const DefaultImage: Story = {};
+
+export const WithImage: Story = { args: { src: PHOTO, alt: 'Foto de perfil' } };
+
+export const WithLabel: Story = { args: { label: 'MB', bgColor: '#eef2ff', textColor: '#4338ca' } };
+
+export const WithIcon: Story = { args: { icon: 'user', bgColor: '#dcfce7', iconColor: '#166534' } };
+
+export const BrokenImageFallsBack: Story = { args: { src: 'https://invalid.example/nao-existe.png' } };
+
+export const CustomDefaultImage: Story = { args: { defaultSrc: 'https://i.pravatar.cc/200?img=47' } };
+
+export const Sizes: Story = {
+    render: () => ({
+        template: `
+      <div style="${ROW}">
+        <cao-avatar [src]="'${PHOTO}'" size="small" />
+        <cao-avatar [src]="'${PHOTO}'" size="normal" />
+        <cao-avatar [src]="'${PHOTO}'" size="large" />
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" />
+        <cao-avatar [src]="'${PHOTO}'" [size]="96" />
+        <cao-avatar [src]="'${PHOTO}'" size="7rem" />
+      </div>`,
+    }),
+};
+
+export const Shapes: Story = {
+    render: () => ({
+        template: `
+      <div style="${ROW}">
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" shape="circle" />
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" shape="rounded" />
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" shape="square" />
+      </div>`,
+    }),
+};
+
+export const Stroke: Story = {
+    render: () => ({
+        template: `
+      <div style="${ROW}">
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" [strokeWidth]="2" strokeColor="#4f46e5" />
+        <cao-avatar [src]="'${PHOTO}'" size="xlarge" [strokeWidth]="4" strokeColor="#16a34a" strokeStyle="dashed" />
+        <cao-avatar label="AB" size="xlarge" shape="rounded" [strokeWidth]="3" strokeColor="#f59e0b" strokeStyle="double" />
+      </div>`,
+    }),
+};

package/src/lib/shared/components/avatar/avatar.ts

@@ -0,0 +1,83 @@
+import { ChangeDetectionStrategy, Component, computed, inject, input, signal } from '@angular/core';
+import { DomSanitizer, SafeUrl } from '@angular/platform-browser';
+
+import { CAO_AVATAR_DEFAULT_SRC, CAO_AVATAR_SIZES } from './avatar.constants';
+import { CaoAvatarPresetSize, CaoAvatarShape, CaoAvatarStrokeStyle } from './avatar.model';
+
+type CaoAvatarMode = 'image'  | 'label' | 'default';
+
+@Component({
+  selector: 'cao-avatar',
+  imports: [],
+  templateUrl: './avatar.html',
+  styleUrl: './avatar.css',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class CaoAvatarComponent {
+  private readonly sanitizer = inject(DomSanitizer);
+  private readonly defaultUrl: SafeUrl = this.sanitizer.bypassSecurityTrustUrl(CAO_AVATAR_DEFAULT_SRC);
+  private readonly failedSrc = signal<string | null>(null);
+
+  /** URL da imagem. Se vazia ou inválida, usa ícone, label ou a imagem padrão (nessa ordem). */
+  readonly src = input<string | null | undefined>('');
+  /** Imagem padrão customizada, usada quando nada é informado ou `src` falha ao carregar. */
+  readonly defaultSrc = input<string>('');
+  /** Texto exibido (ex.: iniciais) quando não há imagem nem ícone. */
+  readonly label = input<string>('');
+  /** Nome do ícone Lucide ou imagem usada como ícone. */
+  readonly icon = input<string>('');
+  readonly isLucideIcon = input<boolean>(true);
+  readonly iconColor = input<string>('');
+
+  /** Tamanho: `'small' | 'normal' | 'large' | 'xlarge'`, número em px ou string (`'72px'`, `'4.5rem'`). */
+  readonly size = input<CaoAvatarPresetSize | number | string>('normal');
+  /** Formato do avatar. */
+  readonly shape = input<CaoAvatarShape>('circle');
+
+  /** Espessura do contorno (stroke). Número = px. `0` remove o contorno. */
+  readonly strokeWidth = input<number | string>(0);
+  readonly strokeColor = input<string>('#ffffff');
+  readonly strokeStyle = input<CaoAvatarStrokeStyle>('solid');
+
+  readonly bgColor = input<string>('');
+  readonly textColor = input<string>('');
+
+  readonly alt = input<string>('');
+  readonly ariaLabel = input<string>('');
+  readonly dataCy = input<string>('');
+
+  protected readonly sizePx = computed<number>(() => this.resolveSize(this.size()));
+  protected readonly fontSizePx = computed<number>(() => Math.round(this.sizePx() * 0.4));
+  protected readonly iconSizePx = computed<number>(() => Math.round(this.sizePx() * 0.55));
+
+  protected readonly strokeWidthCss = computed<string>(() => {
+    const width = this.strokeWidth();
+    return typeof width === 'number' ? `${width}px` : width;
+  });
+
+  protected readonly mode = computed<CaoAvatarMode>(() => {
+    const src = this.src();
+    if (src && this.failedSrc() !== src) {return 'image';}
+    if (this.label()) {return 'label';}
+    return 'default';
+  });
+
+  protected readonly defaultImage = computed<string | SafeUrl>(() => this.defaultSrc() || this.defaultUrl);
+
+  protected readonly accessibleName = computed<string>(
+    () => this.ariaLabel() || this.alt() || this.label() || 'Avatar',
+  );
+
+  protected onImageError(): void {
+    this.failedSrc.set(this.src() ?? null);
+  }
+
+  private resolveSize(value: CaoAvatarPresetSize | number | string): number {
+    if (typeof value === 'number') {return value > 0 ? value : CAO_AVATAR_SIZES.normal;}
+    if (value in CAO_AVATAR_SIZES) {return CAO_AVATAR_SIZES[value as CaoAvatarPresetSize];}
+
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed) || parsed <= 0) {return CAO_AVATAR_SIZES.normal;}
+    return value.trim().endsWith('rem') || value.trim().endsWith('em') ? parsed * 16 : parsed;
+  }
+}

package/src/lib/shared/components/avatar/index.ts

@@ -0,0 +1,3 @@
+export * from './avatar'
+export * from './avatar.constants'
+export * from './avatar.model'

package/src/lib/shared/components/breadcrumb/breadcrumb.css

@@ -0,0 +1,105 @@
+:host {
+  display: block;
+}
+
+.cao-breadcrumb {
+  --_link: var(--cao-breadcrumb-link-color, #6b7280);
+  --_link-hover: var(--cao-breadcrumb-link-hover-color, #4f46e5);
+  --_current: var(--cao-breadcrumb-current-color, #111827);
+  --_separator: var(--cao-breadcrumb-separator-color, #9ca3af);
+  --_disabled: var(--cao-breadcrumb-disabled-color, #d1d5db);
+  --_focus: var(--cao-breadcrumb-focus-ring, rgba(79, 70, 229, 0.35));
+  --_badge-bg: var(--cao-breadcrumb-badge-bg, #eef2ff);
+  --_badge-text: var(--cao-breadcrumb-badge-text, #4338ca);
+  --_gap: var(--cao-breadcrumb-gap, 8px);
+  --_size: var(--cao-breadcrumb-font-size, 0.875rem);
+}
+
+.cao-breadcrumb__list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--_gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: var(--_size);
+  line-height: 1.25;
+}
+
+.cao-breadcrumb__item,
+.cao-breadcrumb__separator {
+  display: inline-flex;
+  align-items: center;
+}
+
+.cao-breadcrumb__separator {
+  color: var(--_separator);
+  user-select: none;
+}
+
+.cao-breadcrumb__action,
+.cao-breadcrumb__text {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 4px;
+  border: 0;
+  border-radius: 4px;
+  background: none;
+  color: var(--_link);
+  font: inherit;
+  text-decoration: none;
+}
+
+.cao-breadcrumb__action {
+  cursor: pointer;
+  transition: color 150ms ease;
+}
+
+.cao-breadcrumb__action:hover {
+  color: var(--_link-hover);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+
+.cao-breadcrumb__action:focus-visible {
+  outline: 2px solid var(--_focus);
+  outline-offset: 1px;
+}
+
+.cao-breadcrumb__item--current .cao-breadcrumb__text {
+  color: var(--_current);
+  font-weight: 600;
+}
+
+.cao-breadcrumb__item--disabled .cao-breadcrumb__text {
+  color: var(--_disabled);
+  cursor: not-allowed;
+}
+
+.cao-breadcrumb__icon {
+  display: inline-flex;
+  align-items: center;
+  line-height: 0;
+}
+
+.cao-breadcrumb__badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  padding: 1px 6px;
+  border-radius: 999px;
+  background: var(--_badge-bg);
+  color: var(--_badge-text);
+  font-size: 0.75em;
+  font-weight: 600;
+  line-height: 1.4;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .cao-breadcrumb__action {
+    transition: none;
+  }
+}

package/src/lib/shared/components/breadcrumb/breadcrumb.html

@@ -0,0 +1,108 @@
+<ng-template #content let-item let-index="index">
+  @if (item.icon && iconPosition(item) === 'left') {
+    <ng-container *ngTemplateOutlet="icon; context: { $implicit: item }" />
+  }
+  @if (item.label) {
+    <span class="cao-breadcrumb__label">{{ item.label }}</span>
+  }
+  @if (item.icon && iconPosition(item) === 'right') {
+    <ng-container *ngTemplateOutlet="icon; context: { $implicit: item }" />
+  }
+  @if (item.badge !== undefined && item.badge !== null && item.badge !== '') {
+    <span
+      class="cao-breadcrumb__badge"
+      [style.color]="item.badgeColor || null"
+      [style.background-color]="item.badgeBgColor || null"
+      [attr.data-cy]="item.dataCy ? item.dataCy + '-badge' : null">
+      {{ item.badge }}
+    </span>
+  }
+</ng-template>
+
+<ng-template #icon let-item>
+  <span class="cao-breadcrumb__icon" aria-hidden="true">
+    <cao-base-icon
+      [imgSource]="item.icon"
+      [isLucideIcon]="isLucide(item)"
+      [iconColor]="item.iconColor ?? ''"
+      [strokeWidthIcon]="item.iconStrokeWidth ?? 1.5"
+      [size]="item.iconSize ?? 16" />
+  </span>
+</ng-template>
+
+@if (allItems().length) {
+  <nav
+    class="cao-breadcrumb"
+    [attr.aria-label]="ariaLabel()"
+    [attr.data-cy]="dataCy() || null"
+    [style.--cao-breadcrumb-link-color]="linkColor() || null"
+    [style.--cao-breadcrumb-link-hover-color]="linkHoverColor() || null"
+    [style.--cao-breadcrumb-current-color]="currentColor() || null"
+    [style.--cao-breadcrumb-separator-color]="separatorColor() || null"
+    [style.--cao-breadcrumb-font-size]="fontSize() || null"
+    [style.--cao-breadcrumb-gap]="gap() || null">
+    <ol class="cao-breadcrumb__list">
+      @for (item of allItems(); track $index; let i = $index; let last = $last) {
+        <li
+          class="cao-breadcrumb__item"
+          [class.cao-breadcrumb__item--current]="last"
+          [class.cao-breadcrumb__item--disabled]="item.disabled"
+          [attr.data-cy]="item.dataCy || null">
+          @if (isInteractive(item, last)) {
+            @if (hasLink(item)) {
+              <a
+                class="cao-breadcrumb__action"
+                [routerLink]="item.link"
+                [queryParams]="item.queryParams"
+                [target]="item.target ?? '_self'"
+                [attr.aria-label]="item.ariaLabel || null"
+                (click)="onItemClick(item, i, $event)">
+                <ng-container *ngTemplateOutlet="content; context: { $implicit: item, index: i }" />
+              </a>
+            } @else if (item.href) {
+              <a
+                class="cao-breadcrumb__action"
+                [attr.href]="item.href"
+                [attr.target]="item.target || null"
+                [attr.rel]="item.target === '_blank' ? 'noopener noreferrer' : null"
+                [attr.aria-label]="item.ariaLabel || null"
+                (click)="onItemClick(item, i, $event)">
+                <ng-container *ngTemplateOutlet="content; context: { $implicit: item, index: i }" />
+              </a>
+            } @else {
+              <button
+                type="button"
+                class="cao-breadcrumb__action"
+                [attr.aria-label]="item.ariaLabel || null"
+                (click)="onItemClick(item, i, $event)">
+                <ng-container *ngTemplateOutlet="content; context: { $implicit: item, index: i }" />
+              </button>
+            }
+          } @else {
+            <span
+              class="cao-breadcrumb__text"
+              [attr.aria-current]="last ? 'page' : null"
+              [attr.aria-disabled]="item.disabled ? 'true' : null"
+              [attr.aria-label]="item.ariaLabel || null">
+              <ng-container *ngTemplateOutlet="content; context: { $implicit: item, index: i }" />
+            </span>
+          }
+        </li>
+
+        @if (!last) {
+          <li class="cao-breadcrumb__separator" role="presentation" aria-hidden="true">
+            @if (separatorIcon()) {
+              <cao-base-icon
+                [imgSource]="separatorIcon()"
+                [isLucideIcon]="isLucideSeparatorIcon()"
+                [strokeWidthIcon]="separatorIconStrokeWidth()"
+                [size]="separatorIconSize()" />
+            } @else {
+              {{ separator() }}
+            }
+          </li>
+        }
+      }
+    </ol>
+  </nav>
+}

package/src/lib/shared/components/breadcrumb/breadcrumb.model.ts

@@ -0,0 +1,54 @@
+import { Params } from '@angular/router';
+
+/** Posição do ícone em relação ao texto do item. */
+export type CaoBreadcrumbIconPosition = 'left' | 'right';
+
+/** Item do breadcrumb. */
+export interface ICaoBreadcrumbItem {
+  /** Texto exibido. Pode ser omitido em itens apenas com ícone (informe `ariaLabel`). */
+  label?: string;
+  /** Nome do ícone Lucide ou caminho/URL/data URI da imagem. */
+  icon?: string;
+  /** Define se `icon` é um ícone Lucide. Padrão: `true`. */
+  isLucideIcon?: boolean;
+  /** Posição do ícone em relação ao texto. Padrão: `'left'`. */
+  iconPosition?: CaoBreadcrumbIconPosition;
+  /** Cor do ícone (aplicada a ícones Lucide). */
+  iconColor?: string;
+  /** Tamanho do ícone em px. Padrão: `16`. */
+  iconSize?: number;
+  /** Espessura do traço do ícone Lucide. Padrão: `1.5`. */
+  iconStrokeWidth?: number;
+
+  /** Navegação interna via Angular Router (ex.: `'/clientes'` ou `['/clientes', 12]`). */
+  link?: string | unknown[];
+  /** Query params usados junto com `link`. */
+  queryParams?: Params;
+  /** Navegação externa via `href`. Ignorado se `link` estiver definido. */
+  href?: string;
+  /** `target` do link (ex.: `'_blank'`). */
+  target?: '_self' | '_blank' | '_parent' | '_top';
+  /** Callback executado ao clicar (item sem `link`/`href` vira um botão). */
+  command?: (event: ICaoBreadcrumbItemClickEvent) => void;
+
+  /** Texto/valor do badge exibido após o item. */
+  badge?: string | number;
+  /** Cor do texto do badge. */
+  badgeColor?: string;
+  /** Cor de fundo do badge. */
+  badgeBgColor?: string;
+
+  /** Desabilita a interação com o item. */
+  disabled?: boolean;
+  /** `aria-label` do item (recomendado para itens apenas com ícone). */
+  ariaLabel?: string;
+  /** Atributo `data-cy` para testes E2E. */
+  dataCy?: string;
+}
+
+/** Evento emitido ao clicar em um item. */
+export interface ICaoBreadcrumbItemClickEvent {
+  item: ICaoBreadcrumbItem;
+  index: number;
+  originalEvent: Event;
+}