@kouji-ui/core 0.0.3 → 0.1.1

package/src/breadcrumb/breadcrumb.spec.ts

@@ -0,0 +1,354 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjBreadcrumb } from './breadcrumb';
+import { KjBreadcrumbList } from './breadcrumb-list';
+import { KjBreadcrumbItem } from './breadcrumb-item';
+import { KjBreadcrumbLink } from './breadcrumb-link';
+import { KjBreadcrumbCurrent } from './breadcrumb-current';
+import { KjBreadcrumbSeparator } from './breadcrumb-separator';
+import { KjBreadcrumbEllipsis } from './breadcrumb-ellipsis';
+
+const imports = [
+  KjBreadcrumb,
+  KjBreadcrumbList,
+  KjBreadcrumbItem,
+  KjBreadcrumbLink,
+  KjBreadcrumbCurrent,
+  KjBreadcrumbSeparator,
+  KjBreadcrumbEllipsis,
+];
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <nav kjBreadcrumb [kjMaxItems]="maxItems()" [kjOverflow]="overflow()">
+      <ol kjBreadcrumbList>
+        @for (crumb of crumbs(); track crumb.label; let last = $last) {
+          <li kjBreadcrumbItem>
+            @if (last) {
+              <span kjBreadcrumbCurrent>{{ crumb.label }}</span>
+            } @else {
+              <a kjBreadcrumbLink [attr.href]="crumb.href">{{ crumb.label }}</a>
+            }
+          </li>
+        }
+      </ol>
+    </nav>
+  `,
+})
+class BreadcrumbHost {
+  readonly crumbs = signal<{ label: string; href: string }[]>([
+    { label: 'Home', href: '/' },
+    { label: 'Library', href: '/library' },
+    { label: 'Data', href: '/library/data' },
+  ]);
+  readonly maxItems = signal<number>(4);
+  readonly overflow = signal<'truncate' | 'menu' | 'none'>('truncate');
+}
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <nav kjBreadcrumb>
+      <ol kjBreadcrumbList>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+        <li kjBreadcrumbSeparator>›</li>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/library">Library</a></li>
+        <li kjBreadcrumbSeparator>›</li>
+        <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Data</span></li>
+      </ol>
+    </nav>
+  `,
+})
+class ExplicitSeparatorHost {}
+
+@Component({
+  standalone: true,
+  imports,
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <nav kjBreadcrumb [kjMaxItems]="3">
+      <ol kjBreadcrumbList>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/a">A</a></li>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/b">B</a></li>
+        <li kjBreadcrumbItem><a kjBreadcrumbLink href="/c">C</a></li>
+        <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Current</span></li>
+      </ol>
+    </nav>
+  `,
+})
+class TruncatedHost {}
+
+describe('KjBreadcrumb (root)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [BreadcrumbHost, ExplicitSeparatorHost, TruncatedHost],
+    });
+  });
+
+  test('renders <nav aria-label="Breadcrumb"> by default', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const nav = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    expect(nav).not.toBeNull();
+    expect(nav.getAttribute('aria-label')).toBe('Breadcrumb');
+  });
+
+  test('reflects data-overflow="truncate" by default', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const nav = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    expect(nav.getAttribute('data-overflow')).toBe('truncate');
+  });
+
+  test('exposes a kjBreadcrumb template ref via exportAs', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    // Selector restriction forces <nav> host — sanity check.
+    const nav = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    expect(nav.tagName.toLowerCase()).toBe('nav');
+  });
+});
+
+describe('KjBreadcrumbList', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [BreadcrumbHost, ExplicitSeparatorHost] });
+  });
+
+  test('renders <ol> as the host', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const ol = fixture.nativeElement.querySelector('ol[kjBreadcrumbList]');
+    expect(ol).not.toBeNull();
+    expect(ol.tagName.toLowerCase()).toBe('ol');
+  });
+
+  test('reflects data-explicit-separators when separator cells are present', () => {
+    const fixture = TestBed.createComponent(ExplicitSeparatorHost);
+    fixture.detectChanges();
+    const ol = fixture.nativeElement.querySelector('ol[kjBreadcrumbList]');
+    expect(ol.getAttribute('data-explicit-separators')).toBe('');
+  });
+
+  test('omits data-explicit-separators when separators are auto', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const ol = fixture.nativeElement.querySelector('ol[kjBreadcrumbList]');
+    expect(ol.hasAttribute('data-explicit-separators')).toBe(false);
+  });
+});
+
+describe('KjBreadcrumbItem', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [BreadcrumbHost, TruncatedHost] });
+  });
+
+  test('renders one <li> per crumb', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const items = fixture.nativeElement.querySelectorAll('li[kjBreadcrumbItem]');
+    expect(items.length).toBe(3);
+  });
+
+  test('hides truncated items via data-hidden', () => {
+    const fixture = TestBed.createComponent(TruncatedHost);
+    fixture.detectChanges();
+    const items = fixture.nativeElement.querySelectorAll('li[kjBreadcrumbItem]');
+    // 5 total, kjMaxItems=3 → first + last (3-2)=1 last = first + last 1 visible.
+    // visible indices: [0, 4]. hidden: [1, 2, 3].
+    expect(items[0].hasAttribute('data-hidden')).toBe(false);
+    expect(items[1].getAttribute('data-hidden')).toBe('');
+    expect(items[2].getAttribute('data-hidden')).toBe('');
+    expect(items[3].getAttribute('data-hidden')).toBe('');
+    expect(items[4].hasAttribute('data-hidden')).toBe(false);
+  });
+});
+
+describe('KjBreadcrumbCurrent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [BreadcrumbHost] });
+  });
+
+  test('reflects aria-current="page"', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const current = fixture.nativeElement.querySelector('[kjBreadcrumbCurrent]');
+    expect(current).not.toBeNull();
+    expect(current.getAttribute('aria-current')).toBe('page');
+  });
+
+  test('the parent <li> does NOT also receive aria-current when explicit current is registered', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const items = fixture.nativeElement.querySelectorAll('li[kjBreadcrumbItem]');
+    // With an explicit KjBreadcrumbCurrent the parent <li> should NOT carry
+    // aria-current — only the <span> does.
+    const last = items[items.length - 1];
+    expect(last.hasAttribute('aria-current')).toBe(false);
+  });
+});
+
+describe('KjBreadcrumbSeparator', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [ExplicitSeparatorHost] });
+  });
+
+  test('reflects role="presentation" + aria-hidden="true"', () => {
+    const fixture = TestBed.createComponent(ExplicitSeparatorHost);
+    fixture.detectChanges();
+    const sep = fixture.nativeElement.querySelector('li[kjBreadcrumbSeparator]');
+    expect(sep).not.toBeNull();
+    expect(sep.getAttribute('role')).toBe('presentation');
+    expect(sep.getAttribute('aria-hidden')).toBe('true');
+  });
+});
+
+describe('KjBreadcrumbLink', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [BreadcrumbHost] });
+  });
+
+  test('the directive composes KjLink — host carries data-underline + data-variant + data-size', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a[kjBreadcrumbLink]');
+    expect(link).not.toBeNull();
+    // KjLink defaults reflect to data-underline; the breadcrumb wrapper sets
+    // size/variant/underline through forwarded inputs at the components layer,
+    // here we just verify KjLink is composed by checking data-underline exists.
+    expect(link.hasAttribute('data-underline')).toBe(true);
+  });
+
+  test('marks the host with data-breadcrumb-link', () => {
+    const fixture = TestBed.createComponent(BreadcrumbHost);
+    fixture.detectChanges();
+    const link = fixture.nativeElement.querySelector('a[kjBreadcrumbLink]');
+    expect(link.getAttribute('data-breadcrumb-link')).toBe('');
+  });
+});
+
+describe('KjBreadcrumb truncation', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [TruncatedHost] });
+  });
+
+  test('appends "(N items hidden)" to aria-label in truncate mode', () => {
+    const fixture = TestBed.createComponent(TruncatedHost);
+    fixture.detectChanges();
+    const nav = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    // 5 items, maxItems=3 → 3 hidden.
+    expect(nav.getAttribute('aria-label')).toContain('3 items hidden');
+  });
+
+  test('does not append count when overflow is "none"', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <nav kjBreadcrumb [kjMaxItems]="3" kjOverflow="none">
+          <ol kjBreadcrumbList>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/a">A</a></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/b">B</a></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/c">C</a></li>
+            <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Cur</span></li>
+          </ol>
+        </nav>
+      `,
+    })
+    class NoneHost {}
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({ imports: [NoneHost] });
+    const fixture = TestBed.createComponent(NoneHost);
+    fixture.detectChanges();
+    const nav = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    expect(nav.getAttribute('aria-label')).toBe('Breadcrumb');
+  });
+});
+
+describe('KjBreadcrumbEllipsis', () => {
+  test('reflects aria-hidden="true" in truncate mode', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <nav kjBreadcrumb [kjMaxItems]="3">
+          <ol kjBreadcrumbList>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+            <li kjBreadcrumbItem><span kjBreadcrumbEllipsis>…</span></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/a">A</a></li>
+            <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Cur</span></li>
+          </ol>
+        </nav>
+      `,
+    })
+    class EllipsisHost {}
+
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({ imports: [EllipsisHost] });
+    const fixture = TestBed.createComponent(EllipsisHost);
+    fixture.detectChanges();
+    const ell = fixture.nativeElement.querySelector('[kjBreadcrumbEllipsis]');
+    expect(ell).not.toBeNull();
+    expect(ell.getAttribute('aria-hidden')).toBe('true');
+  });
+
+  test('reflects aria-haspopup="true" + label in menu mode', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <nav kjBreadcrumb [kjMaxItems]="3" kjOverflow="menu">
+          <ol kjBreadcrumbList>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/a">A</a></li>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/b">B</a></li>
+            <li kjBreadcrumbItem><button kjBreadcrumbEllipsis>…</button></li>
+            <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Cur</span></li>
+          </ol>
+        </nav>
+      `,
+    })
+    class MenuHost {}
+
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({ imports: [MenuHost] });
+    const fixture = TestBed.createComponent(MenuHost);
+    fixture.detectChanges();
+    const ell = fixture.nativeElement.querySelector('[kjBreadcrumbEllipsis]');
+    expect(ell.getAttribute('aria-haspopup')).toBe('true');
+    expect(ell.getAttribute('aria-label')).toContain('hidden');
+  });
+});
+
+describe('KjBreadcrumb separator wiring', () => {
+  test('kjSeparator reflects to --kj-breadcrumb-separator-content style', () => {
+    @Component({
+      standalone: true,
+      imports,
+      template: `
+        <nav kjBreadcrumb kjSeparator="›">
+          <ol kjBreadcrumbList>
+            <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+            <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Cur</span></li>
+          </ol>
+        </nav>
+      `,
+    })
+    class SepHost {}
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({ imports: [SepHost] });
+    const fixture = TestBed.createComponent(SepHost);
+    fixture.detectChanges();
+    const nav: HTMLElement = fixture.nativeElement.querySelector('nav[kjBreadcrumb]');
+    // The custom property should resolve to "'›'".
+    const cssValue = nav.style.getPropertyValue('--kj-breadcrumb-separator-content');
+    expect(cssValue).toContain('›');
+  });
+});

