@dashforge/tw 0.1.0-beta

package/src/components/Autocomplete/autocomplete.types.ts

@@ -0,0 +1,198 @@
+import type { ReactNode } from 'react';
+import type { Engine } from '@dashforge/ui-core';
+import type { AccessRequirement } from '@dashforge/rbac';
+import type { AutocompleteVariants } from './autocomplete.variants.js';
+
+/**
+ * Default `{ value, label, disabled? }` option shape.
+ *
+ * The simplest shape and the one used by the component when no
+ * `getOptionValue` / `getOptionLabel` props are provided. For richer
+ * option shapes (e.g., `{ id, name, country, ... }`) make the component
+ * generic by passing `<TOption>` and providing the accessors:
+ *
+ * ```tsx
+ * type User = { id: string; name: string; admin?: boolean };
+ *
+ * <Autocomplete<User>
+ *   name="owner"
+ *   options={users}
+ *   getOptionValue={(u) => u.id}
+ *   getOptionLabel={(u) => u.name}
+ *   getOptionDisabled={(u) => !u.admin}
+ * />
+ * ```
+ */
+export interface AutocompleteOption {
+  /** Value persisted on the form. */
+  value: string;
+  /** Display label (string or any React node). */
+  label: ReactNode;
+  /** Per-option explicit disable. */
+  disabled?: boolean;
+}
+
+export interface AutocompleteSlotProps {
+  root?: { className?: string };
+  label?: { className?: string };
+  requiredMark?: { className?: string };
+  inputWrapper?: { className?: string };
+  input?: { className?: string };
+  trigger?: { className?: string };
+  clearButton?: { className?: string };
+  popover?: { className?: string };
+  listBox?: { className?: string };
+  listItem?: { className?: string };
+  emptyState?: { className?: string };
+  helperText?: { className?: string };
+  errorText?: { className?: string };
+  /** Wrapper around the chip list (multi-select only). */
+  chipsList?: { className?: string };
+  /** Individual chip displayed in multi-select. */
+  chip?: { className?: string };
+  /** `×` button on a chip. */
+  chipRemove?: { className?: string };
+}
+
+/**
+ * Union of the value shapes `<Autocomplete>` accepts.
+ *
+ * - **Single-select (default)**: `string | null`
+ * - **Multi-select** (`multiple` prop): `string[] | null`
+ *
+ * `null` means "no selection" in both modes — a multi-select with no
+ * picks emits an empty array on first commit, then keeps emitting arrays.
+ */
+export type AutocompleteValue = string | string[] | null;
+
+/**
+ * Props for `<Autocomplete>`.
+ *
+ * Bridge-integrated single-select combobox with full ARIA combobox
+ * a11y, keyboard navigation, and Form Closure v1 error gating.
+ *
+ * Mirrors the MUI-side `@dashforge/ui/Autocomplete` at the bridge
+ * level — same `name` / `rules` / `visibleWhen` / `access` semantics,
+ * same StrictMode-safe unregister-on-unmount.
+ *
+ * @typeParam TOption  Shape of an option. Defaults to
+ *                     `AutocompleteOption` (`{ value, label, disabled? }`).
+ *                     Pass `<TOption>` + `getOptionValue` / `getOptionLabel`
+ *                     for arbitrary domain types.
+ */
+export interface AutocompleteProps<TOption = AutocompleteOption>
+  extends AutocompleteVariants {
+  name: string;
+  rules?: unknown;
+  options: TOption[];
+  label?: ReactNode;
+  helperText?: ReactNode;
+  required?: boolean;
+  error?: boolean;
+  disabled?: boolean;
+  /** Placeholder shown when the input is empty. */
+  placeholder?: string;
+  /** Engine predicate — field not rendered when it returns `false`. */
+  visibleWhen?: (engine: Engine) => boolean;
+  /** RBAC access requirement. */
+  access?: AccessRequirement;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot className overrides. */
+  slotProps?: AutocompleteSlotProps;
+  /** Controlled value (form mode reads from the bridge if omitted). */
+  value?: AutocompleteValue;
+  /** Default value for uncontrolled mode (no-op in form mode). */
+  defaultValue?: AutocompleteValue;
+  /** Fires when the user picks an option (after bridge update in form mode). */
+  onValueChange?: (value: AutocompleteValue) => void;
+  /** Fallback text when no option matches the typed filter. */
+  emptyMessage?: string;
+
+  // ───── F5-A-bis: multi-select ─────
+
+  /**
+   * Multi-select mode. When `true`:
+   *
+   * - `value` / `defaultValue` accept `string[]` (or `null`).
+   * - Picks are toggled rather than replaced; the popover stays open.
+   * - Selected items render as chips inside the input wrapper.
+   * - Backspace at the start of an empty input removes the last chip.
+   * - The clear button (`×`) clears the entire selection.
+   */
+  multiple?: boolean;
+
+  // ───── F5-A-bis: free-solo ─────
+
+  /**
+   * Allow committing arbitrary strings (not just option values).
+   *
+   * When `true`:
+   *   - **Enter** commits the typed text as the value when no option
+   *     row is highlighted (or no rows match the filter).
+   *   - **Blur** commits the typed text the same way, unless the text
+   *     exactly matches an existing option's label (in which case the
+   *     option's value snaps in).
+   *   - In multi mode, each free-solo commit adds a new chip whose key
+   *     and label are the typed string.
+   *
+   * Free-solo is independent of `multiple` — works in both modes.
+   */
+  freeSolo?: boolean;
+
+  // ───── F5-A-bis: async runtime options ─────
+
+  /**
+   * Async option loader. Called (debounced by `loadDebounceMs`) every
+   * time the user types in the input. Results replace the static
+   * `options` prop while the user is actively filtering.
+   *
+   * Return a promise that resolves with the new option list. Reject /
+   * throw to surface a generic empty state.
+   *
+   * @example
+   * ```tsx
+   * <Autocomplete
+   *   name="user"
+   *   options={[]}
+   *   loadOptions={async (q) => {
+   *     const res = await fetch(`/api/users?q=${q}`);
+   *     return res.ok ? res.json() : [];
+   *   }}
+   * />
+   * ```
+   */
+  loadOptions?: (query: string) => Promise<TOption[]>;
+  /**
+   * Debounce window (ms) for `loadOptions`. The loader fires after the
+   * user stops typing for this long.
+   * @default 250
+   */
+  loadDebounceMs?: number;
+  /** Text displayed in the popover while a fetch is in flight. */
+  loadingMessage?: ReactNode;
+
+  // ───── Generic option accessors (F5-A-bis) ─────
+
+  /**
+   * Extract the persistable value (string) from an option.
+   * @default `(o) => (o as AutocompleteOption).value`
+   */
+  getOptionValue?: (option: TOption) => string;
+  /**
+   * Extract the display label from an option.
+   * @default `(o) => (o as AutocompleteOption).label`
+   */
+  getOptionLabel?: (option: TOption) => ReactNode;
+  /**
+   * Per-option disabled flag.
+   * @default `(o) => Boolean((o as AutocompleteOption).disabled)`
+   */
+  getOptionDisabled?: (option: TOption) => boolean;
+  /**
+   * Unique React key for an option. Defaults to `getOptionValue`.
+   * Override if your `value` strings can collide across distinct
+   * option records (rare).
+   */
+  getOptionKey?: (option: TOption) => string;
+}