package/src/breadcrumb/breadcrumb.ts

@@ -0,0 +1,239 @@
+import {
+  Directive,
+  Signal,
+  computed,
+  effect,
+  inject,
+  input,
+  isDevMode,
+  signal,
+} from '@angular/core';
+import { KjSize, bindPresets } from '../presets';
+import { KJ_BREADCRUMB_CONFIG } from './config';
+import {
+  KJ_BREADCRUMB,
+  KjBreadcrumbContext,
+  KjBreadcrumbItemContext,
+} from './breadcrumb.context';
+
+/** @internal Internal entry stored in the items signal. */
+interface KjBreadcrumbItemEntry {
+  indexSignal: ReturnType<typeof signal<number>>;
+  context?: KjBreadcrumbItemContext;
+}
+
+/**
+ * Root of the Breadcrumb directive family. Owns the `<nav>` landmark, the
+ * `aria-label`, the registered-items model, the truncation algorithm, and
+ * the "exactly one current crumb, last in document order" invariant.
+ *
+ * Applied to a `<nav>` element. The selector restriction
+ * (`nav[kjBreadcrumb]`) keeps the landmark's host element honest — attaching
+ * `kjBreadcrumb` to a `<div>` will simply not match.
+ *
+ * Compose with `[kjBreadcrumbList]`, `[kjBreadcrumbItem]`, `[kjBreadcrumbLink]`,
+ * and `[kjBreadcrumbCurrent]`. No styling is attached; `kjMaxItems` triggers
+ * the ellipsis overflow strategy.
+ *
+ * @example
+ * ```html
+ * <nav kjBreadcrumb>
+ *   <ol kjBreadcrumbList>
+ *     <li kjBreadcrumbItem><a kjBreadcrumbLink href="/">Home</a></li>
+ *     <li kjBreadcrumbItem><a kjBreadcrumbLink href="/library">Library</a></li>
+ *     <li kjBreadcrumbItem><span kjBreadcrumbCurrent>Data</span></li>
+ *   </ol>
+ * </nav>
+ * ```
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name breadcrumb
+ * @doc-description Unstyled breadcrumb root that owns the nav landmark, item registration, and truncation.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjBreadcrumb]',
+  standalone: true,
+  exportAs: 'kjBreadcrumb',
+  hostDirectives: [{ directive: KjSize, inputs: ['kjSize'] }],
+  providers: [
+    { provide: KJ_BREADCRUMB, useExisting: KjBreadcrumb },
+    ...bindPresets(KJ_BREADCRUMB_CONFIG),
+  ],
+  host: {
+    '[attr.aria-label]': 'effectiveAriaLabel()',
+    '[attr.data-overflow]': 'kjOverflow()',
+    '[style.--kj-breadcrumb-separator-content]': 'separatorCss()',
+  },
+})
+export class KjBreadcrumb implements KjBreadcrumbContext {
+  /** @internal */
+  readonly config = inject(KJ_BREADCRUMB_CONFIG);
+
+  /** Override for the `<nav>` `aria-label`. Defaults to `"Breadcrumb"`. */
+  readonly kjAriaLabel = input<string | undefined>(undefined);
+
+  /**
+   * Separator glyph rendered by the CSS pseudo-element on each non-first
+   * item. Defaults to `'/'`. When the consumer renders explicit
+   * `<li kjBreadcrumbSeparator>` cells, the auto separator is suppressed.
+   */
+  readonly kjSeparator = input<string | undefined>(undefined);
+
+  /**
+   * Maximum number of items to render before truncation. Default `4`. Set
+   * to `0` (or `Infinity`) to disable truncation regardless of item count.
+   */
+  readonly kjMaxItems = input<number>(this.config.defaults.maxItems);
+
+  /**
+   * Overflow strategy when item count exceeds `kjMaxItems`.
+   *
+   * - `'truncate'` (default): the ellipsis cell renders as plain `<span>`.
+   * - `'menu'`: the ellipsis becomes a `<button>` (consumers wire a
+   *   `KjDropdownMenu` to expose the hidden crumbs).
+   * - `'none'`: no truncation; all crumbs render.
+   */
+  readonly kjOverflow = input<'truncate' | 'menu' | 'none'>(this.config.defaults.overflow);
+
+  // ── Registered children (item / current / separator counts) ─────────────
+  private readonly _items = signal<readonly KjBreadcrumbItemEntry[]>([]);
+  private readonly _currents = signal<number>(0);
+  private readonly _separators = signal<number>(0);
+
+  /** Read-only count of registered items. */
+  readonly itemCount: Signal<number> = computed(() => this._items().length);
+
+  /** Read-only count of registered explicit `KjBreadcrumbCurrent` cells. */
+  readonly currentCount: Signal<number> = computed(() => this._currents());
+
+  /** Whether the consumer has rendered explicit separator cells. */
+  readonly hasExplicitSeparators: Signal<boolean> = computed(() => this._separators() > 0);
+
+  /** The configured separator glyph (input wins over config default). */
+  readonly separator: Signal<string | undefined> = computed(() => this.kjSeparator());
+
+  /** Effective `kjMaxItems` exposed to descendants. */
+  readonly maxItems: Signal<number> = computed(() => this.kjMaxItems());
+
+  /** Effective overflow mode exposed to descendants. */
+  readonly overflow: Signal<'truncate' | 'menu' | 'none'> = computed(() => this.kjOverflow());
+
+  /** Indices that should render visibly. */
+  readonly visibleIndices: Signal<readonly number[]> = computed(() => {
+    const total = this._items().length;
+    const max = this.kjMaxItems();
+    if (total === 0) return [];
+    if (this.kjOverflow() === 'none' || max <= 0 || !Number.isFinite(max) || total <= max) {
+      return Array.from({ length: total }, (_, i) => i);
+    }
+    // First crumb + last (max - 2) crumbs visible (the rest collapse).
+    const tailCount = Math.max(0, max - 2);
+    const visible: number[] = [0];
+    for (let i = total - tailCount; i < total; i++) {
+      if (i > 0) visible.push(i);
+    }
+    return visible;
+  });
+
+  /** Indices hidden by truncation. */
+  readonly hiddenIndices: Signal<readonly number[]> = computed(() => {
+    const total = this._items().length;
+    const visible = new Set(this.visibleIndices());
+    const hidden: number[] = [];
+    for (let i = 0; i < total; i++) {
+      if (!visible.has(i)) hidden.push(i);
+    }
+    return hidden;
+  });
+
+  /**
+   * The `aria-label` actually applied to the `<nav>`. When truncation is
+   * active and overflow mode is `'truncate'`, the count of hidden items is
+   * appended so AT users learn the truncation occurred.
+   */
+  protected readonly effectiveAriaLabel = computed(() => {
+    const explicit = this.kjAriaLabel();
+    const hidden = this.hiddenIndices().length;
+    if (explicit) return explicit;
+    if (hidden > 0 && this.kjOverflow() === 'truncate') {
+      return this.config.truncatedAriaLabel(this.visibleIndices().length, hidden);
+    }
+    return this.config.defaults.ariaLabel;
+  });
+
+  /** CSS custom-property value for the separator (so the `::before` reads it). */
+  protected readonly separatorCss = computed(() => {
+    const sep = this.kjSeparator();
+    return sep === undefined ? null : `'${sep.replace(/'/gu, "\\'")}'`;
+  });
+
+  constructor() {
+    if (isDevMode()) {
+      effect(() => {
+        const total = this._items().length;
+        const currents = this._currents();
+        if (total === 0) return;
+        if (currents > 1) {
+          console.warn(
+            `[kj] KjBreadcrumb: ${currents} KjBreadcrumbCurrent instances registered; expected 0 or 1. The first wins.`,
+          );
+        }
+      });
+    }
+  }
+
+  /** @internal */
+  registerItem(): KjBreadcrumbItemContext {
+    const indexSignal = signal<number>(this._items().length);
+    const entry: KjBreadcrumbItemEntry = { indexSignal };
+    this._items.update((arr) => [...arr, entry]);
+    this._items().forEach((it, i) => it.indexSignal.set(i));
+
+    const ctx: KjBreadcrumbItemContext = {
+      index: indexSignal.asReadonly(),
+      current: computed(() => this.computeItemCurrent(indexSignal())),
+      hidden: computed(() => this.hiddenIndices().includes(indexSignal())),
+    };
+    entry.context = ctx;
+    return ctx;
+  }
+
+  /** @internal */
+  unregisterItem(item: KjBreadcrumbItemContext): void {
+    this._items.update((arr) => arr.filter((e) => e.context !== item));
+    this._items().forEach((it, i) => it.indexSignal.set(i));
+  }
+
+  /** @internal */
+  registerCurrent(): void {
+    this._currents.update((n) => n + 1);
+  }
+
+  /** @internal */
+  unregisterCurrent(): void {
+    this._currents.update((n) => Math.max(0, n - 1));
+  }
+
+  /** @internal */
+  registerSeparator(): void {
+    this._separators.update((n) => n + 1);
+  }
+
+  /** @internal */
+  unregisterSeparator(): void {
+    this._separators.update((n) => Math.max(0, n - 1));
+  }
+
+  /**
+   * Auto-current rule: an item is current when it is the last item AND no
+   * explicit `KjBreadcrumbCurrent` is registered anywhere in the tree.
+   */
+  private computeItemCurrent(index: number): boolean {
+    const total = this._items().length;
+    if (total === 0) return false;
+    if (this._currents() > 0) return false;
+    return index === total - 1;
+  }
+}

package/src/breadcrumb/config.ts

@@ -0,0 +1,84 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/**
+ * Configuration shape for the Breadcrumb directive family. Exposes preset
+ * lists, default truncation policy, and the (mostly i18n-facing) labels the
+ * directives reflect into the DOM.
+ */
+export interface KjBreadcrumbConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: {
+    variant: string;
+    size: string;
+    /** `aria-label` on the root `<nav>` host element. */
+    ariaLabel: string;
+    /** Default separator glyph. */
+    separator: string;
+    /** Default `kjMaxItems`. `0` disables truncation. */
+    maxItems: number;
+    /** Default overflow mode. */
+    overflow: 'truncate' | 'menu' | 'none';
+    /** Default link variant for `KjBreadcrumbLink`. */
+    linkVariant: string;
+    /** Default link size for `KjBreadcrumbLink`. */
+    linkSize: string;
+    /** Default underline mode for `KjBreadcrumbLink`. */
+    linkUnderline: 'always' | 'hover' | 'none';
+  };
+  /** Computes the `aria-label` for the `<nav>` when items are truncated. */
+  truncatedAriaLabel: (visible: number, hidden: number) => string;
+  /** Computes the `aria-label` for the ellipsis trigger button (menu mode). */
+  ellipsisLabel: (hidden: number) => string;
+}
+
+/**
+ * Default Breadcrumb presets shipped by kouji-ui. Exported so consumers can
+ * spread when extending: `[...KJ_BREADCRUMB_DEFAULTS.sizes, 'xl']`.
+ */
+export const KJ_BREADCRUMB_DEFAULTS: KjBreadcrumbConfig = {
+  variants: ['default'],
+  sizes: ['sm', 'md', 'lg'],
+  defaults: {
+    variant: 'default',
+    size: 'md',
+    ariaLabel: 'Breadcrumb',
+    separator: '/',
+    maxItems: 4,
+    overflow: 'truncate',
+    linkVariant: 'muted',
+    linkSize: 'sm',
+    linkUnderline: 'hover',
+  },
+  truncatedAriaLabel: (_visible, hidden) =>
+    hidden === 1 ? 'Breadcrumb (1 item hidden)' : `Breadcrumb (${hidden} items hidden)`,
+  ellipsisLabel: (hidden) =>
+    hidden === 1 ? 'Show 1 hidden breadcrumb' : `Show ${hidden} hidden breadcrumbs`,
+};
+
+/**
+ * DI token for the active Breadcrumb presets. Default factory yields
+ * `KJ_BREADCRUMB_DEFAULTS`. Override via `provideKjBreadcrumb(…)` at the
+ * application or component scope.
+ */
+export const KJ_BREADCRUMB_CONFIG = new InjectionToken<KjBreadcrumbConfig>(
+  'kj.breadcrumb.config',
+  { factory: () => KJ_BREADCRUMB_DEFAULTS },
+);
+
+/**
+ * Configures the Breadcrumb presets / labels for the enclosing injector.
+ * Shallow-merges over the defaults — pass only the fields you want to override.
+ */
+export function provideKjBreadcrumb(config: Partial<KjBreadcrumbConfig>): Provider[] {
+  return [
+    {
+      provide: KJ_BREADCRUMB_CONFIG,
+      useValue: {
+        ...KJ_BREADCRUMB_DEFAULTS,
+        ...config,
+        defaults: { ...KJ_BREADCRUMB_DEFAULTS.defaults, ...(config.defaults ?? {}) },
+      },
+    },
+  ];
+}

package/src/breadcrumb/index.ts

@@ -0,0 +1,18 @@
+export { KjBreadcrumb } from './breadcrumb';
+export { KjBreadcrumbList } from './breadcrumb-list';
+export { KjBreadcrumbItem } from './breadcrumb-item';
+export { KjBreadcrumbLink } from './breadcrumb-link';
+export { KjBreadcrumbCurrent } from './breadcrumb-current';
+export { KjBreadcrumbSeparator } from './breadcrumb-separator';
+export { KjBreadcrumbEllipsis } from './breadcrumb-ellipsis';
+export {
+  KJ_BREADCRUMB,
+  type KjBreadcrumbContext,
+  type KjBreadcrumbItemContext,
+} from './breadcrumb.context';
+export {
+  KJ_BREADCRUMB_CONFIG,
+  KJ_BREADCRUMB_DEFAULTS,
+  provideKjBreadcrumb,
+  type KjBreadcrumbConfig,
+} from './config';