package/src/components/Autocomplete/autocomplete.variants.ts

@@ -0,0 +1,135 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<Autocomplete>` with slots.
+ *
+ * Slots:
+ *   - `root`         — outer wrapper (label + combobox + helper/error)
+ *   - `label`        — text label above the input
+ *   - `requiredMark` — red `*` for required fields
+ *   - `inputWrapper` — surface holding the input + clear/trigger buttons
+ *   - `input`        — the typeable text input
+ *   - `trigger`      — caret / chevron button that opens the popover
+ *   - `clearButton`  — `×` button to clear the current selection
+ *   - `popover`      — floating panel containing the option list
+ *   - `listBox`      — list element wrapping the options
+ *   - `listItem`     — single option row
+ *   - `emptyState`   — fallback when no options match the filter
+ *   - `helperText`   — descriptive line below the input
+ *   - `errorText`    — semantic counterpart for error mode
+ *   - `chipsList`    — wrapper around selected chips (multi-select only)
+ *   - `chip`         — individual selected chip
+ *   - `chipRemove`   — `×` button on a chip
+ */
+export const autocompleteVariants = tv({
+  slots: {
+    root: 'flex',
+    label: 'block text-sm font-medium text-neutral-900 mb-1',
+    requiredMark: 'text-danger-500 ml-0.5',
+    inputWrapper: [
+      'relative flex items-center',
+      'rounded-md border bg-neutral-50',
+      'border-neutral-300',
+      'transition-colors',
+      'focus-within:border-primary-500 focus-within:ring-2 focus-within:ring-primary-500/30',
+    ],
+    input: [
+      'block w-full bg-transparent outline-none',
+      'text-neutral-900 placeholder:text-neutral-400',
+      'disabled:cursor-not-allowed disabled:opacity-60',
+      'read-only:cursor-default',
+    ],
+    trigger: [
+      'flex items-center justify-center shrink-0 px-2',
+      'text-neutral-600 hover:text-neutral-900',
+      'disabled:cursor-not-allowed disabled:opacity-40',
+      'transition-colors',
+    ],
+    clearButton: [
+      'flex items-center justify-center shrink-0 px-2',
+      'text-neutral-500 hover:text-neutral-900',
+      'transition-colors',
+    ],
+    popover: [
+      'z-50 mt-1 max-h-64 overflow-auto',
+      'rounded-md border bg-neutral-50 border-neutral-300 shadow-lg',
+      'min-w-[var(--trigger-width)]',
+    ],
+    listBox: 'outline-none py-1',
+    listItem: [
+      'cursor-pointer select-none px-3 py-2 text-sm text-neutral-900',
+      'outline-none',
+      'data-[focused]:bg-primary-50 data-[focused]:text-primary-900',
+      'data-[selected]:bg-primary-100 data-[selected]:text-primary-900 data-[selected]:font-medium',
+      'data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed',
+    ],
+    emptyState: 'px-3 py-2 text-sm text-neutral-500',
+    helperText: 'mt-1 text-sm text-neutral-600',
+    errorText: 'mt-1 text-sm text-danger-600',
+    chipsList: 'flex flex-wrap items-center gap-1 px-1 py-1',
+    chip: [
+      'inline-flex items-center gap-1 shrink-0',
+      'rounded-md bg-primary-100 text-primary-900',
+      'px-2 py-0.5 text-xs font-medium',
+      'border border-primary-200',
+    ],
+    chipRemove: [
+      'inline-flex items-center justify-center',
+      'rounded-sm w-4 h-4 text-primary-700',
+      'hover:bg-primary-200 hover:text-primary-900',
+      'transition-colors',
+    ],
+  },
+  variants: {
+    size: {
+      sm: {
+        inputWrapper: 'h-8',
+        input: 'text-sm px-2',
+        trigger: 'h-8 text-xs',
+        clearButton: 'h-8',
+      },
+      md: {
+        inputWrapper: 'h-10',
+        input: 'text-base px-3',
+        trigger: 'h-10 text-sm',
+        clearButton: 'h-10',
+      },
+      lg: {
+        inputWrapper: 'h-12',
+        input: 'text-lg px-4',
+        trigger: 'h-12 text-base',
+        clearButton: 'h-12',
+      },
+    },
+    layout: {
+      stacked: { root: 'flex-col' },
+      inline: { root: 'flex-row items-start gap-3', label: 'mb-0 pt-2 whitespace-nowrap shrink-0' },
+    },
+    error: {
+      true: {
+        inputWrapper:
+          'border-danger-500 focus-within:border-danger-500 focus-within:ring-danger-500/30',
+      },
+    },
+    fullWidth: {
+      true: {
+        root: 'w-full',
+        inputWrapper: 'w-full',
+      },
+    },
+    disabled: {
+      true: {
+        inputWrapper: 'opacity-60 cursor-not-allowed bg-neutral-200',
+      },
+    },
+  },
+  defaultVariants: {
+    size: 'md',
+    layout: 'stacked',
+    error: false,
+    fullWidth: false,
+    disabled: false,
+  },
+});
+
+export type AutocompleteVariants = VariantProps<typeof autocompleteVariants>;

package/src/components/Breadcrumbs/Breadcrumbs.perf.test.tsx

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+/**
+ * Performance + re-render budget tests for `<Breadcrumbs>`.
+ *
+ * Layout components are typically near the top of the tree, so a
+ * regression here ripples through everything below. Guardrails:
+ *
+ *  1. Mount cost stays bounded even with very long trails.
+ *  2. Re-rendering the parent with the SAME items reference does not
+ *     re-do the truncation memo work (verifies `useMemo` deps).
+ *  3. Truncation does not allocate per-render arrays that would defeat
+ *     the React keyed-reuse heuristics.
+ */
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { Breadcrumbs } from './Breadcrumbs.js';
+import type { BreadcrumbItem } from './breadcrumbs.types.js';
+
+void React;
+afterEach(() => cleanup());
+
+function makeTrail(n: number): BreadcrumbItem[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `c${i}`,
+    label: `Crumb ${i}`,
+    href: i === n - 1 ? undefined : `/c${i}`,
+  }));
+}
+
+function withRenderCounter<P>(
+  Component: React.ComponentType<P>,
+  counterRef: { count: number }
+): React.FC<P> {
+  return function Counted(props: P) {
+    counterRef.count++;
+    return <Component {...(props as P & object)} />;
+  };
+}
+
+describe('<Breadcrumbs> performance', () => {
+  it('mounts a 50-crumb trail under 50ms', () => {
+    const trail = makeTrail(50);
+    const t0 = performance.now();
+    render(<Breadcrumbs items={trail} />);
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(50);
+  });
+
+  it('mounts a 1000-crumb (collapsed) trail under 100ms', () => {
+    const trail = makeTrail(1000);
+    const t0 = performance.now();
+    render(<Breadcrumbs items={trail} maxItems={5} />);
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(100);
+  });
+});
+
+describe('<Breadcrumbs> re-render budget', () => {
+  it('renders at most 2 times on mount', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(Breadcrumbs, counter);
+    render(<Counted items={makeTrail(5)} />);
+    expect(counter.count).toBeLessThanOrEqual(2);
+  });
+
+  it('re-renders exactly once per prop change to items', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(Breadcrumbs, counter);
+    const a = makeTrail(3);
+    const b = makeTrail(4);
+    const c = makeTrail(5);
+    const { rerender } = render(<Counted items={a} />);
+    const baseline = counter.count;
+    rerender(<Counted items={b} />);
+    rerender(<Counted items={c} />);
+    // Two prop changes → up to two renders (plus tolerance).
+    expect(counter.count - baseline).toBeLessThanOrEqual(3);
+  });
+
+  it('does NOT re-render siblings when only Breadcrumbs items change', () => {
+    // Truncation memoization shouldn't leak through React.memo'd
+    // siblings, but at minimum it must not trigger sibling renders
+    // when the parent re-renders for an unrelated reason.
+    const sibCount = { count: 0 };
+    const Sibling = () => {
+      sibCount.count++;
+      return <div data-testid="sib" />;
+    };
+    const Tree = ({ items }: { items: BreadcrumbItem[] }) => (
+      <div>
+        <Breadcrumbs items={items} />
+        <Sibling />
+      </div>
+    );
+    const trail = makeTrail(5);
+    const { rerender } = render(<Tree items={trail} />);
+    const baseline = sibCount.count;
+    // Re-render the parent with the SAME items reference — Sibling
+    // should still re-render (parent re-rendered) but only ONCE per
+    // parent re-render, no extra renders triggered by Breadcrumbs.
+    rerender(<Tree items={trail} />);
+    rerender(<Tree items={trail} />);
+    expect(sibCount.count - baseline).toBeLessThanOrEqual(2);
+  });
+
+  it('truncation logic is stable: same items + same maxItems => same DOM ids', () => {
+    // If `useMemo` is well-keyed, the rendered <li> elements (with
+    // stable keys from item.id) should be identical DOM nodes across
+    // unrelated re-renders. Detects an accidental "always new array"
+    // refactor that would invalidate keys.
+    const items = makeTrail(10);
+    const { rerender, container } = render(
+      <Breadcrumbs items={items} maxItems={4} />
+    );
+    const firstSnapshot = Array.from(container.querySelectorAll('li')).map(
+      (li) => li.outerHTML
+    );
+    rerender(<Breadcrumbs items={items} maxItems={4} />);
+    const secondSnapshot = Array.from(container.querySelectorAll('li')).map(
+      (li) => li.outerHTML
+    );
+    expect(secondSnapshot).toEqual(firstSnapshot);
+  });
+});

package/src/components/Breadcrumbs/Breadcrumbs.test.tsx

@@ -0,0 +1,231 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  cleanup,
+} from '@testing-library/react';
+import { Breadcrumbs } from './Breadcrumbs.js';
+import type { BreadcrumbItem } from './breadcrumbs.types.js';
+
+// Keep the React import alive for the classic JSX transform — when this
+// file is run in environments where the bundler tree-shakes
+// `import * as React`, the JSX call sites would lose the global.
+void React;
+
+// Auto-cleanup is not reliably registered when test-library is loaded
+// before vitest globals are wired up — register the unmount step
+// explicitly so back-to-back `render()` calls don't accumulate trees.
+afterEach(() => {
+  cleanup();
+});
+
+const trail: BreadcrumbItem[] = [
+  { id: 'home', label: 'Home', href: '/' },
+  { id: 'settings', label: 'Settings', href: '/settings' },
+  { id: 'profile', label: 'Profile' },
+];
+
+describe('<Breadcrumbs>', () => {
+  describe('basic rendering', () => {
+    it('renders a nav with role + accessible name', () => {
+      render(<Breadcrumbs items={trail} />);
+      const nav = screen.getByRole('navigation', { name: 'Breadcrumb' });
+      expect(nav).toBeTruthy();
+    });
+
+    it('renders an <ol> with one <li> per item', () => {
+      const { container } = render(<Breadcrumbs items={trail} />);
+      expect(container.querySelectorAll('li')).toHaveLength(3);
+    });
+
+    it('returns null for an empty items array', () => {
+      const { container } = render(<Breadcrumbs items={[]} />);
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('marks the last crumb as aria-current="page" by default', () => {
+      render(<Breadcrumbs items={trail} />);
+      const current = screen.getByText('Profile').closest('span');
+      expect(current?.getAttribute('aria-current')).toBe('page');
+    });
+
+    it('honours an explicit `current: true` flag', () => {
+      const custom: BreadcrumbItem[] = [
+        { id: 'a', label: 'A', href: '/a' },
+        { id: 'b', label: 'B', current: true },
+        { id: 'c', label: 'C', href: '/c' },
+      ];
+      render(<Breadcrumbs items={custom} />);
+      const bElement = screen.getByText('B').closest('span');
+      expect(bElement?.getAttribute('aria-current')).toBe('page');
+    });
+  });
+
+  describe('separator', () => {
+    it('inserts the default `/` between crumbs', () => {
+      const { container } = render(<Breadcrumbs items={trail} />);
+      const separators = container.querySelectorAll('[aria-hidden="true"]');
+      // 2 separators between 3 crumbs.
+      expect(separators).toHaveLength(2);
+      expect(separators[0].textContent).toBe('/');
+    });
+
+    it('accepts a custom separator (string)', () => {
+      const { container } = render(
+        <Breadcrumbs items={trail} separator=">" />
+      );
+      const separators = container.querySelectorAll('[aria-hidden="true"]');
+      expect(separators[0].textContent).toBe('>');
+    });
+
+    it('accepts a custom separator (ReactNode)', () => {
+      render(
+        <Breadcrumbs
+          items={trail}
+          separator={<span data-testid="sep">»</span>}
+        />
+      );
+      // Two separators ⇒ two custom nodes.
+      expect(screen.getAllByTestId('sep')).toHaveLength(2);
+    });
+  });
+
+  describe('navigation links', () => {
+    it('renders a non-current crumb with href as a real link', () => {
+      render(<Breadcrumbs items={trail} />);
+      const link = screen.getByRole('link', { name: 'Home' });
+      expect(link.getAttribute('href')).toBe('/');
+    });
+
+    it('renders a crumb without href as a non-link span', () => {
+      const noHref: BreadcrumbItem[] = [
+        { id: 'a', label: 'A' },
+        { id: 'b', label: 'B' },
+      ];
+      render(<Breadcrumbs items={noHref} />);
+      expect(screen.queryByRole('link')).toBeNull();
+    });
+
+    it('fires onClick on link crumbs', () => {
+      const onClick = vi.fn();
+      const itemsWithClick: BreadcrumbItem[] = [
+        { id: 'a', label: 'A', href: '/a', onClick },
+        { id: 'b', label: 'B' },
+      ];
+      render(<Breadcrumbs items={itemsWithClick} />);
+      fireEvent.click(screen.getByText('A'));
+      expect(onClick).toHaveBeenCalled();
+    });
+
+    it('renders a disabled crumb as a non-interactive span', () => {
+      const dis: BreadcrumbItem[] = [
+        { id: 'a', label: 'A', href: '/a', disabled: true },
+        { id: 'b', label: 'B' },
+      ];
+      render(<Breadcrumbs items={dis} />);
+      // 'A' must not be a link (disabled overrides interactivity).
+      expect(screen.queryByRole('link', { name: 'A' })).toBeNull();
+      const span = screen.getByText('A').closest('span');
+      expect(span?.getAttribute('aria-disabled')).toBe('true');
+    });
+  });
+
+  describe('truncation', () => {
+    const long: BreadcrumbItem[] = Array.from({ length: 6 }, (_, i) => ({
+      id: `c${i}`,
+      label: `Crumb ${i}`,
+      href: i === 5 ? undefined : `/c${i}`,
+    }));
+
+    it('collapses the middle when items > maxItems', () => {
+      const { container } = render(
+        <Breadcrumbs items={long} maxItems={3} />
+      );
+      // 1 (head) + 1 ellipsis + 1 (tail) = 3 <li>s.
+      expect(container.querySelectorAll('li')).toHaveLength(3);
+      expect(
+        container.querySelector('[aria-label="More breadcrumbs"]')
+      ).toBeTruthy();
+    });
+
+    it('respects itemsBeforeCollapse / itemsAfterCollapse', () => {
+      const { container } = render(
+        <Breadcrumbs
+          items={long}
+          maxItems={4}
+          itemsBeforeCollapse={2}
+          itemsAfterCollapse={2}
+        />
+      );
+      // 2 head + 1 ellipsis + 2 tail = 5 <li>s.
+      // (maxItems is the visible-budget hint; once collapsed the
+      // before/after counts drive the final visible count.)
+      expect(container.querySelectorAll('li')).toHaveLength(5);
+    });
+
+    it('does NOT collapse when items.length <= maxItems', () => {
+      const { container } = render(
+        <Breadcrumbs items={trail} maxItems={10} />
+      );
+      expect(container.querySelectorAll('li')).toHaveLength(3);
+      expect(
+        container.querySelector('[aria-label="More breadcrumbs"]')
+      ).toBeNull();
+    });
+
+    it('does NOT collapse when maxItems is 0 (default)', () => {
+      const { container } = render(<Breadcrumbs items={long} />);
+      expect(container.querySelectorAll('li')).toHaveLength(6);
+    });
+
+    it('preserves the LAST crumb (current page) when collapsing', () => {
+      render(<Breadcrumbs items={long} maxItems={3} />);
+      expect(screen.getByText('Crumb 0')).toBeTruthy(); // first
+      expect(screen.getByText('Crumb 5')).toBeTruthy(); // last/current
+      expect(screen.queryByText('Crumb 2')).toBeNull(); // middle, collapsed
+    });
+  });
+
+  describe('polymorphic link component', () => {
+    it('uses the provided linkComponent instead of <a>', () => {
+      const MyLink = vi.fn(
+        ({ children, ...rest }: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+          <a data-testid="custom-link" {...rest}>
+            {children}
+          </a>
+        )
+      );
+      render(<Breadcrumbs items={trail} linkComponent={MyLink} />);
+      // Two interactive crumbs ⇒ MyLink called twice.
+      expect(MyLink).toHaveBeenCalledTimes(2);
+      expect(screen.getAllByTestId('custom-link')).toHaveLength(2);
+    });
+  });
+
+  describe('size variants', () => {
+    it('renders sm / md / lg without throwing', () => {
+      const sizes = ['sm', 'md', 'lg'] as const;
+      sizes.forEach((s) => {
+        const { unmount } = render(
+          <Breadcrumbs items={trail} size={s} />
+        );
+        expect(
+          screen.getByRole('navigation', { name: 'Breadcrumb' })
+        ).toBeTruthy();
+        unmount();
+      });
+    });
+  });
+
+  describe('aria-label override', () => {
+    it('applies a custom aria-label to the nav landmark', () => {
+      render(<Breadcrumbs items={trail} ariaLabel="Sentiero corrente" />);
+      expect(
+        screen.getByRole('navigation', { name: 'Sentiero corrente' })
+      ).toBeTruthy();
+    });
+  });
+});